Package ej.mwt

## Class Desktop

- java.lang.Object
- - ej.microui.display.Displayable
  - - ej.mwt.Desktop

- All Implemented Interfaces:
    `EventHandler`

      public class Desktop
      extends Displayable

  A desktop is the top-level object that can be displayed on a `Display`.

  It contains a widget. This widget can be a container to have a more elaborate hierarchy of widgets.

  A desktop may be shown or hidden, but at most one desktop is shown per `Display`.

  A desktop provides an animator, which can be used by the widgets to start and stop animations. When the desktop is hidden, every animation is automatically stopped.

  A desktop provides a stylesheet, which is used by the widgets of the desktop in order to retrieve their style. By default, the stylesheet is a `VoidStylesheet`, but this can be changed at any time.

  See Also:
    `Display`

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Desktop()` | Creates a new desktop.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `containsWidget​(Widget widget)` | Returns whether or not this desktop contains the given widget.
    `protected EventDispatcher` | `createEventDispatcher()` | Creates the event dispatcher which is responsible for dispatching events to the widgets.
    `protected RenderPolicy` | `createRenderPolicy()` | Creates the render policy which is responsible for rendering the widgets.
    `Animator` | `getAnimator()` | Gets the animator instance.
    `EventDispatcher` | `getEventDispatcher()` | Gets the event dispatcher of this desktop.
    `Stylesheet` | `getStylesheet()` | Gets the stylesheet instance.
    `Widget` | `getWidget()` | Gets the widget attached to this desktop.
    `Widget` | `getWidgetAt​(int x, int y)` | Returns the child widget at the specified position.
    `boolean` | `handleEvent​(int event)` | Handles an event by delegating it to the event dispatcher.
    `boolean` | `isAttached()` | Gets whether this desktop is attached or not.
    `boolean` | `isShown()` | Checks whether the desktop is visible on the display.
    `protected void` | `onHidden()` | This method is called by the system as soon as the desktop is hidden from the display.
    `protected void` | `onShown()` | This method is called by the system as soon as the desktop is shown on the display.
    `protected void` | `render​(GraphicsContext g)` | The desktop is rendered using the given graphics context.
    `void` | `renderWidget​(GraphicsContext g, Widget widget)` | Renders a widget.
    `void` | `requestHide()` | Hides the desktop from the display.
    `void` | `requestLayOut()` | Requests a lay out of all the hierarchy of this desktop.
    `void` | `requestRender()` | Requests a rendering for the entire displayable.
    `void` | `requestShow()` | Shows the desktop on the display.
    `void` | `setAttached()` | Sets this desktop as attached.
    `void` | `setDetached()` | Sets this desktop as detached.
    `void` | `setStylesheet​(Stylesheet stylesheet)` | Sets the stylesheet instance.
    `void` | `setWidget​(Widget widget)` | Attaches a widget to this desktop.

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

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

- - ### Constructor Detail

    - #### Desktop

          public Desktop()

      Creates a new desktop.

  - ### Method Detail

    - #### createEventDispatcher

          protected EventDispatcher createEventDispatcher()

      Creates the event dispatcher which is responsible for dispatching events to the widgets. By default, a `pointer event dispatcher` is created.
      Returns:
        the event dispatcher.
      See Also:
        `PointerEventDispatcher`

    - #### getEventDispatcher

          @Nullable
          public EventDispatcher getEventDispatcher()

      Gets the event dispatcher of this desktop.
      Returns:
        the event dispatcher of this desktop.

    - #### createRenderPolicy

          protected RenderPolicy createRenderPolicy()

      Creates the render policy which is responsible for rendering the widgets. By default, a `default render policy` is created.
      Returns:
        the render policy.
      See Also:
        `DefaultRenderPolicy`

    - #### setWidget

          public void setWidget​(@Nullable
                                Widget widget)

      Attaches a widget to this desktop.

      If there is already a widget on this desktop, the former is detached from the latter.

      If the specified widget is `null`, the desktop does not hold a widget anymore.

      Should be called in the display thread to avoid concurrency issues.

      Parameters:
        `widget` - the widget.
      Throws:
        `IllegalArgumentException` - if the specified widget is already attached.

    - #### getWidget

          @Nullable
          public Widget getWidget()

      Gets the widget attached to this desktop.
      Returns:
        the widget attached with this desktop or `null`.

    - #### requestLayOut

          public void requestLayOut()

      Requests a lay out of all the hierarchy of this desktop.

      The layout is done asynchronously, therefore this method returns immediately. 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)`.

      Nothing is done if the desktop is not shown.

      Notifies its child widget that it is shown.

    - #### requestRender

          public void requestRender()

      Description copied from class: `Displayable`
      Requests a rendering for the entire displayable. Calling this method may result in subsequent call to `Displayable.render(GraphicsContext)` on the displayable.

      The call to `Displayable.render(GraphicsContext)` occurs asynchronously to this call. That is, this method will not block waiting for `Displayable.render(GraphicsContext)` to finish. After render action (after call to `Displayable.render(GraphicsContext)`), a call to `Display.flush()` is synchronously performed.

      This call may have no effect under certain conditions:

      - if the displayable is not visible on the display (see `Display.isShown(Displayable)`): the request is refused.
      - if the displayable is not visible on the display when the event is executed (a call to `Display.requestShow(Displayable)` has been performed with another displayable): the request is abandoned (this displayable is no longer the current displayable).
      - if a request is already available in the events queue and if the request is called from the MicroUI pump: the request is useless because this request has been already added and cannot be executed until the end of current caller method. The request is not added into the queue.
      Overrides:
        `requestRender` in class `Displayable`

    - #### isShown

          public boolean isShown()

      Checks whether the desktop is visible on the display.

      Calling this method is equivalent to calling `Display.getDisplay().isShown(desktop);`.

      Returns:
        `true` if the desktop is currently visible, `false` otherwise.

    - #### requestShow

          public void requestShow()

      Shows the desktop on the display.

      Calling this method is equivalent to calling `Display.getDisplay().requestShow(desktop);`.

      This method returns immediately and the desktop is shown asynchronously in the MicroUI thread. To execute some code just after the show is done, this code could be wrapped in a `Runnable` and executed asynchronously with `MicroUI.callSerially(Runnable)`.

      Throws:
        `SecurityException` - if a security manager exists and does not allow the caller to get the display.

    - #### requestHide

          public void requestHide()

      Hides the desktop from the display.

      Calling this method is equivalent to calling `Display.getDisplay().requestHide(desktop);`.

      This method returns immediately and the desktop is hidden asynchronously in the MicroUI thread. To execute some code just after the hide is done, this code could be wrapped in a `Runnable` and executed asynchronously with `MicroUI.callSerially(Runnable)`.

    - #### onShown

          protected void onShown()

      This method is called by the system as soon as the desktop is shown on the display.
      - The event dispatcher is created,
      - the desktop is attached (along with its children),
      - its children are shown.
      Overrides:
        `onShown` in class `Displayable`
      See Also:
        `setAttached()`

    - #### onHidden

          protected void onHidden()

      This method is called by the system as soon as the desktop is hidden from the display.
      - The event dispatcher is disposed,
      - the desktop is detached (along with its widget hierarchy).
      Overrides:
        `onHidden` in class `Displayable`
      See Also:
        `setDetached()`

    - #### setAttached

          public void setAttached()

      Sets this desktop as attached.

      Every widget in its hierarchy is attached and a layout is performed.

      See Also:
        `isAttached()`, `Widget.onAttached()`

    - #### setDetached

          public void setDetached()

      Sets this desktop as detached.

      Every widget in its hierarchy is detached.

      See Also:
        `isAttached()`, `Widget.onDetached()`

    - #### isAttached

          public boolean isAttached()

      Gets whether this desktop is attached or not.

      When the desktop is attached, that means that it is ready to be displayed (shown on a display or drawn in an image).

      Returns:
        `true` if this desktop is attached, `false` otherwise.

    - #### handleEvent

          public boolean handleEvent​(int event)

      Handles an event by delegating it to the event dispatcher.
      Parameters:
        `event` - the event to handle.
      Returns:
        `true` if the event is consumed, `false` otherwise.
      See Also:
        `Event`

    - #### renderWidget

          public void renderWidget​(GraphicsContext g,
                                   Widget widget)

      Renders a widget.

      Beware that even an hidden child can be rendered by calling this method.

      An assertion checks that the given widget is actually a child of this desktop.

      Parameters:
        `g` - the graphics context to use to draw the widget.
        `widget` - the widget to render.

    - #### render

          protected void render​(GraphicsContext g)

      The desktop is rendered using the given graphics context.

      Renders its child widget entirely.

      Specified by:
        `render` in class `Displayable`
      Parameters:
        `g` - the graphics context of the display.

    - #### getWidgetAt

          @Nullable
          public Widget getWidgetAt​(int x,
                                    int y)

      Returns the child widget at the specified position.

      If this desktop does not `contains(x, y)`, `null` is returned. The position is considered here as a relative position to the desktop.

      Parameters:
        `x` - x coordinate.
        `y` - y coordinate.
      Returns:
        the widget at the position, `null` if no widget is found in this desktop hierarchy.
      See Also:
        `Widget.getWidgetAt(int, int)`

    - #### containsWidget

          public boolean containsWidget​(Widget widget)

      Returns whether or not this desktop contains the given widget.
      Parameters:
        `widget` - the widget to check.
      Returns:
        `true` if this desktop contains the given widget, `false` otherwise.
      See Also:
        `Widget.containsWidget(Widget)`

    - #### getAnimator

          public Animator getAnimator()

      Gets the animator instance.
      Returns:
        the animator instance.

    - #### setStylesheet

          public void setStylesheet​(Stylesheet stylesheet)

      Sets the stylesheet instance.
      Parameters:
        `stylesheet` - the stylesheet instance.

    - #### getStylesheet

          public Stylesheet getStylesheet()

      Gets the stylesheet instance.
      Returns:
        the stylesheet instance.