Package ej.microui.display

## Class Display

- java.lang.Object
- - ej.microui.display.Display

-     public class Display
      extends Object

  The `Display` object represents the pixelated screen in the platform.
  The display of the system may be retrieved by calling `getDisplay()`.
  The display is able to render a `Displayable` on its implementation screen. Only one `Displayable` can be set on the display at a time; it is said to be visible or to be shown. The visible `Displayable` can be retrieved with the method `getDisplayable()`.
  `requestShow(Displayable)` allows the Displayable to be selected for rendering on the display. It can be called at any time by the application, for instance in response to user inputs.
  `Display` uses a `GraphicsContext` to draw on its corresponding screen. All draw actions are serialized. The application should not use the display's graphics context outside the events mechanism `requestRender()` and `render()`. Nevertheless, for exceptional cases a new `GraphicsContext` may be created using `getGraphicsContext()`. This `GraphicsContext` bypasses the standard serialized drawing mechanism and allows drawings to be rendered on the display at any time.
  All events on the display are serialized: requestRender, callSerially, handleEvent etc. The display uses a `FIFOPump` to manage its serialized event mechanism. Some events are internally executed and some events are calling some application code.
  When a visible object has to be painted on a `Display`, the `render` method gives a `GraphicsContext` as argument and should use it to render the visible object.
  Direct drawing on the display can be done from application by retrieving a `GraphicsContext` with `getGraphicsContext()`. Using this mechanism does not ensure drawings will be performed before, during or after the current `render()`, since it bypasses the serialization system events.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Display()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `callOnFlushCompleted​(Runnable run)` | Prepares a call event which will be serialized in the system event stream when the next executed flush will be done.
    `void` | `cancelCallOnFlushCompleted()` | Cancels the event previously registered by the call to `callOnFlushCompleted(Runnable)`.
    `void` | `flush()` | Performs immediately a flush updating the display with the draw actions since the last flush if and only if the display is double buffered.
    `int` | `getBacklight()` | Returns the current backlight setting
    `int` | `getContrast()` | Returns the contrast of the display.
    `static Display` | `getDisplay()` | Returns the display of the system.
    `Displayable` | `getDisplayable()` | Returns the current `Displayable` object in the `Display`. The value returned by `getDisplayable()` may be `null` if no `Displayable` is visible.
    `int` | `getDisplayColor​(int color)` | Gets the color that will be displayed if the specified color is requested. For example, with a monochrome display, this method will return either 0xFFFFFF (white) or 0x000000 (black) depending on the brightness of the specified color.
    `EventHandler` | `getEventHandler()` | Returns the display's event serializer.
    `GraphicsContext` | `getGraphicsContext()` | Returns the display's `GraphicsContext`.
    `int` | `getHeight()` | Returns the height in pixels of the display screen area available to the application.
    `int` | `getNumberOfColors()` | Gets the number of colors that can be represented on the device. Note that the number of colors for a black and white display is 2.
    `int` | `getPixelDepth()` | Returns the number of bits per pixel of the display.
    `int` | `getWidth()` | Returns the width in pixels of the display screen area available to the application.
    `boolean` | `hasBacklight()` | Tells whether the display has backlight.
    `boolean` | `isColor()` | Tells whether the display offers color.
    `boolean` | `isDoubleBuffered()` | Returns if the display uses an underlying double buffer (either hardware or software).
    `boolean` | `isShown​(Displayable displayable)` | Checks whether the given displayable is visible on the display.
    `void` | `requestFlush()` | Requests a flush updating the display with the draw actions since the last flush if and only if the display is double buffered.
    `void` | `requestHide​(Displayable displayable)` | Asks to set the given displayable as hidden on the display.
    `void` | `requestRender()` | Asks to render the current displayable.
    `void` | `requestShow​(Displayable displayable)` | Asks to set the given displayable as visible on the display.
    `void` | `setBacklight​(int backlight)` | Sets the backlight of the display.
    `void` | `setContrast​(int contrast)` | Sets the contrast of the display.
    `void` | `waitFlushCompleted()` | Blocks the current thread (with all its locks) until previous call `flush()` has been processed.

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

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

- - ### Constructor Detail

    - #### Display

          public Display()

  - ### Method Detail

    - #### getEventHandler

          public EventHandler getEventHandler()

      Returns the display's event serializer.
      Returns:
        the display's event serializer.
      Since:
        2.0

    - #### getHeight

          public int getHeight()

      Returns the height in pixels of the display screen area available to the application.
      Returns:
        height of the display screen area.

    - #### getWidth

          public int getWidth()

      Returns the width in pixels of the display screen area available to the application.
      Returns:
        width of the display screen area.

    - #### getPixelDepth

          public int getPixelDepth()

      Returns the number of bits per pixel of the display.
      Returns:
        the number of bits per pixel

    - #### isColor

          public boolean isColor()

      Tells whether the display offers color.
      Returns:
        if display has color

    - #### getNumberOfColors

          public int getNumberOfColors()

      Gets the number of colors that can be represented on the device.
      Note that the number of colors for a black and white display is 2.
      Returns:
        the number of colors

    - #### isDoubleBuffered

          public boolean isDoubleBuffered()

      Returns if the display uses an underlying double buffer (either hardware or software). This technique is useful to avoid flickering while the user is drawing.
      Returns:
        true if and only if a double buffer is used for the display

    - #### getDisplayColor

          public int getDisplayColor​(int color)

      Gets the color that will be displayed if the specified color is requested.
      For example, with a monochrome display, this method will return either 0xFFFFFF (white) or 0x000000 (black) depending on the brightness of the specified color.
      Parameters:
        `color` - the desired color in 0x00RRGGBB format.
      Returns:
        the corresponding color that will be displayed on the graphics context (in 0x00RRGGBB format).

    - #### hasBacklight

          public boolean hasBacklight()

      Tells whether the display has backlight.
      Returns:
        if display has backlight

    - #### setContrast

          public void setContrast​(int contrast)

      Sets the contrast of the display. `contrast` value range is 0-100
      Parameters:
        `contrast` - the new value of the contrast

    - #### getContrast

          public int getContrast()

      Returns the contrast of the display.
      Returns:
        the current contrast of the display (range 0-100)

    - #### setBacklight

          public void setBacklight​(int backlight)

      Sets the backlight of the display. `backlight` value range is 0-100
      Parameters:
        `backlight` - the new value of the backlight

    - #### getBacklight

          public int getBacklight()

      Returns the current backlight setting
      Returns:
        the current backlight setting (range 0-100)

    - #### getDisplay

          public static Display getDisplay()

      Returns the display of the system. Throws a `MicroUIException` when there is no display.
      Returns:
        the unique display.
      Throws:
        `MicroUIException` - if MicroUI is not started or if there is no display.

    - #### getDisplayable

          @Nullable
          public Displayable getDisplayable()

      Returns the current `Displayable` object in the `Display`.
      The value returned by `getDisplayable()` may be `null` if no `Displayable` is visible.
      Returns:
        the current `Displayable` object in the `Display`

    - #### getGraphicsContext

          public GraphicsContext getGraphicsContext()

      Returns the display's `GraphicsContext`. With this `GraphicsContext`, it is possible to draw on the screen at any time without following the display events serializer. The graphics context has the same dimensions as the display, which allows to modify every pixel of the display.

      If the normal system execution is repainting at the same time, the last unflushed draw actions will be visible (the previous one will be hidden by the last one). It is not possible to determine which draw action will be done last.

      This method should be only used in `MicroUI.callSerially(Runnable)` context to synchronize the use of this graphics context with all display events.

      Returns:
        the display's graphics context.
      See Also:
        `MicroUI.callSerially(Runnable)`, `flush()`

    - #### requestShow

          public void requestShow​(Displayable displayable)

      Asks to set the given displayable as visible on the display. The treatment is synchronized with the other `Display` events. If the `Display`'s current displayable is not this displayable, the methods `Displayable.onShown()`, then `Displayable.render(GraphicsContext)` and then `flush()` will be called.
      Parameters:
        `displayable` - the displayable to show
      Throws:
        `SecurityException` - if a security manager exists and does not allow the caller to get the display.

    - #### requestHide

          public void requestHide​(Displayable displayable)

      Asks to set the given displayable as hidden on the display. The treatment is synchronized with the other `Display` events. If the `Display`'s current displayable is this displayable, the method `Displayable.onHidden()` will be called.
      Parameters:
        `displayable` - the displayable to hide

    - #### isShown

          public boolean isShown​(Displayable displayable)

      Checks whether the given displayable is visible on the display.
      Parameters:
        `displayable` - the displayable to check
      Returns:
        `true` if the displayable is currently visible, `false` otherwise

    - #### requestRender

          public void requestRender()

      Asks to render the current displayable. The treatment is synchronized with the other `Display` events. The methods `Displayable.render(GraphicsContext)` and then `flush()` will be called when the event is executed.

      The current displayable is the displayable which is shown when the event is executed and not the displayable which is currently shown (see `getDisplayable()` which returns the current displayable). This displayable will be different than the displayable currently shown if the method `requestShow(Displayable)` is called with another displayable.

      By consequence, this method has not the same behavior than `Displayable.requestRender()`: this other method requests the rendering on the displayable itself (if and only if this displayable is the current displayable), and the method `Displayable.render(GraphicsContext)` is called if only if the displayable is the current displayable when the event is executed.

    - #### requestFlush

          public void requestFlush()

      Requests a flush updating the display with the draw actions since the last flush if and only if the display is double buffered. The treatment is synchronized with the other `Display` events. If there is already this event in `Display`'s events queue, the new event is not added.

    - #### flush

          public void flush()

      Performs immediately a flush updating the display with the draw actions since the last flush if and only if the display is double buffered. The treatment is not synchronized with the other `Display` events; for this reason, this method should be used in `MicroUI.callSerially(Runnable)` context.

    - #### waitFlushCompleted

          public void waitFlushCompleted()

      Blocks the current thread (with all its locks) until previous call `flush()` has been processed.

      The following code does not block the caller (assuming there is no pending flush before calling first line):

           display.requestFlush();
           display.waitFlushCompleted();

      because the call to `display.requestFlush();` only adds the request in the event serializer: no `flush` is running so there is nothing to wait.

      On the other hand, the following code blocks the current thread until the call to `flush()` has been processed:

           display.flush();
           display.waitFlushCompleted();

      Throws:
        `MicroUIException` - if the current thread is the `Display`'s events thread.

    - #### callOnFlushCompleted

          public void callOnFlushCompleted​(Runnable run)

      Prepares a call event which will be serialized in the system event stream when the next executed flush will be done. This flush can already be launched or serialized (will be executed in few time) or not programmed yet.

      When the event is processed, the `run()` method of the `Runnable` object is called.
      The call to the `run()` method of the `Runnable` object is performed asynchronously. Therefore `callOnFlushCompleted()` will never block waiting for the `run()` method to finish.

      Only one event can be serialized at any time. When a new event is added while the previous one has not been executed, the new one replaces the old one. The `Runnable` object of the old event will not be notified about the end of next flush.

      The event can be cleared by calling `cancelCallOnFlushCompleted()`. In this case,The `Runnable` object of the event will not be notified about the end of next flush.

      The `run()` method should return quickly, as with other callback methods.

      Parameters:
        `run` - a `Runnable` object to call

    - #### cancelCallOnFlushCompleted

          public void cancelCallOnFlushCompleted()

      Cancels the event previously registered by the call to `callOnFlushCompleted(Runnable)`. The `Runnable` object of the old event will not be notified about the end of next flush.