Class Widget
- java.lang.Object
-
- ej.mwt.Widget
-
- Direct Known Subclasses:
Container
public abstract class Widget extends java.lang.Object
Widget is the superclass of all the user interface objects.There are a number of important concepts involving widgets:
- Lay out.
Lay out is the process of positioning and setting the size of the widgets on a desktop.
This is performed by evaluating the optimal size of each widget and container in the hierarchy then, considering the layout of the containers and the optimal size of their children, setting the position and actual size of all widgets.
The optimal size is the minimal size that allow to show correctly the content of a widget. For instance the optimal size of a label that displays a string will be the size of the string with the font defined in the style.
The optimal size is computed by
computeContentOptimalSize(Size)
method. On this size are applied the boxes and dimension defined in the style, and the size of the widget is set. This size is then used by the parent container to lay out (set position and size) the widget along with its siblings.Whenever the state of a widget changes in a way that may affect its optimal size and the lay out of the desktop of which it is a part then the hierarchy of the widget must be ask to perform a new lay out. This can be achieved by invoking
requestLayOut()
on one of the parents of the widget or the desktop depending on the lay out modification.An application will normally invoke
requestLayOut()
after making a set of changes to widgets. - Rendering.
Any widget can be asked to render itself by invoking
requestRender()
. If a widget has children it will ask them to render. If the widget is transparent it will cause the relevant area of its parent to be rendered. Note that a render request does not trigger a new lay out, and the scope of the rendering that results from a call torequestRender()
will never exceed the widget itself, its children (recursively), and, if it is transparent, its parent (recursively if the parent is also transparent).
For heap optimization the position and size are stored as a
short
and therefore are limited between-32768
and32767
.
-
-
Field Summary
Fields Modifier and Type Field Description static int
NO_CONSTRAINT
A width or height hint equal toNO_CONSTRAINT
means that there is no constraint on this dimension.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description void
addClassSelector(int classSelector)
Adds a class selector.protected abstract void
computeContentOptimalSize(Size size)
Computes the optimal size of the widget.boolean
contains(int x, int y)
Gets whether or not a position (x,y) is in the widget's bounds.boolean
containsWidget(Widget widget)
Returns whether or not this widget contains the given widget in its hierarchy.int
getAbsoluteX()
Gets the absolute x coordinate of the widget.int
getAbsoluteY()
Gets the absolute y coordinate of the widget.Rectangle
getContentBounds()
Gets the content bounds of this widget (the bounds minus the outlines).Desktop
getDesktop()
Gets the desktop to which this widget has been added.int
getHeight()
Gets the height of this widget.Container
getParent()
Gets the parent of this widget ornull
if the widget is not in a hierarchy or if it is the root of its hierarchy.Style
getStyle()
Gets the current style of the widget.Widget
getWidgetAt(int x, int y)
Gets the widget at the specified position.int
getWidth()
Gets the width of this widget.int
getX()
Gets the x coordinate of this widget, relative to its parent.int
getY()
Gets the y coordinate of this widget, relative to its parent.boolean
handleEvent(int event)
Handles the given event.boolean
hasClassSelector(int classSelector)
Gets whether or not the widget has the given class selector.boolean
isAttached()
Gets whether this widget is attached or not.boolean
isEnabled()
Gets whether or not this widget is enabled.boolean
isInState(int state)
Gets whether or not the widget is in the given state.boolean
isShown()
Gets whether this widget is shown or not.boolean
isTransparent()
Tells whether or not this widget is transparent.protected void
onAttached()
This method is called as soon as: the widget is attached to a desktop that is attached, the desktop of the widget is attached.protected void
onDetached()
This method is called as soon as: the widget is detached from a desktop that is attached, the desktop of the widget is detached.protected void
onHidden()
This method is called as soon as the widget is no more visible on the display.protected void
onLaidOut()
This method is called as soon as the widget bounds are set.protected void
onShown()
This method is called as soon as the widget is visible on the display.void
removeAllClassSelectors()
Removes all the class selectors.void
removeClassSelector(int classSelector)
Removes a class selector.void
render(ej.microui.display.GraphicsContext g)
Renders the widget on the given graphics context.protected abstract void
renderContent(ej.microui.display.GraphicsContext g, int contentWidth, int contentHeight)
Renders the content of the widget without the border, margin and padding specified in the style.void
requestLayOut()
Requests a lay out of all the widgets in the sub hierarchy of this widget.void
requestRender()
Requests a render of this entire widget on the display.void
requestRender(int x, int y, int width, int height)
Requests a render of a zone of this widget on the display.void
setClassSelectors(int[] classSelectors)
Sets the class selectors.void
setEnabled(boolean enabled)
Sets this widget to be enabled or not.void
setPosition(int x, int y)
Sets the position of this widget.void
setStyle(Style newStyle)
Sets the style of the widget.void
updateStyle()
Updates the style of this widget.
-
-
-
Constructor Detail
-
Widget
public Widget()
Creates a widget.Once created, the widget is disabled. It may be enabled later by calling
setEnabled(boolean)
. Enabled widgets can handle events by overridinghandleEvent(int)
.
-
Widget
public Widget(boolean enabled)
Creates a widget specifying if its enabled or not.Enabled widgets can handle events by overriding
handleEvent(int)
.- Parameters:
enabled
-true
if this widget is to be enabled,false
otherwise.
-
-
Method Detail
-
getX
public int getX()
Gets the x coordinate of this widget, relative to its parent.- Returns:
- the x coordinate.
-
getY
public int getY()
Gets the y coordinate of this widget, relative to its parent.- Returns:
- the y coordinate.
-
getWidth
public int getWidth()
Gets the width of this widget.- Returns:
- the width.
-
getHeight
public int getHeight()
Gets the height of this widget.- Returns:
- the height.
-
setPosition
public void setPosition(int x, int y)
Sets the position of this widget.- Parameters:
x
- the x coordinate.y
- the y coordinate.
-
getContentBounds
public Rectangle getContentBounds()
Gets the content bounds of this widget (the bounds minus the outlines).- Returns:
- the content bounds of this widget.
-
onLaidOut
protected void onLaidOut()
This method is called as soon as the widget bounds are set.
-
onAttached
protected void onAttached()
This method is called as soon as:- the widget is attached to a desktop that is attached,
- the desktop of the widget is attached.
After this call, the widget is ready to be rendered.
For example, the widget can allocate some resources useful to render it.
- See Also:
Desktop.setAttached()
-
onDetached
protected void onDetached()
This method is called as soon as:- the widget is detached from a desktop that is attached,
- the desktop of the widget is detached.
After this call, the resources allocated to render the widget must be disposed.
- See Also:
Desktop.setDetached()
-
isAttached
public boolean isAttached()
Gets whether this widget is attached or not.A widget is considered as attached if it belongs to the hierarchy of an attached desktop.
- Returns:
true
if this widget is attached,false
otherwise.
-
onShown
protected void onShown()
This method is called as soon as the widget is visible on the display.For example, this method can be used to start a task that refreshes the widget periodically.
-
onHidden
protected void onHidden()
This method is called as soon as the widget is no more visible on the display.After this call, all that has been allocated or started in
onShown()
must be disposed or stopped.
-
isShown
public boolean isShown()
Gets whether this widget is shown or not.This information is set by the parent of the widget and used to know if the widget can be drawn.
- Returns:
true
if this widget is shown,false
otherwise.- See Also:
Container.setShownChildren()
-
getAbsoluteX
public int getAbsoluteX()
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.
-
getAbsoluteY
public int getAbsoluteY()
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.
-
isTransparent
public boolean isTransparent()
Tells whether or not this widget is transparent.By default, a widget is transparent. A widget is considered as transparent if it does not draw every pixel of its bounds with maximal opacity when it is rendered. If a widget is transparent, its parent (recursively if also transparent) has to be rendered before the widget.
- Returns:
true
if this widget is transparent,false
otherwise.- See Also:
contains(int, int)
-
containsWidget
public boolean containsWidget(Widget widget)
Returns whether or not this widget contains the given widget in its hierarchy.A widget contains an other widget if one of the children of the former contains the latter or if they reference the same widget.
- Parameters:
widget
- the widget to check.- Returns:
true
if this widget contains the given widget,false
otherwise.
-
contains
public boolean contains(int x, int y)
Gets whether or not a position (x,y) is in the widget's bounds.The given position is considered here as a relative position to parent.
Subclasses can override this method if the widget is not reactive to pointer events in its entire bounds. As long as this method is used to dispatch pointer events, its implementation should be as fast as possible (for example by simplifying the shape of the sensitive area).
If this method is overridden, it may be relevant to override the
isTransparent()
method as well.- Parameters:
x
- x coordinate.y
- y coordinate.- Returns:
true
if the(x,y)
position is in widget bounds,false
otherwise.
-
getWidgetAt
@Nullable public Widget getWidgetAt(int x, int y)
Gets the widget at the specified position.If this widget does not
contains(x, y)
,null
is returned, else this widget is returned. The position is considered here as a relative position to parent.- Parameters:
x
- x coordinate.y
- y coordinate.- Returns:
- this widget if it
contains(x, y)
,null
otherwise.
-
isEnabled
public boolean isEnabled()
Gets whether or not this widget is enabled.- Returns:
true
if this widget is enabled,false
otherwise.
-
setEnabled
public void setEnabled(boolean enabled)
Sets this widget to be enabled or not.- Parameters:
enabled
-true
if this widget is to be enabled,false
otherwise.
-
requestLayOut
public void requestLayOut()
Requests a lay out of all the widgets in the sub hierarchy of this widget.This method returns immediately and the layout of the widget is performed asynchronously in the MicroUI thread.
This method can only be called if this widget has been added to a desktop.
Nothing is done if the widget is not attached or if the widget has an empty size (width and height are equal to
0
).If the widget was not already shown, it is shown as soon as its bounds are set.
The style of all the widgets in the hierarchy is set (or updated) during this phase.
After the widget is laid out, it will be rendered.
-
computeContentOptimalSize
protected abstract void computeContentOptimalSize(Size size)
Computes the optimal size of the widget.This method does not consider the border, margin, padding and dimension specified in the style.
The given size is the available size for this widget in its parent. A width or a height equal to
Widget#NO_CONSTRAINT
means that there is no constraint on this dimension.The given size is modified to set the optimal size.
- Parameters:
size
- the size available for the content.
-
requestRender
public void requestRender()
Requests a render of this entire widget on the display. This method returns immediately and the rendering of the widget is performed asynchronously in the MicroUI thread.If the widget is not shown, nothing is done.
- See Also:
RenderPolicy
-
requestRender
public void requestRender(int x, int y, int width, int height)
Requests a render of a zone of this widget on the display. This method returns immediately and the rendering of the widget is performed asynchronously in the MicroUI thread.If the widget is not shown, nothing is done.
If the given area exceeds the bounds of the widget, only the intersection of the widget and the area will be rendered.
- Parameters:
x
- the relative x coordinate of the area to render.y
- the relative y coordinate of the area to render.width
- the width of the area to render.height
- the height of the area to render.- See Also:
RenderPolicy
-
handleEvent
public boolean handleEvent(int event)
Handles the given event. Does nothing by default and returnsfalse
(does not consume event).Called by the desktop event manager.
- Parameters:
event
- the event to handle.- Returns:
true
if the widget has consumed the event,false
otherwise.
-
render
public void render(ej.microui.display.GraphicsContext g)
Renders the widget on the given graphics context.The given graphics context is translated to the origin of the widget and clipped to the area to draw.
First, the different outlines defined in the style are applied, then, the content is rendered.
- Parameters:
g
- the graphics context to use to draw the widget.- See Also:
OutlineHelper.applyOutlinesAndBackground(GraphicsContext, Size, Style)
,renderContent(GraphicsContext, int, int)
-
renderContent
protected abstract void renderContent(ej.microui.display.GraphicsContext g, int contentWidth, int contentHeight)
Renders the content of the widget without the border, margin and padding specified in the style.The given graphics context is translated and clipped according to the given bounds (the border, margin and padding are applied on this graphics context before).
- Parameters:
g
- the graphics context where to render the content of the widget.contentWidth
- the width of the content area.contentHeight
- the height of the content area.
-
getParent
@Nullable public Container getParent()
Gets the parent of this widget ornull
if the widget is not in a hierarchy or if it is the root of its hierarchy.- Returns:
- the parent of this widget or
null
.
-
getDesktop
public Desktop getDesktop()
Gets the desktop to which this widget has been added.This method can only be called if this widget has been added to a desktop.
- Returns:
- the desktop to which this widgets has been added.
-
getStyle
public Style getStyle()
Gets the current style of the widget.This method should not be called before this widget is laid out.
- Returns:
- the current style of the widget.
- See Also:
Stylesheet.getStyle(Widget)
-
setStyle
public void setStyle(Style newStyle)
Sets the style of the widget.- Parameters:
newStyle
- the style.
-
updateStyle
public void updateStyle()
Updates the style of this widget.If the widget is not in a desktop, nothing is done.
-
hasClassSelector
public boolean hasClassSelector(int classSelector)
Gets whether or not the widget has the given class selector.- Parameters:
classSelector
- the class selector to check.- Returns:
true
if the widget has the given class selector,false
otherwise.
-
addClassSelector
public void addClassSelector(int classSelector)
Adds a class selector.- Parameters:
classSelector
- the class selector to add.- Throws:
java.lang.NullPointerException
- if the given class selector isnull
.
-
removeClassSelector
public void removeClassSelector(int classSelector)
Removes a class selector.- Parameters:
classSelector
- the class selector to remove.
-
setClassSelectors
public void setClassSelectors(int[] classSelectors)
Sets the class selectors.If there is already some class selectors, they are removed.
- Parameters:
classSelectors
- the class selectors list to split.
-
removeAllClassSelectors
public void removeAllClassSelectors()
Removes all the class selectors.
-
isInState
public boolean isInState(int state)
Gets whether or not the widget is in the given state.- Parameters:
state
- the state to check.- Returns:
true
if the widget is in the given state,false
otherwise.
-
-