container.java

j2me is based on j2mepolish, client & server for mobile application. menu sample

//#condition polish.usePolishGui
/*
 * Created on 01-Mar-2004 at 09:45:32.
 *
 * Copyright (c) 2004-2005 Robert Virkus / Enough Software
 *
 * This file is part of J2ME Polish.
 *
 * J2ME Polish is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * J2ME Polish is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with J2ME Polish; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 * 
 * Commercial licenses are also available, please
 * refer to the accompanying LICENSE.txt or visit
 * http://www.j2mepolish.org for details.
 */
package de.enough.polish.ui;

import javax.microedition.lcdui.Canvas;
import javax.microedition.lcdui.Graphics;

import de.enough.polish.util.ArrayList;

/**
 * <p>Contains a number of items.</p>
 * <p>Main purpose is to manage all items of a Form or similiar canvases.</p>
 * <p>Containers support following additional CSS attributes:
 * </p>
 * <ul>
 * 		<li><b>columns</b>: The number of columns. If defined a table will be drawn.</li>
 * 		<li><b>columns-width</b>: The width of the columns. "equals" for an equal width
 * 				of each column, "normal" for a column width which depends on
 * 			    the items. One can also specify the used widths directly with
 * 				a comma separated list of integers, e.g.
 * 				<pre>
 * 					columns: 2;
 * 					columns-width: 15,5;
 * 				</pre>
 * 				</li>
 * 		<li><b>scroll-mode</b>: Either "smooth" (=default) or "normal".</li>
 * </ul>
 * <p>Copyright Enough Software 2004, 2005</p>

 * <pre>
 * history
 *        01-Mar-2004 - rob creation
 * </pre>
 * @author Robert Virkus, [e-mail]
 */
public class Container extends Item {
	//#if polish.css.columns || polish.useTable
		//#define tmp.useTable
	//#endif
	
	/** constant for normal scrolling (0) */
	public static final int SCROLL_DEFAULT = 0;
	/** constant for smooth scrolling (1) */
	public static final int SCROLL_SMOOTH = 1;
	
	protected ArrayList itemsList;
	protected Item[] items;
	protected boolean autoFocusEnabled;
	protected int autoFocusIndex;
	protected Style itemStyle;
	protected Item focusedItem;
	public int focusedIndex = -1;
	protected boolean enableScrolling;
	//#if polish.Container.allowCycling != false
		public boolean allowCycling = true;
	//#endif
	protected int yOffset;
	protected int targetYOffset;
	private int focusedTopMargin;
	//#if polish.css.view-type || polish.css.columns
		//#define tmp.supportViewType 
		protected ContainerView containerView;
	//#endif
	//#ifdef polish.css.scroll-mode
		//# protected boolean scrollSmooth = true;
	//#endif
	private boolean isScrollRequired;
	/** The height available for scrolling, ignore when set to -1 */
	protected int availableHeight = -1;	

	
	/**
	 * Creates a new empty container.
	 * 
	 * @param focusFirstElement true when the first focussable element should be focused automatically.
	 */
	public Container( boolean focusFirstElement ) {
		this( null, focusFirstElement, null, -1 );
	}
	
	/**
	 * Creates a new empty container.
	 * 
	 * @param focusFirstElement true when the first focussable element should be focused automatically.
	 * @param style the style for this container
	 */
	public Container(boolean focusFirstElement, Style style) {
		this( null, focusFirstElement, style, -1  );
	}

	/**
	 * Creates a new empty container.
	 * 
	 * @param label the label of this container
	 * @param focusFirstElement true when the first focussable element should be focused automatically.
	 * @param style the style for this container
	 * @param height the vertical space available for this container, set to -1 when scrolling should not be activated
	 * @see #setScrollHeight( int ) 
	 */
	public Container(String label, boolean focusFirstElement, Style style, int height ) {
		super( label, LAYOUT_DEFAULT, INTERACTIVE, style );
		this.itemsList = new ArrayList();
		this.autoFocusEnabled = focusFirstElement;
		Style focStyle = StyleSheet.focusedStyle;
		//#if false
			//# // this code is needed for the JUnit tests only:
			//# if (focStyle == null) {
				//# focStyle = new Style( 1, 1, 1, 1,
						//# 0, 0, 0, 0, 0, 0,
						//# 0, 0x0, null, null, null, null, null, null
				//# );
			//# }
		//#endif
		this.focusedStyle = focStyle;
		this.focusedTopMargin = focStyle.marginTop + focStyle.paddingTop;
		if (focStyle.border != null) {
			this.focusedTopMargin += focStyle.border.borderWidth;
		} 
		if (focStyle.background != null) {
			this.focusedTopMargin += focStyle.background.borderWidth;
		}
		this.layout |= Item.LAYOUT_NEWLINE_BEFORE;
		setScrollHeight( height );
	}
	
	/**
	 * Sets the height available for scrolling of this item.
	 * 
	 * @param height available height for this item including label, padding, margin and border, -1 when scrolling should not be done.
	 */
	public void setScrollHeight( int height ) {
		this.availableHeight = height;
		this.enableScrolling = (height != -1);
	}
	
	/**
	 * Adds an item to this container.
	 * 
	 * @param item the item which should be added.
	 * @throws IllegalArgumentException when the given item is null
	 */
	public void add( Item item ) {
		item.relativeY =  0;
		item.internalX = -9999;
		item.parent = this;
		this.itemsList.add( item );
		if (this.isInitialized) {
			this.isInitialized = false;
			repaint();
		}
	}

	/**
	 * Inserts the given item at the defined position.
	 * Any following elements are shifted one position to the back.
	 * 
	 * @param index the position at which the element should be inserted, 
	 * 					 use 0 when the element should be inserted in the front of this list.
	 * @param item the item which should be inserted
	 * @throws IllegalArgumentException when the given item is null
	 * @throws IndexOutOfBoundsException when the index < 0 || index >= size()
	 */
	public void add( int index, Item item ) {
		item.relativeY = 0;
		item.internalX = -9999;
		item.parent = this;
		this.itemsList.add( index, item );
		if (index <= this.focusedIndex) {
			this.focusedIndex++;
		}
		if (this.isInitialized) {
			this.isInitialized = false;
			repaint();
		}
	}
	
	//#if polish.LibraryBuild
	//# public void add( javax.microedition.lcdui.Item item ) {
		//# // ignore
	//# }
	//# public void add( int index, javax.microedition.lcdui.Item item ) {
		//# // ignore
	//# }
	//#endif
	
	/**
	 * Replaces the item at the specified position in this list with the given item. 
	 * 
	 * @param index the position of the element, the first element has the index 0.
	 * @param item the item which should be set
	 * @return the replaced item
	 * @throws IndexOutOfBoundsException when the index < 0 || index >= size()
	 */
	public Item set( int index, Item item ) {
		//#debug
		//# System.out.println("Container: setting item " + index + " " + item.toString() );
		item.parent = this;
		Item last = (Item) this.itemsList.set( index, item );
		if (index == this.focusedIndex) {
			last.defocus(this.itemStyle);
			if ( item.appearanceMode != PLAIN ) {
				this.itemStyle = item.focus( this.focusedStyle, 0 );
			}
		}
		if (this.isInitialized) {
			this.isInitialized = false;
			repaint();
		}
		return last;
	}
	
	/**
	 * Returns the item at the specified position of this container.
	 *  
	 * @param index the position of the desired item.
	 * @return the item stored at the given position
	 * @throws IndexOutOfBoundsException when the index < 0 || index >= size()
	 */
	public Item get( int index ) {
		return (Item) this.itemsList.get( index );
	}
	
	/**
	 * Removes the item at the specified position of this container.
	 *  
	 * @param index the position of the desired item.
	 * @return the item stored at the given position
	 * @throws IndexOutOfBoundsException when the index < 0 || index >= size()
	 */
	public Item remove( int index ) {
		Item removedItem = (Item) this.itemsList.remove(index);
		//#debug
		//# System.out.println("Container: removing item " + index + " " + removedItem.toString()  );
		// adjust y-positions of following items:
		Item[] myItems = (Item[]) this.itemsList.toArray( new Item[ this.itemsList.size() ]);
		for (int i = 0; i < myItems.length; i++) {
			Item item = myItems[i];
			item.internalX = -9999;
			item.relativeY = 0;
			/*
			 int removedItemHeight = removedItem.itemHeight;
			if (item.yTopPos != item.yBottomPos) {
				item.yTopPos -= removedItemHeight;
				item.yBottomPos -= removedItemHeight;
			}*/
		}
		// check if the currenlty focused item has been removed:
		if (index == this.focusedIndex) {
			// remove any items:
			Screen scr = getScreen();
			if (scr != null) {
				scr.removeItemCommands(removedItem);
			}
			// focus the first possible item:
			boolean focusSet = false;
			for (int i = 0; i < myItems.length; i++) {
				Item item = myItems[i];
				if (item.appearanceMode != PLAIN) {
					focus( i, item, Canvas.DOWN );
					focusSet = true;
					break;
				}
			}
			if (!focusSet) {
				this.autoFocusEnabled = true;
				this.focusedItem = null;
				this.focusedIndex = -1;
			}
		} else if (index < this.focusedIndex) {
			this.focusedIndex--;
		}
		this.yOffset = 0;
		this.targetYOffset = 0;
		if (this.isInitialized) {
			this.isInitialized = false;
			repaint();
		}
		return removedItem;
	}
	
	/**
	 * Removes the given item.
	 * 
	 * @param item the item which should be removed.
	 * @return true when the item was found in this list.
	 * @throws IllegalArgumentException when the given item is null
	 */
	public boolean remove( Item item ) {
		int index = this.itemsList.indexOf(item);
		if (index != -1) {
			remove( index );
			return true;
		} else {
			return false;
		}
	}
	
	/**
	 * Removes all items from this container.
	 */
	public void clear() {
		this.itemsList.clear();
		this.items = new Item[0];
		if (this.focusedIndex != -1) {
			this.autoFocusEnabled = this.isFocused;
			//#if polish.Container.clearResetsFocus != false
				this.autoFocusIndex = 0;
			//#else
				//# this.autoFocusIndex = this.focusedIndex;
			//#endif			
			this.focusedIndex = -1;
			if (this.focusedItem != null) {
				if (this.focusedItem.commands != null) {
					Screen scr = getScreen();
					if (scr != null) {
						scr.removeItemCommands(this.focusedItem);
					}
				}
				if (this.itemStyle != null) {
					this.focusedItem.defocus(this.itemStyle);
				}
			}
			this.focusedItem = null;
		}
		this.yOffset = 0;
		this.targetYOffset = 0;
		if (this.internalX != -9999) {
			this.internalX = -9999;
			this.internalY = 0;
			// adjust scrolling:
			if ( this.isFocused && this.parent instanceof Container ) {
				Container parentContainer = (Container) this.parent;
				int scrollOffset = - parentContainer.getScrollYOffset();
				if (scrollOffset > this.relativeY) {
					int diff = scrollOffset - this.relativeY;
					parentContainer.setScrollYOffset( diff - scrollOffset,  false );
				}
			}