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 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 and Description
Display()

Method Summary

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	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 or null.
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

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 old event will be not 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

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

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 or null.

Returns:

the display's event serializer or null.

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 add the request in the event serializer: no flush is running so there is nothing to wait.

On the other hand, the following code notifies the caller the flush action has been launched:

 display.requestFlush();
 MicroUI.callSerially(myRunnable);
 

where myRunnable is a Runnable which calls display.waitFlushCompleted(); to wait until previous call flush() has been processed. It works because the call to MicroUI.callSerially(myRunnable); ensures to wait the end of previous flush request (so to wait the launch of a flush).

Throws:

RuntimeException - if the current thread is the Display's events thread.