ej.mwt

Class Widget

java.lang.Object

ej.mwt.Widget

All Implemented Interfaces:

Renderable

Direct Known Subclasses:

Composite

public abstract class Widget
extends java.lang.Object
implements Renderable

Widget is the superclass of all the user interface objects.

There are a number of important concepts involving widgets:

• Invalidation.
  Whenever the state of a widget changes in a way that may affect the layout of the panel of which it is a part then the hierarchy of the widget must be ask to be revalidated. This can be achieved by invoking revalidate() on the widget.
• Validation.
  Validation is the process laying out the widgets on a panel. This is performed by invoking Panel.validate(), which has the side-effect of performing any required repainting after validation. An application will normally invoke Panel.revalidate() after making a set of changes to widgets.

  The validate(int, int) method should not normally be invoked by applications or widget implementations. It is used by the Panel to propagate the validation request down through the widget hierarchy - widgets with children propagate the call to their children.

• Repainting.
  Any widget can be asked to repaint itself by invoking repaint(). If a widget has children it will ask them to repaint. If the widget is transparent it will cause the relevant area of its parent to be repainted. Note that a repaint request does not trigger validation, and the scope of the repainting that results from a call to repaint() will never exceed the widget itself, its children (recursively), and, if it is transparent, its parent (recursively if the parent is also transparent).
• Preferred size.
  A widget's preferred size is its optimal displayed size given its content. Calling validate(int, int) causes the preferred size to be determined, normally with the assistance of a renderer. The preferred size is distinct from the widget's actual size on the display (which may itself be subject to clipping).
• Actual size.
  The actual size is set by calling setSize(int, int) or setBounds(int, int, int, int).
  

Constructor Summary

Constructors

Constructor and Description
Widget() Creates a new widget.

Method Summary

Modifier and Type	Method and Description
boolean	contains(int x, int y) Gets true if the (x,y) location is in the widget bounds, false otherwise.
void	gainFocus() Notifies the widget that it is now the focus owner of its panel.
int	getAbsoluteX() Gets the absolute x coordinate of the widget.
int	getAbsoluteX(int relativeX) Gets the absolute x coordinate computed from the given x coordinate relative to the widget.
int	getAbsoluteY() Gets the absolute y coordinate of the widget.
int	getAbsoluteY(int relativeY) Gets the absolute y coordinate computed from the given y coordinate relative to the widget.
ej.microui.util.EventHandler	getEventHandler() Gets the event handler.
int	getHeight() Gets the height of this renderable.
Panel	getPanel() Gets the panel of this widget or null if the widget is not in a panel.
Composite	getParent() Gets the parent of this widget or null if the widget is not in a hierarchy.
int	getPreferredHeight() Gets the preferred height of the widget.
int	getPreferredWidth() Gets the preferred width of the widget.
int	getRelativeX(int absoluteX) Gets the x coordinate relative to the widget computed from the given absolute x coordinate.
int	getRelativeY(int absoluteY) Gets the y coordinate relative to the widget computed from the given absolute y coordinate.
Widget	getWidgetAt(int x, int y) Gets the 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 the widget is the owner of the focus of the active panel.
boolean	hasFocus() Gets whether or not this widget is the focus owner of its panel and its panel is the active one.
void	hideNotify() This method is called as soon as the renderable is hidden.
void	invalidate() Declares that the panel containing this widget needs to be laid out.
boolean	isEnabled() Gets whether or not this widget is enabled.
boolean	isShown() Gets whether or not the widget is shown on a shown panel.
boolean	isTransparent() Gets whether this widget is transparent or not.
boolean	isValid() Gets whether this widget is valid.
boolean	isVisible() Gets whether this widget is visible or not.
void	lostFocus() Notifies the widget that it is no longer the focus owner of its panel.
void	repaint() Requests a repaint of this entire widget.
void	repaint(int x, int y, int width, int height) Requests a repaint of a zone of this widget.
void	requestFocus() Sets this widget as the focus owner of its panel if it is enabled.
boolean	requestFocus(int direction) Sets this widget as the focus owner of its panel if it is enabled.
void	revalidate() Lays out all the hierarchy of the panel containing this widget if exists.
void	setBounds(int x, int y, int width, int height) Sets the bounds of this widget.
void	setEnabled(boolean enable) Sets this widget to be enabled or not.
void	setEventHandler(ej.microui.util.EventHandler eventHandler) Sets the event handler.
void	setLocation(int x, int y) Sets the location of this widget.
void	setPreferredSize(int preferredWidth, int preferredHeight) Sets the preferred size of the widget.
void	setSize(int width, int height) Sets the size of this widget.
void	setVisible(boolean visible) Sets this widget visible or not.
void	showNotify() This method is called as soon as the renderable is visible.
abstract void	validate(int widthHint, int heightHint) Lays out this widget if visible.

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

Widget

public Widget()

Creates a new widget.

By default:

• its bounds are 0,
• it is visible,
• it is enable.

Method Detail

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()

Gets the width of this renderable.

If the widget is not visible, its width is always equals to 0.

Specified by:

getWidth in interface Renderable

Returns:

the width

getHeight

public int getHeight()

Gets the height of this renderable.

If the widget is not visible, its height is always equals to 0.

Specified by:

getHeight in interface Renderable

Returns:

the height

getPreferredWidth

public int getPreferredWidth()

Gets the preferred width of the widget.

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 widget.

getPreferredHeight

public int getPreferredHeight()

Gets the preferred height of the widget.

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 widget.

setPreferredSize

public void setPreferredSize(int preferredWidth,
                             int preferredHeight)

Sets the preferred size of the widget.

Parameters:

preferredWidth - the width to set.

preferredHeight - the height to set.

setLocation

public void setLocation(int x,
                        int y)

Sets the location of this widget.

Parameters:

x - the x coordinate to set.

y - the y coordinate to set.

setSize

public void setSize(int width,
                    int height)

Sets the size of this widget.

Parameters:

width - the width to set.

height - the height to set.

setBounds

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

Sets the bounds of this widget.

Parameters:

x - the x coordinate to set.

y - the y coordinate to set.

width - the width to set.

height - the height to set.

showNotify

public void showNotify()

Description copied from interface: Renderable

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

Specified by:

showNotify in interface Renderable

hideNotify

public void hideNotify()

Description copied from interface: Renderable

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

Specified by:

hideNotify in interface Renderable

getAbsoluteX

public int getAbsoluteX()
                 throws java.lang.IllegalArgumentException

Gets the absolute x coordinate of the widget. That is, the x coordinate relative to the origin of the display.

Returns:

the absolute x coordinate of the widget.

Throws:

java.lang.IllegalArgumentException - if the widget is not connected to a Panel.

getAbsoluteY

public int getAbsoluteY()
                 throws java.lang.IllegalArgumentException

Gets the absolute y coordinate of the widget. That is, the y coordinate relative to the origin of the display.

Returns:

the absolute y coordinate of the widget.

Throws:

java.lang.IllegalArgumentException - if the widget is not connected to a Panel.

getRelativeX

public int getRelativeX(int absoluteX)
                 throws java.lang.IllegalArgumentException

Gets the x coordinate relative to the widget computed from the given absolute x coordinate.

Parameters:

absoluteX - the absolute x coordinate to convert.

Returns:

the widget relative x coordinate.

Throws:

java.lang.IllegalArgumentException - if the widget is not connected to a Panel.

Since:

1.0

getRelativeY

public int getRelativeY(int absoluteY)
                 throws java.lang.IllegalArgumentException

Gets the y coordinate relative to the widget computed from the given absolute y coordinate.

Parameters:

absoluteY - the absolute y coordinate to convert.

Returns:

the widget relative y coordinate.

Throws:

java.lang.IllegalArgumentException - if the widget is not connected to a Panel.

Since:

1.0

getAbsoluteX

public int getAbsoluteX(int relativeX)

Gets the absolute x coordinate computed from the given x coordinate relative to the widget.

Parameters:

relativeX - the widget relative x coordinate to convert.

Returns:

the absolute x coordinate.

Since:

1.0

getAbsoluteY

public int getAbsoluteY(int relativeY)

Gets the absolute y coordinate computed from the given y coordinate relative to the widget.

Parameters:

relativeY - the widget relative y coordinate to convert.

Returns:

the absolute y coordinate.

Since:

1.0

isVisible

public boolean isVisible()

Gets whether this widget is visible or not.

Returns:

true if this widget is visible, false otherwise.

Since:

1.0

See Also:

setVisible(boolean)

setVisible

public void setVisible(boolean visible)

Sets this widget visible or not.

Declaring a widget as invisible means that it does not appear on the screen and its size is (0, 0).

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

Parameters:

visible - true to set this widget visible, false otherwise.

Since:

1.0

See Also:

isValid(), invalidate()

isTransparent

public boolean isTransparent()

Gets whether this widget is transparent or not.

By default, a widget is transparent.

A transparent widget 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 widget.
Each time a non-transparent widget needs to be repainted, it is the only one to be repainted.

Returns:

true if this widget is transparent, false otherwise.

See Also:

contains(int, int)

contains

public boolean contains(int x,
                        int y)

Gets true if the (x,y) location is in the widget bounds, false otherwise.

The location is considered here as a relative location to parent.

Parameters:

x - x coordinate.

y - y coordinate.

Returns:

true if the (x,y) location is in widget bounds, false otherwise.

See Also:

isTransparent()

getWidgetAt

public Widget getWidgetAt(int x,
                          int y)

Gets the widget at the specified location.

If this widget does not contains(x, y), null is returned, else this widget is returned. The location is considered here as a relative location to parent.

Parameters:

x - x coordinate.

y - y coordinate.

Returns:

this widget if it contains(x, y), null otherwise.

hasFocus

public boolean hasFocus()

Gets whether or not this widget is the focus owner of its panel and its panel is the active one.

Gets false if this widget is not on a panel.

Returns:

true if this widget is the focus owner, false otherwise.

See Also:

Panel.isActive()

requestFocus

public void requestFocus()

Sets this widget as the focus owner of its panel if it is enabled.

If the widget is not in a panel hierarchy, nothing is done.

requestFocus

public boolean requestFocus(int direction)

Sets this widget as the focus owner of its panel if it is enabled.

If the widget is not in a panel hierarchy, nothing is done.
The given direction must be one of MWT.UP, MWT.DOWN, MWT.LEFT, MWT.RIGHT.
Composed widgets can override this method in order to manage internal focus.

Parameters:

direction - the direction followed by the focus

Returns:

true if the widget take the focus, false otherwise.

gainFocus

public void gainFocus()

Notifies the widget that it is now the focus owner of its panel.

The subclasses can override this method to add behavior.

lostFocus

public void lostFocus()

Notifies the widget that it is no longer the focus owner of its panel.

The subclasses can override this method to add behavior.

isEnabled

public boolean isEnabled()

Gets whether or not this widget is enabled.

A widget that is not enabled cannot get focus.
A widget that is not visible is also disabled.

Returns:

true if this widget is enabled, false otherwise.

setEnabled

public void setEnabled(boolean enable)

Sets this widget to be enabled or not. A widget must be enabled in order to receive focus, to be the subject of mouse focus, or to receive events.

Requests a repaint of the widget.

Parameters:

enable - true if this widget is to be enabled, false otherwise.

See Also:

repaint()

invalidate

public void invalidate()

Declares that the panel containing this widget needs to be laid out.

Since:

2.0

See Also:

Panel.invalidate()

revalidate

public void revalidate()

Lays out all the hierarchy of the panel containing this widget if exists.

If the hierarchy is not declared as invalid, nothing is done.

Since:

1.0

See Also:

Panel.revalidate()

validate

public abstract void validate(int widthHint,
                              int heightHint)

Lays out this widget if visible.

After this call the preferred size will have been established.

The parameters defines the maximum size available for this widget, or MWT.NONE if there is no constraint.

Parameters:

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

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

See Also:

isVisible(), setPreferredSize(int, int)

isValid

public boolean isValid()

Gets whether this widget is valid.

A widget is valid if all of these conditions are meet :

• if it is in a panel hierarchy,
• if it is visible,
• if all its panel hierarchy is valid.

Returns:

true if this widget is valid, false otherwise.

See Also:

isVisible(), Panel.isValid()

getParent

public Composite getParent()

Gets the parent of this widget or null if the widget is not in a hierarchy.

Returns:

the parent of this widget or null.

getPanel

public Panel getPanel()

Gets the panel of this widget or null if the widget is not in a panel.

Returns:

the panel of this widget or null.

isShown

public boolean isShown()

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

Specified by:

isShown in interface Renderable

Returns:

true if the widget is shown, false otherwise.

See Also:

getPanel(), Panel.isShown()

repaint

public void repaint()

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

If the widget is not shown, nothing is done.
If the widget is transparent, it requests a repaint of its parent within the widget's bounds.

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 widget. This method returns immediately, the repaint of the widget is performed asynchronously.

If the widget is not shown, nothing is done.
If the widget is transparent, it requests a repaint of its parent within the requested bounds.

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.

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 the widget is the owner of the focus of the active panel.

If an event handler is registered, its EventHandler.handleEvent(int) method is called.
Otherwise, do nothing and return false (do not consume event).

Specified by:

handleEvent in interface Renderable

Parameters:

event - the event to handle.

Returns:

true if the widget has consumed the event, false otherwise.

See Also:

setEventHandler(EventHandler)