totalcross.ui
Class Container

totalcross.lang.Object
  totalcross.ui.gfx.GfxSurface
      totalcross.ui.Control
          totalcross.ui.Container

Direct Known Subclasses:

AlignedLabelsContainer, ComboBox, GPS, Grid, HtmlContainer, ListBox, MultiEdit, ScrollBar, ScrollContainer, ScrollContainer.ClippedContainer, TabbedContainer, Tree, Window

public class Container
extends Control

Container is a control that contains child controls.

Field Summary

boolean	alwaysEraseBackground Set to true to always erase the background when repainting this container.
static byte	BORDER_LOWERED used in the setBorderStyle method
static byte	BORDER_NONE used in the setBorderStyle method
static byte	BORDER_RAISED used in the setBorderStyle method
static byte	BORDER_SIMPLE used in the setBorderStyle method
protected Control	children The children of the container.
protected static boolean	controlFound Returns true if the control was found in findChild, false otherwise.
protected boolean	finishedStart
protected boolean	ignoreOnAddAgain Set to true to avoid calling the methods onRemove or onAddAgain
protected boolean	ignoreOnRemove Set to true to avoid calling the methods onRemove or onAddAgain
protected Insets	insets The insets of this container.
protected int	lastH
protected int	lastScreenWidth
protected int	lastW
protected int	lastX
protected int	lastY
static int	nextTransitionEffect The transition effect to apply in the next screen update.
protected boolean	started
Vector	tabOrder Holds the controls that will be used to transfer focus when the tab key is pressed.
protected Control	tail The tail of the children list.
static int	TRANSITION_CLOSE Used when animating the exhibition of a container.
static int	TRANSITION_NONE Used when animating the exhibition of a container.
static int	TRANSITION_OPEN Used when animating the exhibition of a container.
int	transitionEffect Set the transition effect when this container appears on screen.

Fields inherited from class totalcross.ui.Control

AFTER, appId, appObj, asContainer, asWindow, backColor, BEFORE, BOTTOM, BOTTOM_OF, CENTER, CENTER_OF, clearValueInt, clearValueStr, enabled, enableUpdateScreen, FILL, FIT, fm, fmH, focusHandler, focusLess, focusOnPenDown, focusTraversable, font, foreColor, height, isHighlighting, KEEP, LEFT, onEventFirst, parent, PREFERRED, RANGE, repositionAllowed, RIGHT, RIGHT_OF, SAME, setFont, setH, setRel, setW, setX, setY, TOP, transparentBackground, uiCE, uiFlat, uiPalm, uiVista, visible, width, WILL_RESIZE, x, y

Constructor Summary

Container()
Creates a container with the default colors.

Method Summary

void	add(Control control) Adds a child control to this container.
void	add(Control control, int x, int y) Add the control to this container and set its rect to be the given x,y and PREFERRED as width/height relative to the last control added Same of add(control); control.setRect(x,y,PREFERRED,PREFERRED, null,false);
void	add(Control control, int x, int y, Control relative) Add the control to this container and set its rect to be the given x,y and PREFERRED as width/height relative to the given control Same of add(control); control.setRect(x,y,PREFERRED,PREFERRED, relative,false);
void	add(Control control, int x, int y, int w, int h) Adds the control to this container, using the given bounds, relative to the last control added Same of add(control); control.setRect(x,y,w,h, null,false);
void	add(Control control, int x, int y, int w, int h, Control relative) Adds the control to this container, using the given bounds, relative to the given control.
void	broadcastEvent(Event e) Posts an event to the children of this container and to all containers inside this containers; recursively.
void	clear() Clears all children controls that are focusTraversable, recursively.
Control	findChild(int x, int y) Returns the child located at the given x and y coordinates.
Control	findNearestChild(int x, int y, int minDistance)
Control	findNextFocusControl(Control c, int direction) Finds the next control that should receive focus based on the direction with respect to c.
byte	getBorderStyle() Returns the border style.
Control[]	getChildren() Return an array of Controls that are added to this Container.
Rect	getClientRect() Returns the client rect for this Container, in relative coords.
protected void	getClientRect(Rect r) Returns the client rect for this Container, in relative coords, excluding the insets.
void	getFocusableControls(Vector v) Get a list of child controls of this container which are focus candidates
void	getInsets(Insets copyInto) Copy the current insets values into the given insets.
void	incLastX(int n) Increments the lastX, used in relative positioning.
void	incLastY(int n) Increments the lastY, used in relative positioning.
void	initUI() Called to initialize the User Interface of this container.
protected void	onAddAgain() When the container is added for the first time, the method initUI is called, so the user interface can be initialized.
protected void	onColorsChanged(boolean colorsChanged) Called after a setEnabled, setForeColor and setBackColor and when a control has been added to a Container.
void	onPaint(Graphics g) Draws the border (if any).
protected void	onRemove() Called when this container is removed from the parent.
void	paintChildren() Called by the system to draw the children of the container.
void	remove(Control control) Removes a child control from the container.
void	removeAll() Removes all controls inside this container.
void	resize() This method resizes the Container's width and height to the needed bounds, based on added childs.
void	resizeHeight() This method resizes the Container's width to the needed bounds, based on added childs.
void	resizeWidth() This method resizes the Container's width to the needed bounds, based on added childs.
void	setBorderStyle(byte border) Sets the border for this container.
void	setEnabled(boolean enabled) Sets if this container and all childrens can or not accept events
void	setHighlighting() Called by the event dispatcher to set highlighting back to true.
void	setInsets(int left, int right, int top, int bottom) Sets the insets value to match the given ones.
void	swapToTopmostWindow() Call this method to swap this Container to the topmost window.

Methods inherited from class totalcross.ui.Control

_onEvent, addFocusListener, addGridListener, addHighlightListener, addKeyListener, addPenListener, addPressListener, addTimer, addTimer, addTimerListener, addWindowListener, changeHighlighted, contains, getAbsoluteRect, getBackColor, getEventListeners, getFont, getForeColor, getGraphics, getHeight, getNext, getParent, getParentWindow, getPos, getPreferredHeight, getPreferredWidth, getPressedEvent, getPrev, getRect, getSize, getWidth, getX, getX2, getY, getY2, handleGeographicalFocusChangeKeys, isDisplayed, isEnabled, isInsideOrNear, isVisible, isVisibleAndInside, onBoundsChanged, onEvent, onFontChanged, onWindowPaintFinished, postEvent, postPressedEvent, removeFocusListener, removeGridListener, removeHighlightListener, removeKeyListener, removePenListener, removePressListener, removeTimer, removeTimerListener, removeWindowListener, repaint, repaintNow, reposition, reposition, requestFocus, setBackColor, setBackForeColors, setFocusLess, setFont, setForeColor, setRect, setRect, setRect, setRect, setVisible, translateFromOrigin, uiStyleChanged, updateScreen, updateTemporary

Methods inherited from class totalcross.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

children

protected Control children

The children of the container.

tail

protected Control tail

The tail of the children list.

BORDER_NONE

public static final byte BORDER_NONE

used in the setBorderStyle method

See Also:

Constant Field Values

BORDER_LOWERED

public static final byte BORDER_LOWERED

used in the setBorderStyle method

See Also:

Constant Field Values

BORDER_RAISED

public static final byte BORDER_RAISED

used in the setBorderStyle method

See Also:

Constant Field Values

BORDER_SIMPLE

public static final byte BORDER_SIMPLE

used in the setBorderStyle method

See Also:

Constant Field Values

TRANSITION_NONE

public static final int TRANSITION_NONE

Used when animating the exhibition of a container.

See Also:

Constant Field Values

TRANSITION_OPEN

public static final int TRANSITION_OPEN

Used when animating the exhibition of a container.

See Also:

Constant Field Values

TRANSITION_CLOSE

public static final int TRANSITION_CLOSE

Used when animating the exhibition of a container.

See Also:

Constant Field Values

transitionEffect

public int transitionEffect

Set the transition effect when this container appears on screen. Defaults to Control.UPDATESCREEN_AT_ONCE, which means no transition effects. The transition is applied by the popup/unpop methods (if this container is a Window), or in the swap method (otherwise).

See the UIGadgets and the ContainerSwitch samples in the SDK.

Since:

TotalCross 1.2

See Also:

TRANSITION_NONE, TRANSITION_OPEN, TRANSITION_CLOSE, Window.swap(Container), Window.popup(), Window.unpop(), nextTransitionEffect

nextTransitionEffect

public static int nextTransitionEffect

The transition effect to apply in the next screen update. After this effect is applied, the next effect is set to TRANSITION_NONE.

Since:

TotalCross 1.2

See Also:

transitionEffect, TRANSITION_NONE, TRANSITION_OPEN, TRANSITION_CLOSE

lastX

protected int lastX

lastY

protected int lastY

lastW

protected int lastW

lastH

protected int lastH

started

protected boolean started

ignoreOnRemove

protected boolean ignoreOnRemove

Set to true to avoid calling the methods onRemove or onAddAgain

ignoreOnAddAgain

protected boolean ignoreOnAddAgain

Set to true to avoid calling the methods onRemove or onAddAgain

finishedStart

protected boolean finishedStart

tabOrder

public Vector tabOrder

Holds the controls that will be used to transfer focus when the tab key is pressed. You can add or remove controls from here, but be careful not to add repeated controls.

Since:

SuperWaba 5.5

lastScreenWidth

protected int lastScreenWidth

insets

protected Insets insets

The insets of this container. Never change it directly, otherwise some controls may not work correctly; use setInsets instead.

See Also:

setInsets(int, int, int, int)

alwaysEraseBackground

public boolean alwaysEraseBackground

Set to true to always erase the background when repainting this container.

Since:

TotalCross 1.0

controlFound

protected static boolean controlFound

Returns true if the control was found in findChild, false otherwise.

Since:

TotalCross 1.2

Constructor Detail

Container

public Container()

Creates a container with the default colors. Important note: this container has no default size.

NEVER INITIALIZE THE USER INTERFACE IN THE CONSTRUCTOR

If you're extending the Container class and adding controls in its constructor, you may come into problems if you don't set the bounds as the first thing.

Method Detail

setInsets

public void setInsets(int left,
                      int right,
                      int top,
                      int bottom)

Sets the insets value to match the given ones.

Since:

TotalCross 1.01

getInsets

public void getInsets(Insets copyInto)

Copy the current insets values into the given insets. If you call this method often, create an Insets field and reuse it.

Parameters:

copyInto - The created object where the insets values will be copied into.

Since:

TotalCross 1.01

add

public void add(Control control,
                int x,
                int y,
                int w,
                int h)

Adds the control to this container, using the given bounds, relative to the last control added Same of

 add(control);
 control.setRect(x,y,w,h, null,false);
 

See Also:

Control.setRect(int, int, int, int, Control, boolean)

add

public void add(Control control,
                int x,
                int y,
                int w,
                int h,
                Control relative)

Adds the control to this container, using the given bounds, relative to the given control. Same of

 add(control);
 control.setRect(x,y,w,h, relative,false);
 

See Also:

Control.setRect(int, int, int, int, Control, boolean)

add

public void add(Control control,
                int x,
                int y)

Add the control to this container and set its rect to be the given x,y and PREFERRED as width/height relative to the last control added Same of

 add(control);
 control.setRect(x,y,PREFERRED,PREFERRED, null,false);
 

See Also:

Control.setRect(int, int, int, int, Control, boolean)

add

public void add(Control control,
                int x,
                int y,
                Control relative)

Add the control to this container and set its rect to be the given x,y and PREFERRED as width/height relative to the given control Same of

 add(control);
 control.setRect(x,y,PREFERRED,PREFERRED, relative,false);
 

See Also:

Control.setRect(int, int, int, int, Control, boolean)

add

public void add(Control control)

Adds a child control to this container. Important: If you're swapping containers from the MainWindow, be sure that you set the focus on the new container after calling this add method. Otherwise, a MenuBar will not work. Or, use the handy method Window.swap

remove

public void remove(Control control)

Removes a child control from the container.

findChild

public Control findChild(int x,
                         int y)

Returns the child located at the given x and y coordinates. Usually, if a control is not found, the last visited container is returned. In this case, controlFound is set to false.

See Also:

controlFound

findNearestChild

public Control findNearestChild(int x,
                                int y,
                                int minDistance)

getChildren

public Control[] getChildren()

Return an array of Controls that are added to this Container. If there are no Controls, returns null.

setEnabled

public void setEnabled(boolean enabled)

Sets if this container and all childrens can or not accept events

Overrides:

setEnabled in class Control

broadcastEvent

public void broadcastEvent(Event e)

Posts an event to the children of this container and to all containers inside this containers; recursively.

Since:

SuperWaba 2.0 beta 4

paintChildren

public void paintChildren()

Called by the system to draw the children of the container.

setBorderStyle

public void setBorderStyle(byte border)

Sets the border for this container. The insets are changed after this method is called.

See Also:

BORDER_NONE, BORDER_LOWERED, BORDER_RAISED, BORDER_SIMPLE

getClientRect

public Rect getClientRect()

Returns the client rect for this Container, in relative coords. The client rectangle usually excludes the title (if applicable) and the border. If you call this method often, consider using the other version, where a cached Rect is used; it avoids the creation of a Rect.

See Also:

getClientRect(Rect)

getClientRect

protected void getClientRect(Rect r)

Returns the client rect for this Container, in relative coords, excluding the insets. In this version, you provide the instantiated Rect to be filled with the coords.

onColorsChanged

protected void onColorsChanged(boolean colorsChanged)

Description copied from class: Control

Called after a setEnabled, setForeColor and setBackColor and when a control has been added to a Container. If colorsChanged is true, it was called from setForeColor/setBackColor/Container.add; otherwise, it was called from setEnabled

Overrides:

onColorsChanged in class Control

onPaint

public void onPaint(Graphics g)

Draws the border (if any). If you override this method, be sure to call super.onPaint(g);, or the border will not be drawn.

Overrides:

onPaint in class Control

Parameters:

g - the graphics object for drawing

See Also:

Graphics

onAddAgain

protected void onAddAgain()

When the container is added for the first time, the method initUI is called, so the user interface can be initialized. From the second time and up that the container is added, the onAddAgain method is called instead.

If this container is a window, this method is not called when the window is popped.

If you don't want this method to be called, you must set ignoreOnAddAgain = true; inside the method initUI or the class constructor. Doing so makes the user interface initialize faster.

Since:

SuperWaba 4.1

onRemove

protected void onRemove()

Called when this container is removed from the parent. Note that, if this container is a window, this method is not called when the window is unpopped.

If you don't want this method to be called, you must set ignoreOnRemove = true; inside the method initUI or the class constructor. Doing so makes the user interface initialize faster.

Since:

SuperWaba 4.1

initUI

public void initUI()

Called to initialize the User Interface of this container. This differs from the onAddAgain method by that this method is called only once, at the first time the control is added to the parent. When the container is being setup, the initUI method is called; then, the onAddAgain is called every time the container is added again.

Since:

SuperWaba 3.4

setHighlighting

public void setHighlighting()

Called by the event dispatcher to set highlighting back to true. A class may extend this to decide when its time to turn it on again or not.

swapToTopmostWindow

public void swapToTopmostWindow()

Call this method to swap this Container to the topmost window. Note that since we have no idea who is our future parent window, we just use the topmost window. The topmost window is the one that is currently visible.
This method is useful if you have containers that are SINGLETONS and wish to set them as the current container. E.G.:

 public class MainMenu extends Container // create a Singleton from MainMenu
 {
    private static instance;
    public static getInstance()
    {
       return instance != null ? instance : (instance=new MainMenu());
    }
    private MainMenu()
    {
    }
  }
  // then at some other class, you can do:
  MainMenu.getInstance().swapToTopmostWindow();
  

Since:

SuperWaba 5.7

clear

public void clear()

Clears all children controls that are focusTraversable, recursively.

Overrides:

clear in class Control

getFocusableControls

public void getFocusableControls(Vector v)

Get a list of child controls of this container which are focus candidates

Parameters:

v - A vector into which to add the focus candidates.

findNextFocusControl

public Control findNextFocusControl(Control c,
                                    int direction)

Finds the next control that should receive focus based on the direction with respect to c.

Parameters:

c - The reference control from which to find the next control.

direction - The direction in which to look from c. One of: SpecialKeys.LEFT, SpecialKeys.RIGHT, SpecialKeys.UP, SpecialKeys.DOWN

Returns:

The control which should receive focus next, or null.

See Also:

Settings.geographicalFocus

getBorderStyle

public byte getBorderStyle()

Returns the border style.

removeAll

public void removeAll()

Removes all controls inside this container.

Since:

TotalCross 1.0

incLastX

public void incLastX(int n)

Increments the lastX, used in relative positioning.

incLastY

public void incLastY(int n)

Increments the lastY, used in relative positioning.

resize

public void resize()

This method resizes the Container's width and height to the needed bounds, based on added childs. You can add spaces at right and bottom using the insets.right/bottom properties. Sample:

   // this sample will center two buttons of different sizes on screen 
   Container c = new Container();
   add(c, CENTER,BOTTOM,1000,1000);
   c.add(new Button("Ok"),LEFT,TOP);
   c.add(new Button("Cancel"),AFTER+5,SAME);
   c.resize();
 

Note: differently of Window.resize, this method does not call setRect again, it only changes the width and height by direct assignment.

Since:

TotalCross 1.14

See Also:

resizeWidth(), resizeHeight()

resizeWidth

public void resizeWidth()

This method resizes the Container's width to the needed bounds, based on added childs. You can add spaces at right using the insets.right property. Sample:

   // this sample will center two buttons of different sizes on screen 
   Container c = new Container();
   add(c, CENTER,BOTTOM,1000,1000);
   c.add(new Button("Ok"),LEFT,TOP);
   c.add(new Button("Cancel"),AFTER+5,SAME);
   c.resize();
 

Note: differently of Window.resize, this method does not call setRect again, it only changes the width by direct assignment.

Since:

TotalCross 1.14

See Also:

resize(), resizeHeight()

resizeHeight

public void resizeHeight()

This method resizes the Container's width to the needed bounds, based on added childs. You can add spaces at bottom using the insets.bottom property. Sample:

   // this sample will center two buttons of different sizes on screen 
   Container c = new Container();
   add(c, CENTER,BOTTOM,1000,1000);
   c.add(new Button("Ok"),LEFT,TOP);
   c.add(new Button("Cancel"),AFTER+5,SAME);
   c.resize();
 

Note: differently of Window.resize, this method does not call setRect again, it only changes the height by direct assignment.

Since:

TotalCross 1.14

See Also:

resizeWidth(), resize()