ej.microui.display

Class Display

java.lang.Object

ej.microui.display.Display

public class Display
extends java.lang.Object

A Display object represents a pixelated screen in the platform, and there is a display for each such pixelated screen. Available displays can be retrieved with the method getAllDisplays(). A default display is defined in every MicroUI implementation and can be fetched with the method getDefaultDisplay().

A display is able to render a Displayable on its implementation screen. Only one Displayable can be set on a display at a time; it is said to be visible or to be shown. The visible Displayable can be retrieved with the method getDisplayable().

Displayable.show() allows the Displayable to be selected for rendering on its 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 a display's graphics context outside the events mechanism repaint() and paint(). Nevertheless, for exceptional cases a new GraphicsContext may be created using getNewGraphicsContext(). This new GraphicsContext bypasses the standard serialized drawing mechanism and allows drawings to be rendered on the display at any time.

All events on a display are serialized: repaint, callSerially, handleEvent etc. A display uses a FIFOPump to manage its serialized event mechanism.

Constructor Summary

Constructors

Constructor and Description
Display()

Method Summary

Modifier and Type	Method and Description
void	callSerially(java.lang.Runnable run) Serializes a call event in the system event stream.
static Display[]	getAllDisplays() Returns all available displays.
int	getBacklight() Returns the current backlight setting
int	getBacklightColor() Returns the current backlight color.
int	getBPP() Returns the number of bits per pixel of the display.
int	getContrast() Returns the contrast of the display.
static Display	getDefaultDisplay() Returns the default 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	getEventSerializer() Returns the display's event serializer or null.
int	getHeight() Returns the height in pixels of the display screen area available to the application.
ExplicitFlush	getNewExplicitFlush() Returns a new ExplicitFlush which works on the same system screen as this display.
GraphicsContext	getNewGraphicsContext() Returns a new GraphicsContext which works on the same system screen as this display.
int	getNumberOfAlphaLevels() Gets the number of alpha transparency levels supported by the implementation. The minimum possible is 2, which represents full transparency and full opacity with no blending.
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.
Image	getScreenshot() Creates an image with the full content of the display.
Image	getScreenshot(int x, int y, int width, int height) Creates an image with the content of the display region specified thanks the given rectangle.
int	getWidth() Returns the width in pixels of the display screen area available to the application.
void	handleEvent(int event) Injects a MicroUI event to be handled by the event generator associated with this Display.
boolean	hasBacklight() Tells whether the display has backlight.
boolean	isColor() Tells whether the display offers color.
boolean	isDisplayThread() Gets whether the current thread is the display events thread.
boolean	isDisplayThread(java.lang.Thread thread) Gets whether the given thread is the display events thread.
boolean	isDoubleBuffered() Returns if the display uses an underlying double buffer (either hardware or software).
void	setBacklight(int backlight) Sets the backlight of the display.
void	setBacklightColor(int rgbColor) Sets the current backlight color, if it is allowed by implementation.
void	setContrast(int contrast) Sets the contrast of the display.
void	setPriority(int priority) Sets the priority of the display events processing.
void	switchBacklight(boolean on) Switches on or off the backlight of the display.
void	waitForEvent() Blocks the current thread (with all its locks) until all events outstanding at the time of the call have been processed.
void	waitForEvent(int event) Sends event in the event stream and blocks the current thread (with all its locks) until the event processing is finished.

Methods inherited from class java.lang.Object

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

Constructor Detail

Display

public Display()

Method Detail

getEventSerializer

public EventHandler getEventSerializer()

Returns the display's event serializer or null.

Returns:

the display's event serializer or null.

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.

getBPP

public int getBPP()

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

getNumberOfAlphaLevels

public int getNumberOfAlphaLevels()

Gets the number of alpha transparency levels supported by the implementation.

The minimum possible is 2, which represents full transparency and full opacity with no blending. If the return value is greater than 2, the implementation manages blending.

Returns:

the number of alpha levels

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 final 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)

switchBacklight

public void switchBacklight(boolean on)

Switches on or off the backlight of the display.

Parameters:

on - Switch on the backlight if true; switch off the backlight if false

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)

setBacklightColor

public void setBacklightColor(int rgbColor)

Sets the current backlight color, if it is allowed by implementation.

Parameters:

rgbColor - the color to set

getBacklightColor

public int getBacklightColor()

Returns the current backlight color. Returned value is interpreted as a 24-bit RGB color, where the eight less significant bits matches the blue component, the next eight bits matches the green component and the next eight bits matches the red component. By default, this method returns 0xFFFFFF (white) and sub-classes should overwrite this default behavior.

Returns:

the color of the backlight

getAllDisplays

public static Display[] getAllDisplays()
                                throws java.lang.IllegalStateException

Returns all available displays. It is never null but the array may be empty.

Returns:

all available displays.

Throws:

java.lang.IllegalStateException - if MicroUI is not started.

getDefaultDisplay

public static Display getDefaultDisplay()
                                 throws java.lang.IllegalStateException

Returns the default display of the system. It can be null if there is no display. The notion of default display is defined by the implementation.

Returns:

the default display or null.

Throws:

java.lang.IllegalStateException - if MicroUI is not started.

getDisplayable

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

getNewGraphicsContext

public GraphicsContext getNewGraphicsContext()

Returns a new GraphicsContext which works on the same system screen as this display. With this GraphicsContext, it is possible to draw on the system screen at any time without modifying the normal system execution. The new graphics context has its own clip, color, font etc. After each draw action (a drawLine for example), the system screen will show the drawn pixels.
If the normal system execution is repainting at the same time, the last draw action 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.

Returns:

a new graphics context on the display

Throws:

java.lang.OutOfMemoryError - if there is not enough room to add a new graphics context.

getNewExplicitFlush

public ExplicitFlush getNewExplicitFlush()

Returns a new ExplicitFlush which works on the same system screen as this display. With this ExplicitFlush, it is possible to draw on the system screen at any time without modifying the normal system execution. The new graphics context has its own clip, color, font etc. Each draw action will not be automatically flushed. The user has to flush it via the ExplicitFlush.flush() method.
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.

Returns:

a new graphics context with explicit flush on the display

Throws:

java.lang.OutOfMemoryError - if there is not enough room to add a new graphics context.

getScreenshot

public Image getScreenshot()

Creates an image with the full content of the display.

This call is identical to: getScreenshot(0, 0, display.getWidth(), display.getHeight()).

Returns:

the created image.

Throws:

ImageCreationException - if MicroUI implementation cannot create the image.

java.lang.OutOfMemoryError - if there is not enough room to add a new image.

Since:

2.0

See Also:

GraphicsContext.drawRegion(Display, int, int, int, int, int, int, int, int)

getScreenshot

public Image getScreenshot(int x,
                           int y,
                           int width,
                           int height)

Creates an image with the content of the display region specified thanks the given rectangle.

Parameters:

x - the x coordinate of the upper-left corner of the region to copy.

y - the y coordinate of the upper-left corner of the region to copy.

width - the width of the region to copy.

height - the height of the region to copy.

Returns:

the created image.

Throws:

java.lang.IllegalArgumentException - if the zone to copy is out of the bounds of the source image or if either width or height is zero or negative.

ImageCreationException - if MicroUI implementation cannot create the image.

java.lang.OutOfMemoryError - if there is not enough room to add a new image.

Since:

2.0

See Also:

GraphicsContext.drawRegion(Display, int, int, int, int, int, int, int, int)

callSerially

public void callSerially(java.lang.Runnable run)

Serializes a call event in the system event stream. When the event is processed, the run() method of the Runnable object is called.
Multiple call events may be requested with callSerially(): they will occur in the order in which they were requested (first in first out policy).
The call to the run() method of the Runnable object is performed asynchronously Therefore callSerially() will never block waiting for the run() method to finish.
The run() method should return quickly, as with other callback methods.
The callSerially() mechanism may be used by applications as a synchronization tool in the event stream.

Parameters:

run - a Runnable object to call

Throws:

java.lang.SecurityException - if a security manager exists and does not allow the caller to get the display.

waitForEvent

public void waitForEvent(int event)

Sends event in the event stream and blocks the current thread (with all its locks) until the event processing is finished.

Parameters:

event - the event to send and to wait for.

Throws:

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

waitForEvent

public void waitForEvent()

Blocks the current thread (with all its locks) until all events outstanding at the time of the call have been processed.

Throws:

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

isDisplayThread

public boolean isDisplayThread(java.lang.Thread thread)

Gets whether the given thread is the display events thread.

Parameters:

thread - the thread to check

Returns:

true if the given thread is the display events thread, false otherwise.

Since:

2.0

isDisplayThread

public boolean isDisplayThread()

Gets whether the current thread is the display events thread.

Returns:

true if the current thread is the display events thread, false otherwise.

Since:

2.0

setPriority

public void setPriority(int priority)

Sets the priority of the display events processing.

Parameters:

priority - the new priority of display events processing

Throws:

java.lang.IllegalArgumentException - If the priority is not in the range Thread.MIN_PRIORITY to Thread.MAX_PRIORITY.

handleEvent

public void handleEvent(int event)

Injects a MicroUI event to be handled by the event generator associated with this Display.

Parameters:

event - an event in the MicroUI format