ej.mwt

Class Panel

java.lang.Object

ej.mwt.Panel

All Implemented Interfaces:

Renderable

Direct Known Subclasses:

Dialog

public class Panel
extends java.lang.Object
implements Renderable

A panel is a Renderable object that can be added on a Desktop. It can contain a Widget.

Constructor Summary

Constructors

Constructor and Description
Panel() Creates a new panel.

Method Summary

Modifier and Type	Method and Description
void	becameActive() Notifies the panel that it is now the active panel of its desktop.
void	becameInactive() Notifies the panel that it is no longer the active panel of its desktop.
boolean	contains(int x, int y) Returns true if the (x,y) position is in the panel's bounds, false otherwise. The location is considered here as a relative location to the desktop.
Desktop	getDesktop() Gets the desktop on which the panel is shown.
ej.microui.util.EventHandler	getEventHandler() Gets the event handler.
Widget	getFocus() Gets the widget that is the focus owner of this panel.
int	getHeight() Gets the height of this renderable.
int	getPreferredHeight() Returns the preferred height of the panel.
int	getPreferredWidth() Returns the preferred width of the panel.
Widget	getWidget() Gets the widget attached to this panel.
Widget	getWidgetAt(int x, int y) Returns the child widget at the specified location.
int	getWidth() Gets the width of this renderable.
int	getX() Gets the x coordinate of this renderable, relative to its parent.
int	getY() Gets the y coordinate of this renderable, relative to its parent.
boolean	handleEvent(int event) Called by the system if this is the active panel and if no widget in the hierarchy of the focused widget has consumed the event.
void	hide() Requests the panel be hidden. The panel is invalidated. The panel is removed from the list of panels known by the desktop.
void	hideNotify() This method is called as soon as the renderable is hidden.
void	invalidate() Declares that this panel needs to be laid out.
boolean	isActive() Gets whether or not the panel is the active one on its desktop.
boolean	isPacked() Gets whether this panel is packed or not.
boolean	isShown() Gets whether or not the panel is shown on a shown desktop.
boolean	isTransparent() Gets whether this panel is transparent or not.
boolean	isValid() Gets whether this panel is valid.
void	render(ej.microui.display.GraphicsContext g) Renders the renderable on the given graphics context.
void	repaint() Requests a repaint of this entire panel.
void	repaint(int x, int y, int width, int height) Requests a repaint of a zone of this panel.
void	revalidate() Lays out all the hierarchy of this panel.
void	setBounds(int x, int y, int width, int height) Set the bounds of this panel.
void	setEventHandler(ej.microui.util.EventHandler eventHandler) Sets the event handler.
void	setFocus(Widget widget) Sets the specified widget as the current focus owner of this panel.
void	setLocation(int x, int y) Set the location of this panel.
void	setPacked(boolean packed) Sets this panel as packed or not. This property is used when the panel is validated: if it is packed (specified boolean is true), the panel is resized to the preferred size of its widgets, otherwise its widgets fill its size.
void	setPreferredSize(int preferredWidth, int preferredHeight) Sets the preferred size of the panel.
void	setSize(int width, int height) Set the size of this panel.
void	setWidget(Widget widget) Attach the specified widget to this panel.
void	show(Desktop desktop) Requests the panel to be shown on the specified desktop.
void	show(Desktop desktop, boolean fill) Requests the panel to be shown on the specified desktop.
void	showNotify() This method is called as soon as the renderable is visible.
void	validate() Lays out all the hierarchy of this panel.
void	validate(int widthHint, int heightHint) Lays out all the hierarchy of this panel. After this call the preferred size will have been established.

Methods inherited from class java.lang.Object

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

Constructor Detail

Panel

public Panel()

Creates a new panel.

By default:

• its bounds are 0,
• it is packed.

Method Detail

setWidget

public void setWidget(Widget widget)
               throws java.lang.IllegalArgumentException

Attach the specified widget to this panel.

If there is already a widget on this panel, the former is detached from the latter.
If the specified widget is null, the panel does not hold a widget anymore.

The panel is also ask to be revalidated if shown.

Parameters:

widget - the widget to set.

Throws:

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

See Also:

revalidate()

getWidget

public Widget getWidget()

Gets the widget attached to this panel.

Returns:

the widget attached with this panel or null

setLocation

public void setLocation(int x,
                        int y)

Set the location of this panel.

Equivalent to calling setBounds(int, int, int, int) passing the given location and the current size.

Parameters:

x - the x coordinate to set

y - the y coordinate to set

setSize

public void setSize(int width,
                    int height)

Set the size of this panel.

Equivalent to calling setBounds(int, int, int, int) passing the current location and the given size.

Parameters:

width - the width to set

height - the height to set

setBounds

public void setBounds(int x,
                      int y,
                      int width,
                      int height)

Set the bounds of this panel.

Parameters:

x - the x coordinate to set

y - the y coordinate to set

width - the width to set

height - the height to set

getPreferredWidth

public int getPreferredWidth()

Returns the preferred width of the panel. The result returned is meaningful only if isValid() is true or if setPreferredSize(int, int) has been called explicitly.

Returns:

the preferred width of the panel

getPreferredHeight

public int getPreferredHeight()

Returns the preferred height of the panel. The result returned is meaningful only if isValid() is true or if setPreferredSize(int, int) has been called explicitly.

Returns:

the preferred height of the panel

setPreferredSize

public void setPreferredSize(int preferredWidth,
                             int preferredHeight)

Sets the preferred size of the panel.

Parameters:

preferredWidth - the width to set

preferredHeight - the height to set

getX

public int getX()

Description copied from interface: Renderable

Gets the x coordinate of this renderable, relative to its parent.

Specified by:

getX in interface Renderable

Returns:

the x coordinate

getY

public int getY()

Description copied from interface: Renderable

Gets the y coordinate of this renderable, relative to its parent.

Specified by:

getY in interface Renderable

Returns:

the y coordinate

getWidth

public int getWidth()

Description copied from interface: Renderable

Gets the width of this renderable.

Specified by:

getWidth in interface Renderable

Returns:

the width

getHeight

public int getHeight()

Description copied from interface: Renderable

Gets the height of this renderable.

Specified by:

getHeight in interface Renderable

Returns:

the height

show

public void show(Desktop desktop)
          throws java.lang.NullPointerException

Requests the panel to be shown on the specified desktop.

Identical to calling show(Desktop, boolean) without filling the desktop.

Parameters:

desktop - the desktop

Throws:

java.lang.NullPointerException - if desktop is null.

See Also:

show(Desktop, boolean), hide(), isShown(), revalidate()

show

public void show(Desktop desktop,
                 boolean fill)
          throws java.lang.NullPointerException

Requests the panel to be shown on the specified desktop.

If fill is true, it is fitted to desktop size and it will be declared as not be packed.
If fill is false and no size has been set, it will be declared as packed.
If the desktop is shown, the panel is automatically validated.
The panel is added to the list of panels known by the desktop.

Special cases:

• If the panel is already shown on this desktop, nothing is changed.
• If the panel is already shown on another desktop, it is hidden on this desktop before being shown on the new one.

Parameters:

desktop - the desktop

fill - true to fit the panel to the desktop size, false otherwise

Throws:

java.lang.NullPointerException - if desktop is null.

See Also:

hide(), isShown(), revalidate()

showNotify

public void showNotify()

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

Notifies its child widget that it is shown.

Specified by:

showNotify in interface Renderable

hideNotify

public void hideNotify()

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

Notifies its child widget that it is hidden.

Specified by:

hideNotify in interface Renderable

hide

public void hide()

Requests the panel be hidden.
The panel is invalidated.
The panel is removed from the list of panels known by the desktop.

See Also:

show(Desktop), isShown()

isShown

public boolean isShown()

Gets whether or not the panel is shown on a shown desktop.

Specified by:

isShown in interface Renderable

Returns:

true if the panel is shown, false otherwise.

See Also:

getDesktop(), Displayable.isShown()

isActive

public boolean isActive()

Gets whether or not the panel is the active one on its desktop. If the panel is not shown on a desktop, return false.

Returns:

true if the panel is the active one, false otherwise.

See Also:

isShown()

becameActive

public void becameActive()

Notifies the panel that it is now the active panel of its desktop. The subclasses can override this method to add behavior.

becameInactive

public void becameInactive()

Notifies the panel that it is no longer the active panel of its desktop. The subclasses can override this method to add behavior.

getDesktop

public Desktop getDesktop()

Gets the desktop on which the panel is shown. Returns null if the panel is not shown.

Returns:

the desktop on which the panel is shown or null.

See Also:

isShown()

repaint

public void repaint()

Requests a repaint of this entire panel. This method returns immediately, repainting of the panel is performed asynchronously.

If the panel is not shown, nothing is done.

Specified by:

repaint in interface Renderable

repaint

public void repaint(int x,
                    int y,
                    int width,
                    int height)

Requests a repaint of a zone of this panel. This method returns immediately, repainting of the panel is performed asynchronously.

If the panel is not shown, nothing is done.

Specified by:

repaint in interface Renderable

Parameters:

x - the relative x coordinate of the area to repaint.

y - the relative y coordinate of the area to repaint.

width - the width of the area to repaint.

height - the height of the area to repaint.

render

public void render(ej.microui.display.GraphicsContext g)

Description copied from interface: Renderable

Renders the renderable on the given graphics context.

Specified by:

render in interface Renderable

Parameters:

g - the graphics context to be used to draw the renderable.

isTransparent

public boolean isTransparent()

Gets whether this panel is transparent or not.

By default, a panel is transparent.

A transparent panel means that it will not repaint ALL the rectangular zone defined by its bounds. Then each time it needs to be repainted, its parent (recursively if also transparent) will be repainted within the bounds of the panel.
Each time a non-transparent panel needs to be repainted, it is the only one to be repainted.

Returns:

true if this panel is transparent, false otherwise.

See Also:

contains(int, int)

contains

public boolean contains(int x,
                        int y)

Returns true if the (x,y) position is in the panel's bounds, false otherwise.
The location is considered here as a relative location to the desktop.

Parameters:

x - x coordinate

y - y coordinate

Returns:

true if the (x,y) position is in the panel bounds, false otherwise.

See Also:

isTransparent()

getWidgetAt

public Widget getWidgetAt(int x,
                          int y)

Returns the child widget at the specified location. If this panel does not contains(x, y), null is returned. The location is considered here as a relative location to the desktop.

Parameters:

x - x coordinate

y - y coordinate

Returns:

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

See Also:

Widget.getWidgetAt(int, int)

setFocus

public void setFocus(Widget widget)
              throws java.lang.IllegalArgumentException

Sets the specified widget as the current focus owner of this panel.

If the widget is not enabled, nothing is done.

If the widget already own the focus, nothing is done.

Throws an IllegalArgumentException if the specified widget is not in the panel.

Parameters:

widget - the widget to focus.

Throws:

java.lang.IllegalArgumentException - if the specified widget is not in the panel.

getFocus

public Widget getFocus()

Gets the widget that is the focus owner of this panel.

Returns:

the widget that own the focus on this panel or null

setPacked

public void setPacked(boolean packed)

Sets this panel as packed or not.
This property is used when the panel is validated: if it is packed (specified boolean is true), the panel is resized to the preferred size of its widgets, otherwise its widgets fill its size.

Parameters:

packed - true to pack the panel, false otherwise

Since:

1.0

See Also:

revalidate(), setSize(int, int)

isPacked

public boolean isPacked()

Gets whether this panel is packed or not.

Returns:

true if this panel is packed, false otherwise.

Since:

1.0

invalidate

public void invalidate()

Declares that this panel needs to be laid out.

See Also:

revalidate(), validate()

isValid

public boolean isValid()

Gets whether this panel is valid.

A panel is valid if its contents are correctly laid out.

Returns:

true if this panel is valid, false otherwise

See Also:

invalidate(), validate()

revalidate

public void revalidate()

Lays out all the hierarchy of this panel.

It performs the method validate() asynchronously. Therefore this method does not block until the validation of the hierarchy is done.

Nothing is done if the panel is already valid.

The panel is not validated if it is not shown or if its desktop is not shown.

Since:

1.0

See Also:

invalidate()

validate

public void validate()

Lays out all the hierarchy of this panel.

Nothing is done if the panel is already valid.

The panel is repainted if it is shown on a desktop.

If the panel is declared as packed, it is resized to the preferred size of its widgets, otherwise its widgets fill its size.

See Also:

isPacked(), isValid()

validate

public void validate(int widthHint,
                     int heightHint)

Lays out all the hierarchy of this panel.
After this call the preferred size will have been established. The parameters defines the maximum size available for this panel, or MWT.NONE if there is no constraint.

Parameters:

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

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

setEventHandler

public void setEventHandler(ej.microui.util.EventHandler eventHandler)

Description copied from interface: Renderable

Sets the event handler.

Specified by:

setEventHandler in interface Renderable

Parameters:

eventHandler - the event handler to set.

See Also:

Renderable.handleEvent(int)

getEventHandler

public ej.microui.util.EventHandler getEventHandler()

Description copied from interface: Renderable

Gets the event handler.

Specified by:

getEventHandler in interface Renderable

Returns:

the event handler.

See Also:

Renderable.handleEvent(int)

handleEvent

public boolean handleEvent(int event)

Called by the system if this is the active panel and if no widget in the hierarchy of the focused widget has consumed the event. Panels handles Command.UP, Command.DOWN, Command.LEFT, and Command.RIGHT commands to manage navigation.

Specified by:

handleEvent in interface Renderable

Parameters:

event - the event to handle

Returns:

true if the panel has consumed the event, false otherwise