ej.fp.widget

Class Display

java.lang.Object

ej.fp.Widget

ej.fp.widget.Display

All Implemented Interfaces:

LLUIDisplayImpl

public class Display
extends Widget
implements LLUIDisplayImpl

This widget is an implementation of MicroUI LLUIDisplayImpl interface. An implementation of this interface is required to be able to use a MicroUI Display in a MicroEJ application.

This widget has been implemented to target a standard display: a display whose pixel format is LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB8888 , LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_RGB888, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_RGB565, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB1555, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB4444, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C4, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C2 or LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C1. To avoid to create a subclass of this class when the pixel format is custom, an extension of this widget can be set in front panel description file (fp file) using the widget attribute extensionClass.

This widget manages the double buffering mode (see LLUIDisplayImpl.isDoubleBuffered(). However all involved methods by this notion are implemented according the value returned by isDoubleBuffered(). The optional widget attribute doubleBufferFeature can be configured to override default behavior (enabled by default).

This widget manages a backlight with dimming (0 to 100%) (see LLUIDisplayImpl.hasBacklight(). However all involved methods by this notion are implemented according the value returned by hasBacklight(). The optional widget attribute backlightFeature can be configured to override default behavior (enabled by default).

The filter image is used to define the display rendering area. Outside this area, the display buffer data is not drawn. This image must have the same size (@see Widget.setWidth(int) and Widget.setHeight(int)) than the widget itself. If not, an error is thrown in finalizeConfiguration().

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Display.DisplayExtension This interface is a subset of LLUIDisplayImpl interface (provided by MicroUI graphical engine and required to use a MicroUI Display in a MicroEJ application).

Nested classes/interfaces inherited from class ej.fp.Widget

Widget.WidgetAttribute, Widget.WidgetDescription

Field Summary

Fields

Modifier and Type	Field and Description
protected Image	drawingBuffer When the display is double buffered, the backBuffer represents the back buffer where drawings are done.
protected Image	frameBuffer This buffer contains the application drawings after the call to #flush(MicroUIGraphicsContext, Image, int, int, int, int) in double buffer mode or during application rendering in simple buffer mode.
protected Image	visibleBuffer Buffer visible on front panel viewer: contains application drawings (see frameBuffer) and some post transformations like mask reduction, backlight and contrast.

Fields inherited from class ej.fp.Widget

DEFAULT_LABEL

Fields inherited from interface ej.microui.display.LLUIDisplayImpl

BACKLIGHT_MAX, BACKLIGHT_MIN, CONTRAST_MAX, CONTRAST_MIN

Constructor Summary

Constructors

Constructor and Description
Display() Creates the widget display

Method Summary

Modifier and Type	Method and Description
int	convertARGBColorToDisplayColor(int argbColor) Converts the 32-bit ARGB color format (A-R-G-B) into the display color format.
int	convertDisplayColorToARGBColor(int displayColor) Converts the display color format into a 32-bit ARGB color format (A-R-G-B).
void	dispose() Disposes the widget's associated resources (such as threads, images...).
protected void	drawBacklight(Image imageSkin) Transforms the skin data applying an algorithm to simulate the display backlight.
protected void	drawContrast(Image imageSkin) Transforms the skin data applying an algorithm to simulate the display contrast.
void	finalizeConfiguration() Checks whether the widget configuration is valid or not and finalizes the widget configuration according all attributes previously set.
void	flush(LLUIPainter.MicroUIGraphicsContext gc, Image image, int x, int y, int width, int height) Flushes a part of the display limited by specified bounds.
int	getBacklight() Returns the backlight of the display.
Image	getCurrentSkin() Gets the current displayed skin.
Image	getDrawingBuffer() Gets the buffer when drawings are rendered before being copied in frame buffer (call to #flush(MicroUIGraphicsContext, Image, int, int, int, int).
int	getInitialColor() Gets the initial color of the display.
int	getNumberOfColors() Gets the number of colors that can be represented on the device.
boolean	hasBacklight() Returns true if the display holds a backlight.
Image	initialize() Called by MicroUI graphical engine when MicroUI.start() is called by the MicroEJ application.
boolean	isColor() Asks if the display is a colored display or not.
boolean	isDoubleBuffered() Returns if the display uses an underlying double buffer.
protected Image	newDisplayImage() Creates a new image with the same size than display (not widget size).
protected Image	newWidgetImage() Creates a new image with the same size than widget (not display size).
boolean	prepareBlendingOfIndexedColors(java.util.concurrent.atomic.AtomicInteger foreground, java.util.concurrent.atomic.AtomicInteger background) Prepares the blending of two ARGB colors.
void	setAlpha(int alpha) Sets the opacity level (alpha) of the display in order to obtain a translucent display.
void	setBacklight(int backlight) Sets the backlight of the display.
void	setBacklightFeature(boolean enable) Enables or disables the backlight feature.
void	setDisplayHeight(int height) Sets the height of the display in pixels (see class comment).
void	setDisplayWidth(int width) Sets the width of the display in pixels (see class comment).
void	setDoubleBufferFeature(boolean enable) Enables or disables the double buffering feature.
void	setExtensionClass(String extensionClassName) Defines the optional class name of the display extension.
void	setInitialColor(int initialColor) Sets the initial color of the display (color used on startup, just before first drawing).
void	showYourself(boolean appearSwitchedOn) Called by front panel viewer to make widgets appear as if "switched on" or not.
void	start() Called by the parser after filling all the fields defined in the xml.

Methods inherited from class ej.fp.Widget

getAbsoluteX, getAbsoluteY, getFilter, getHeight, getLabel, getParent, getSkin, getWidth, getX, getY, isOver, repaint, repaint, setCurrentSkin, setFilter, setHeight, setLabel, setOverlay, setSkin, setWidth, setX, setY

Methods inherited from class java.lang.Object

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

Methods inherited from interface ej.microui.display.LLUIDisplayImpl

getContrast, setContrast

Field Detail

drawingBuffer

protected Image drawingBuffer

When the display is double buffered, the backBuffer represents the back buffer where drawings are done. At flush time, the backBuffer is copied on this display. When the display is simple buffered, the backBuffer and frame buffer are equals and all drawings are performed in this buffer.

frameBuffer

protected Image frameBuffer

This buffer contains the application drawings after the call to #flush(MicroUIGraphicsContext, Image, int, int, int, int) in double buffer mode or during application rendering in simple buffer mode.

visibleBuffer

protected Image visibleBuffer

Buffer visible on front panel viewer: contains application drawings (see frameBuffer) and some post transformations like mask reduction, backlight and contrast.

Constructor Detail

Display

public Display()

Creates the widget display

Method Detail

convertARGBColorToDisplayColor

public int convertARGBColorToDisplayColor(int argbColor)

Description copied from interface: LLUIDisplayImpl

Converts the 32-bit ARGB color format (A-R-G-B) into the display color format.

This function is called only when the display is not a standard display: when the pixel data does not match with one of these formats: LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB8888 , LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_RGB888, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_RGB565, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB1555, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB4444, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C4, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C2 or LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C1.

In case of this function is not implemented whereas it is required, the result of pixel drawing is unknown.

Note: the opacity level (alpha) may be ignored if the display pixel representation does not hold the opacity level information.

The implementation should not directly call this function when performing a drawing. It must call LLUIDisplay.convertARGBColorToColorToDraw(int) instead in case of this conversion is graphical engine built-in (standard display).

Specified by:

convertARGBColorToDisplayColor in interface LLUIDisplayImpl

Parameters:

argbColor - the color to convert.

Returns:

the display color equivalent to microUIColor.

convertDisplayColorToARGBColor

public int convertDisplayColorToARGBColor(int displayColor)

Description copied from interface: LLUIDisplayImpl

Converts the display color format into a 32-bit ARGB color format (A-R-G-B).

This function is called only when the display is not a standard display: when the pixel data does not match with one of these formats: LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB8888 , LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_RGB888, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_RGB565, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB1555, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB4444, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C4, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C2 or LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C1.

In case of this function is not implemented whereas it is required, the result of pixel drawing is unknown.

Note: the opacity level (alpha) may be ignored if the display pixel representation does not hold the opacity level information.

Specified by:

convertDisplayColorToARGBColor in interface LLUIDisplayImpl

Parameters:

displayColor - the color to convert.

Returns:

the MicroUI color equivalent to displayColor.

dispose

public void dispose()

Description copied from class: Widget

Disposes the widget's associated resources (such as threads, images...).

Default behavior disposes the common images and subclasses should override this method to define their own behavior.

This method should only be called by front panel engine.

Overrides:

dispose in class Widget

drawBacklight

protected void drawBacklight(Image imageSkin)

Transforms the skin data applying an algorithm to simulate the display backlight.

Parameters:

imageSkin - the image where applying the algorithm.

drawContrast

protected void drawContrast(Image imageSkin)

Transforms the skin data applying an algorithm to simulate the display contrast.

The default implementation performs nothing.

Parameters:

imageSkin - the image where applying the algorithm.

finalizeConfiguration

public void finalizeConfiguration()

Description copied from class: Widget

Checks whether the widget configuration is valid or not and finalizes the widget configuration according all attributes previously set.

The widget attributes are set by the front panel parser but the order is not defined. This method allows to perform some checks between several attributes (this method is called by the front panel parser after setting all attributes defined in front panel file).

The configuration validation depends on widget itself. Each subclass must verify its configuration after checking its parent configuration.

When framework calling this method, all device widgets are not created and finalized yet, and by extension the device itself is not fully created too. So the implementation must not have to call some methods on other widgets and the methods Device.getDevice() or FrontPanel.getDevice(). As soon as all widgets are created and finalized, the simulation starts calling the method Widget.start() on each widget. As this moment only, the widget is able to use the other widgets and the device itself.

On configuration error, a RuntimeException (or a subclass of RuntimeException) must be thrown.

This method should only be called by front panel parser.

Overrides:

finalizeConfiguration in class Widget

flush

public void flush(LLUIPainter.MicroUIGraphicsContext gc,
                  Image image,
                  int x,
                  int y,
                  int width,
                  int height)

Description copied from interface: LLUIDisplayImpl

Flushes a part of the display limited by specified bounds. If the display do not have a backBuffer (not double buffered), nothing is done.

Specified by:

flush in interface LLUIDisplayImpl

Parameters:

gc - the graphics context to flush

image - the image returned by LLUIDisplayImpl.initialize()

x - the x coordinate of the area to flush.

y - the x coordinate of the area to flush.

width - the width of the area to flush.

height - the height of the area to flush.

getBacklight

public int getBacklight()

Returns the backlight of the display. backlight value range is LLUIDisplayImpl.BACKLIGHT_MIN-LLUIDisplayImpl.BACKLIGHT_MAX. If the display do not manage backlight ( hasBacklight() == false), returns LLUIDisplayImpl.BACKLIGHT_MIN.

Specified by:

getBacklight in interface LLUIDisplayImpl

Returns:

the backlight of the display.

getCurrentSkin

public Image getCurrentSkin()

Gets the current displayed skin.

Overrides:

getCurrentSkin in class Widget

Returns:

the current displayed skin.

See Also:

Widget.setCurrentSkin(Image)

getDrawingBuffer

public Image getDrawingBuffer()

Gets the buffer when drawings are rendered before being copied in frame buffer (call to #flush(MicroUIGraphicsContext, Image, int, int, int, int).

Returns:

the buffer when performing the drawings

getInitialColor

public int getInitialColor()

Gets the initial color of the display.

Returns:

the initial color.

getNumberOfColors

public int getNumberOfColors()

Description copied from interface: LLUIDisplayImpl

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. Usually the number of colors is 1 << BPP (BPP without transparency bits).

By default this method returns a value which follows this default rule.

Specified by:

getNumberOfColors in interface LLUIDisplayImpl

Returns:

the number of colors of the display.

hasBacklight

public boolean hasBacklight()

Description copied from interface: LLUIDisplayImpl

Returns true if the display holds a backlight. By default this method returns false (feature not supported).

Specified by:

hasBacklight in interface LLUIDisplayImpl

Returns:

true when widget manages display backlight.

initialize

public Image initialize()

Called by MicroUI graphical engine when MicroUI.start() is called by the MicroEJ application.

Specified by:

initialize in interface LLUIDisplayImpl

Returns:

the buffer where performing the MicroUI drawing.

isColor

public boolean isColor()

Description copied from interface: LLUIDisplayImpl

Asks if the display is a colored display or not.

By default this method returns false when the display pixel depth is lower than or equals to 4 and true otherwise.

Specified by:

isColor in interface LLUIDisplayImpl

Returns:

true when the display is not a grayscale display, false otherwise.

isDoubleBuffered

public boolean isDoubleBuffered()

Description copied from interface: LLUIDisplayImpl

Returns if the display uses an underlying double buffer.

By default this method returns true and considers the interface implementation returns a "back" buffer in LLUIDisplayImpl.initialize(). This buffer is used to render the MicroUI drawings in background. When MicroUI Display.flush() method is called, a call to #flush(MicroUIGraphicsContext, Image, int, int, int, int) is performed. The implementation has to copy the image content to another image (visible on front panel).

Implementation can override this method to return false. In this case the image returned by LLUIDisplayImpl.initialize() is used as rendering buffer for MicroUI drawings and as visible buffer on front panel at same time.

Specified by:

isDoubleBuffered in interface LLUIDisplayImpl

Returns:

true if the display is double buffered, else otherwise.

newDisplayImage

protected Image newDisplayImage()

Creates a new image with the same size than display (not widget size).

Returns:

an image as big as display.

newWidgetImage

protected Image newWidgetImage()

Creates a new image with the same size than widget (not display size).

Returns:

an image as big as widget.

prepareBlendingOfIndexedColors

public boolean prepareBlendingOfIndexedColors(java.util.concurrent.atomic.AtomicInteger foreground,
                                              java.util.concurrent.atomic.AtomicInteger background)

Description copied from interface: LLUIDisplayImpl

Prepares the blending of two ARGB colors.

This function is called only when the display is not a standard display: when the pixel data does not match with one of these formats: LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB8888 , LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_RGB888, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_RGB565, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB1555, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB4444, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C4, LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C2 or LLUIPainter.MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C1.

This is useful only when the LCD is a palletized LCD. This method is called by framework when the MicroEJ application draws something which requires a blending between the current foreground color and a specific background color (draw a string, draw an anti-aliased line etc.).

The implementation has to replace the ARGB colors by the indexes of these colors in the LCD CLUT. The framework will use the intermediate values between these two indexes instead of blending in software the ARGB colors. No post conversion will be performed later.

When the ARGB colors are not available in the CLUT or when the range specified by the two ARGB colors is not expected by the CLUT, the implementation should return false (feature not supported). In this way the blending will be done in software and the result color will be converted later thanks a call to LLUIDisplayImpl.convertARGBColorToDisplayColor(int).

By default the method returns false (feature not supported / useless).

Specified by:

prepareBlendingOfIndexedColors in interface LLUIDisplayImpl

Parameters:

foreground - the foreground ARGB color to convert.

background - the background ARGB color to convert.

Returns:

true when the indexes have been found, false otherwise.

setAlpha

public void setAlpha(int alpha)

Sets the opacity level (alpha) of the display in order to obtain a translucent display. By default the display is fully opaque.

This method should only be called by front panel parser.

Parameters:

alpha - the opacity level to set, 0x00 is fully transparent and 0xff fully opaque.

Throws:

IllegalArgumentException - if the given argument is not between 0x0 and 0xff.

setBacklight

public void setBacklight(int backlight)

Sets the backlight of the display.

Specified by:

setBacklight in interface LLUIDisplayImpl

Parameters:

backlight - the new value of the backlight.

setBacklightFeature

public void setBacklightFeature(boolean enable)

Enables or disables the backlight feature.

By default the backlight feature is enabled.

See LLUIDisplayImpl.hasBacklight() to have more information.

Parameters:

enable - true to enable backlight feature (default value).

setDisplayHeight

public void setDisplayHeight(int height)

Sets the height of the display in pixels (see class comment).

This method should only be called by front panel parser.

Parameters:

height - the height to set.

setDisplayWidth

public void setDisplayWidth(int width)

Sets the width of the display in pixels (see class comment).

This method should only be called by front panel parser.

Parameters:

width - the width to set.

setDoubleBufferFeature

public void setDoubleBufferFeature(boolean enable)

Enables or disables the double buffering feature.

By default the double buffering feature is enabled.

See LLUIDisplayImpl.isDoubleBuffered() to have more information.

Parameters:

enable - true to enable double buffering feature (default value).

setExtensionClass

public void setExtensionClass(String extensionClassName)

Defines the optional class name of the display extension. This allows to customize this display widget without creating a sub-class of Display.

When set, a check is performed in finalizeConfiguration() to verify whether this class is valid.

This method should only be called by front panel parser.

Parameters:

extensionClassName - the user display extension class name.

setInitialColor

public void setInitialColor(int initialColor)

Sets the initial color of the display (color used on startup, just before first drawing). By default the initial color is 0x0 (black).

This is a RGB color (24 bits: 8-8-8). Alpha level is ignored.

This method should only be called by front panel parser.

Parameters:

initialColor - the initial color to set.

showYourself

public void showYourself(boolean appearSwitchedOn)

Description copied from class: Widget

Called by front panel viewer to make widgets appear as if "switched on" or not. Useful to render widgets during the front panel device creation: it allows to show some "visual" widgets (display, LEDs etc.) as at runtime.

This method does nothing by default.

This method should only be called by front panel engine.

Overrides:

showYourself in class Widget

Parameters:

appearSwitchedOn - true to switch on widget, false to switch off.

start

public void start()

Called by the parser after filling all the fields defined in the xml. Used to complete the display initialization.

Overrides:

start in class Widget