ej.mwt

Class Composite

java.lang.Object

ej.mwt.Widget

ej.mwt.Composite

All Implemented Interfaces:

Renderable

public abstract class Composite
extends Widget

A composite is a widget that can contain other Widget instances, following the composite pattern.

The children are stored in a list. The order of the list defines the front-to-back stacking order of the widgets within the composite. The first widget in the list is at the back of the stacking order.

A widget cannot be added two times in a hierarchy.

Constructor Summary

Constructors

Constructor and Description
Composite() Creates a new composite. Its bounds will be set to 0.

Method Summary

Modifier and Type	Method and Description
protected void	add(Widget widget) Adds the specified widget to the end of the list of children of this composite.
Widget	getFocus() Gets the widget that is the focus owner or that owns (recursively) the focus owner in this composite.
int	getFocusIndex() Gets the index of the widget that is the focus owner or that is (recursively) the focus owner parent in the composite.
int	getNext(int from, int direction) Gets the next widget in the focus order following the direction. If there is no more widget to focus in this direction, it returns MWT.EMPTY. The given direction must be one of MWT.UP, MWT.DOWN, MWT.LEFT, MWT.RIGHT.
Widget	getWidget(int index) Gets the widget at the specified position in this composite.
Widget	getWidgetAt(int x, int y) Returns the child widget that is at the specified location.
Widget[]	getWidgets() Gets the list of children in this composite.
int	getWidgetsCount() Gets the number of children in this composite.
boolean	handleEvent(int event) Called by the system if a child of this composite is the owner of the focus of the active panel (recursively) and have not consumed the specified event.
boolean	hasFocus() Gets whether or not this composite or one of its children (recursively) is the focus owner of its panel.
void	hideNotify() This method is called as soon as the renderable is hidden.
java.util.Iterator<Widget>	iterator() Gets an iterator over the composite children widgets in proper sequence.
protected void	remove(Widget widget) Removes the specified widget from the list of children of this composite.
protected void	removeAllWidgets() Removes all the widgets from the list of children of this composite.
void	requestFocus() Requests that the first child of this composite be set as the focus owner of its panel.
boolean	requestFocus(int direction) Sets a widget in this composite as the focus owner of its panel, if it is enabled, following the direction. The given direction must be one of MWT.UP, MWT.DOWN, MWT.LEFT, MWT.RIGHT. If the widget is not in a panel hierarchy, nothing is done.
boolean	requestFocusFrom(int from, int direction) Gives the focus to the first enabled widget that is in the list of this composite's children from the widget at the specified index following the direction. The given direction must be one of MWT.UP, MWT.DOWN, MWT.LEFT, MWT.RIGHT.
void	showNotify() This method is called as soon as the renderable is visible.
abstract void	validate(int widthHint, int heightHint) Lays out this composite and all its children.

Methods inherited from class ej.mwt.Widget

contains, gainFocus, getAbsoluteX, getAbsoluteX, getAbsoluteY, getAbsoluteY, getEventHandler, getHeight, getPanel, getParent, getPreferredHeight, getPreferredWidth, getRelativeX, getRelativeY, getWidth, getX, getY, invalidate, isEnabled, isShown, isTransparent, isValid, isVisible, lostFocus, repaint, repaint, revalidate, setBounds, setEnabled, setEventHandler, setLocation, setPreferredSize, setSize, setVisible

Methods inherited from class java.lang.Object

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

Methods inherited from interface ej.mwt.Renderable

render

Constructor Detail

Composite

public Composite()

Creates a new composite.
Its bounds will be set to 0.

Method Detail

add

protected void add(Widget widget)
            throws java.lang.NullPointerException,
                   java.lang.IllegalArgumentException

Adds the specified widget to the end of the list of children of this composite.

If the composite is on a panel hierarchy, it is invalidated.

Parameters:

widget - the widget to add.

Throws:

java.lang.NullPointerException - if the specified widget is null.

java.lang.IllegalArgumentException - if the specified widget or one of its children is already connected to a Panel.

See Also:

Widget.invalidate()

remove

protected void remove(Widget widget)
               throws java.lang.NullPointerException

Removes the specified widget from the list of children of this composite.

If the composite is on a panel hierarchy, it is invalidated.

If the widget is not in the list of children of the composite, nothing is done.

Parameters:

widget - the widget to remove

Throws:

java.lang.NullPointerException - if the specified widget is null

See Also:

Widget.invalidate()

removeAllWidgets

protected void removeAllWidgets()

Removes all the widgets from the list of children of this composite.

If the composite is on a panel hierarchy, it is invalidated.

See Also:

Widget.invalidate()

showNotify

public void showNotify()

This method is called as soon as the renderable is visible.

Notifies its children widgets that they are shown.

Specified by:

showNotify in interface Renderable

Overrides:

showNotify in class Widget

hideNotify

public void hideNotify()

This method is called as soon as the renderable is hidden.

Notifies its children widgets that they are hidden.

Specified by:

hideNotify in interface Renderable

Overrides:

hideNotify in class Widget

getWidgetAt

public Widget getWidgetAt(int x,
                          int y)

Returns the child widget that is at the specified location.

If Widget.contains(int, int) is false for this composite, null is returned. Otherwise, if there is a child for which Widget.contains(int, int) returns true then the result of invoking Widget.getWidgetAt(int, int) on that widget is returned. Otherwise this composite is returned.

The location is relative to the location of this composite's parent.

Overrides:

getWidgetAt in class Widget

Parameters:

x - x coordinate

y - y coordinate

Returns:

the widget at the location, null if no widget is found in this composite hierarchy.

iterator

public java.util.Iterator<Widget> iterator()

Gets an iterator over the composite children widgets in proper sequence.

The Iterator.remove() is not implemented (throws a UnsupportedOperationException).

Returns:

an iterator over the composite children widgets in proper sequence.

Since:

2.0

getWidget

public Widget getWidget(int index)
                 throws java.lang.ArrayIndexOutOfBoundsException

Gets the widget at the specified position in this composite.

Parameters:

index - the index of the element to return.

Returns:

the widget at the specified position in this composite.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the index is out of range ((index < 0 || index >= getWidgetsCount())

getWidgets

public Widget[] getWidgets()

Gets the list of children in this composite.

Returns:

the list of children

getWidgetsCount

public int getWidgetsCount()

Gets the number of children in this composite.

Returns:

the number of children

hasFocus

public boolean hasFocus()

Gets whether or not this composite or one of its children (recursively) is the focus owner of its panel. Returns false if this composite is not on a panel.

Overrides:

hasFocus in class Widget

Returns:

true if this composite is a parent of the focus owner, false otherwise

See Also:

Panel.isActive()

requestFocus

public void requestFocus()

Requests that the first child of this composite be set as the focus owner of its panel.

If the composite does not contains any widgets, nothing is done.
If the composite is not in a panel hierarchy, nothing is done.

Identical to calling requestFocusFrom(int, int) with MWT.RIGHT as direction and 0 as from.

Overrides:

requestFocus in class Widget

requestFocus

public boolean requestFocus(int direction)
                     throws java.lang.IllegalArgumentException

Sets a widget in this composite as the focus owner of its panel, if it is enabled, following the direction.
The given direction must be one of MWT.UP, MWT.DOWN, MWT.LEFT, MWT.RIGHT.
If the widget is not in a panel hierarchy, nothing is done.

Identical to calling requestFocusFrom(int, int) with one of MWT.DOWN or MWT.RIGHT as direction and 0 as from, or one of MWT.LEFT or MWT.UP and (getWidgetsCount() - 1) as from.

Overrides:

requestFocus in class Widget

Parameters:

direction - the direction followed by the focus

Returns:

true if the composite take the focus, false otherwise

Throws:

java.lang.IllegalArgumentException - if direction is not a valid direction

requestFocusFrom

public boolean requestFocusFrom(int from,
                                int direction)
                         throws java.lang.ArrayIndexOutOfBoundsException,
                                java.lang.IllegalArgumentException

Gives the focus to the first enabled widget that is in the list of this composite's children from the widget at the specified index following the direction.
The given direction must be one of MWT.UP, MWT.DOWN, MWT.LEFT, MWT.RIGHT.

Parameters:

from - the index to start search

direction - the direction followed by the focus

Returns:

true if a new widget has been given focus, false otherwise

Throws:

java.lang.ArrayIndexOutOfBoundsException - if from is not a valid index

java.lang.IllegalArgumentException - if direction is not a valid direction

See Also:

getNext(int, int)

getNext

public int getNext(int from,
                   int direction)
            throws java.lang.ArrayIndexOutOfBoundsException,
                   java.lang.IllegalArgumentException

Gets the next widget in the focus order following the direction.
If there is no more widget to focus in this direction, it returns MWT.EMPTY.
The given direction must be one of MWT.UP, MWT.DOWN, MWT.LEFT, MWT.RIGHT.

Parameters:

from - the index of the current widget

direction - the direction to follow

Returns:

the index of the next widget

Throws:

java.lang.ArrayIndexOutOfBoundsException - if from is not a valid index

java.lang.IllegalArgumentException - if direction is not a valid direction

Since:

1.0

See Also:

getFocusIndex()

getFocus

public Widget getFocus()

Gets the widget that is the focus owner or that owns (recursively) the focus owner in this composite.

Returns:

the widget that own the focus on this composite or null

getFocusIndex

public int getFocusIndex()

Gets the index of the widget that is the focus owner or that is (recursively) the focus owner parent in the composite. Returns MWT.EMPTY if the focus owner is not in the composite hierarchy.

Returns:

the widget that own the focus on this composite or MWT.EMPTY

validate

public abstract void validate(int widthHint,
                              int heightHint)

Lays out this composite and all its children.

The parameters defines the maximum size available for this composite, or MWT.NONE if there is no constraint.
After this call the preferred size will have been established.

Specified by:

validate in class Widget

Parameters:

widthHint - the width available for this widget or MWT.NONE

heightHint - the height available for this widget or MWT.NONE

See Also:

Widget.isVisible(), Widget.setPreferredSize(int, int)

handleEvent

public boolean handleEvent(int event)

Called by the system if a child of this composite is the owner of the focus of the active panel (recursively) and have not consumed the specified event. Composites handles Command.UP, Command.DOWN, Command.LEFT, and Command.RIGHT commands to manage navigation in its children.

Specified by:

handleEvent in interface Renderable

Overrides:

handleEvent in class Widget

Parameters:

event - the event to handle

Returns:

true if the composite consume the event, false otherwise

See Also:

Widget.setEventHandler(EventHandler)