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.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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

- Method Detail
  - 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.
  - 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.
  - getBacklight
```
public int getBacklight()
```
    Returns the current backlight setting
    
    Returns:
    
    the current backlight setting (range 0-100)
  - getContrast
```
public int getContrast()
```
    Returns the contrast of the display.
    
    Returns:
    
    the current contrast of the display (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
  - 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).
  - getEventHandler
```
public EventHandler getEventHandler()
```
    Returns the display's event serializer.
    
    Returns:
    
    the display's event serializer.
    
    Since:
    
    2.0
  - 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()
  - 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.
  - 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
  - getPixelDepth
```
public int getPixelDepth()
```
    Returns the number of bits per pixel of the display.
    
    Returns:
    
    the number of bits per pixel
  - 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.
  - hasBacklight
```
public boolean hasBacklight()
```
    Tells whether the display has backlight.
    
    Returns:
    
    if display has backlight
  - isColor
```
public boolean isColor()
```
    Tells whether the display offers color.
    
    Returns:
    
    if display has color
  - 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
  - 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
  - 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.
  - 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
  - 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.
  - 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.
  - 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
  - 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
  - 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.

Class Display

Method Summary

Methods inherited from class java.lang.Object

Method Detail

callOnFlushCompleted

cancelCallOnFlushCompleted

flush

getBacklight

getContrast

getDisplay

getDisplayable

getDisplayColor

getEventHandler

getGraphicsContext

getHeight

getNumberOfColors

getPixelDepth

getWidth

hasBacklight

isColor

isDoubleBuffered

isShown

requestFlush

requestHide

requestRender

requestShow

setBacklight

setContrast

waitFlushCompleted