Package ej.mwt

## Class Widget

- java.lang.Object
- - ej.mwt.Widget

- Direct Known Subclasses:
    `Container`

      public abstract class Widget
      extends 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 to `requestRender()` 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` and `32767`.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `NO_CONSTRAINT` | A width or height hint equal to `NO_CONSTRAINT` means that there is no constraint on this dimension.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `Widget()` | Creates a widget.
    `protected` | `Widget​(boolean enabled)` | Creates a widget specifying if its enabled or not.

  - ### 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 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 or `null` 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​(GraphicsContext g)` | Renders the widget on the given graphics context.
    `protected abstract void` | `renderContent​(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.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### NO_CONSTRAINT

          public static final int NO_CONSTRAINT

      A width or height hint equal to `NO_CONSTRAINT` means that there is no constraint on this dimension.
      See Also:
        `computeContentOptimalSize(Size)`, Constant Field Values

  - ### Constructor Detail

    - #### Widget

          protected 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 overriding `handleEvent(int)`.

    - #### Widget

          protected 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 a position (x,y) is in the widget's bounds.

      The given position is considered here as a relative position to parent.

      By default, the widget's bounds include the content, the padding & the border but not the margins.

      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.
      See Also:
        `PointerEventDispatcher`

    - #### 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. To execute some code just after the layout is done, this code could be wrapped in a `Runnable` and executed asynchronously with `MicroUI.callSerially(Runnable)`.

      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. To execute some code just after the render is done, this code could be wrapped in a `Runnable` and executed asynchronously with `MicroUI.callSerially(Runnable)`.

      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. To execute some code just after the render is done, this code could be wrapped in a `Runnable` and executed asynchronously with `MicroUI.callSerially(Runnable)`.

      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 returns `false` (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​(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​(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 or `null` 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:
        `NullPointerException` - if the given class selector is `null`.

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