ej.fp

Class Widget

java.lang.Object

ej.fp.Widget

Direct Known Subclasses:

Composite, Display, LED, WidgetWithListener

public abstract class Widget
extends Object

Widget is the superclass of all the user interface objects. It represents a part of a device that can be graphically represented.

A widget is created by the front panel parser. The parser sets its characteristics (configuration step) and ask the widget to check its own configuration (finalizeConfiguration(). When all widgets in the hierarchy have been created and checked, each widget is started (start().

The parser is using the widget description (Widget.WidgetDescription) to retrieve the widget itself and the widget characteristics the parser can set. Each widget concrete subclass must define its own Widget.WidgetDescription in order to be recognized by the parser. This description must be written in the class java doc.

Example:

 
 /**
  * @WidgetDescription(
  *     attributes = {
  *             @WidgetAttribute(name = "label"),
  *             @WidgetAttribute(name = "x"),
  *             @WidgetAttribute(name = "y"),
  *             @WidgetAttribute(name = "ledOff"),
  *             @WidgetAttribute(name = "ledOn"),
  *             @WidgetAttribute(name = "overlay", isOptional = true)
  *     }
  * )
  */
  public class LED extends Widget {
        // ...
  }
 
 

This description allows the user to use this widget declaration in his/her front panel file (*.fp):

 <ej.fp.widget.LED label="3" x="140" y="753" ledOff="Led-0.png" ledOn="Led-BLUE.png" overlay="false"/>
 

As soon as a widget holds a description, the parser is able to load the corresponded class. The class is retrieved thanks the widget declaration in the front panel file: package.WidgetClassName. The widget constructor must be empty (no argument).

A Widget.WidgetAttribute allows the parser to call the corresponded method setXxx(), where Xxx id the Widget.WidgetAttribute name field, to configure a widget characteristic.

This method must exist in the widget hierarchy. If not, an error during parsing will be thrown to stop the execution.

Some setXxx() methods can exist in the widget hierarchy whereas they are not described in Widget.WidgetDescription of this widget. The parser will never call these methods. These methods and the associated attributes are optional; it is the responsability to the widget to add (and use) them in its own description.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Widget.WidgetAttribute This interface describes only one attribute of the widget description.
static interface	Widget.WidgetDescription This interface allows a subclass of Widget to describe itself.

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_LABEL Default widget label when no label is defined by front panel file.

Constructor Summary

Constructors

Constructor and Description
Widget() Creates a widget.

Method Summary

Modifier and Type	Method and Description
void	dispose() Disposes the widget's associated resources (such as threads, images...).
void	finalizeConfiguration() Checks whether the widget configuration is valid or not and finalizes the widget configuration according all attributes previously set.
int	getAbsoluteX() Gets the absolute x coordinate of this widget.
int	getAbsoluteY() Gets the absolute y coordinate of this widget.
Image	getCurrentSkin() Gets the current skin to render.
Image	getFilter() Gets the image which represents the filtering area set by the front panel parser thanks setFilter(Image) method).
int	getHeight() Gets the height of this widget set by the front panel parser thanks setSkin(Image) method).
String	getLabel() Gets the label (default label DEFAULT_LABEL or the label set by the front panel parser thanks setLabel(String) method).
Composite	getParent() Gets the parent (Composite) of this widget.
Image	getSkin() Gets the default skin of this widget set by the front panel parser thanks setSkin(Image) method).
int	getWidth() Gets the width of this widget set by the front panel parser thanks setSkin(Image) method).
int	getX() Gets the relative x coordinate of this widget set by the front panel parser thanks setX(int) method).
int	getY() Gets the relative y coordinate of this widget set by the front panel parser thanks setY(int) method).
boolean	isOver(int x, int y) Tells whether the specified point is inside the bounds of the wanted form.
void	repaint() Asks a repaint of the receiver on the device.
void	repaint(int x, int y, int width, int height) Asks a repaint of a part of the receiver on the device.
void	setCurrentSkin(Image skin) Sets the current skin to render according the widget state.
void	setFilter(Image filter) Sets an image which defines a filtering area.
void	setHeight(int height) Sets the height of this widget.
void	setLabel(String label) Sets the label (tag) of this widget.
void	setOverlay(boolean overlay) Sets the repaint policy.
void	setSkin(Image skin) Sets the default skin of this widget.
void	setWidth(int width) Sets the width of widget.
void	setX(int x) Sets the x relative coordinate of this widget.
void	setY(int y) Sets the y relative coordinate of this widget.
void	showYourself(boolean appearSwitchedOn) Called by front panel viewer to make widgets appear as if "switched on" or not.
void	start() Starts the widget.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_LABEL

public static final String DEFAULT_LABEL

Default widget label when no label is defined by front panel file.

See Also:

Constant Field Values

Constructor Detail

Widget

public Widget()

Creates a widget.

By default:

• its bounds are 0,
• it is not visible,
• its label is "" (empty string).

Method Detail

dispose

public void dispose()

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.

finalizeConfiguration

public void finalizeConfiguration()

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

Throws:

IllegalStateException - when a filter has been set whereas there is no skin or when skin and filter bounds are not equal.

getAbsoluteX

public int getAbsoluteX()

Gets the absolute x coordinate of this widget.

Returns:

the absolute x coordinate of this widget.

getAbsoluteY

public int getAbsoluteY()

Gets the absolute y coordinate of this widget.

Returns:

the absolute y coordinate of this widget.

getCurrentSkin

public Image getCurrentSkin()

Gets the current skin to render.

This skin can change at runtime to visualize the widget state. For instance a button has at least two states: pressed and released. Released state is often the default state so the widget skin (setSkin(Image)) should represent the button released. On button pressed, this method should return another image which represents the button pressed.

Note that the returned image can be higher or smaller than the widget size. The framework will perform an image deformation.

Returns:

the current skin to render.

See Also:

setCurrentSkin(Image)

getFilter

public Image getFilter()

Gets the image which represents the filtering area set by the front panel parser thanks setFilter(Image) method).

Returns:

the filtering area image.

getHeight

public int getHeight()

Gets the height of this widget set by the front panel parser thanks setSkin(Image) method).

Returns:

the height.

getLabel

public String getLabel()

Gets the label (default label DEFAULT_LABEL or the label set by the front panel parser thanks setLabel(String) method).

Returns:

the widget label.

getParent

public Composite getParent()

Gets the parent (Composite) of this widget.

Returns:

the parent of this widget.

getSkin

public Image getSkin()

Gets the default skin of this widget set by the front panel parser thanks setSkin(Image) method).

Returns:

the default skin.

getWidth

public int getWidth()

Gets the width of this widget set by the front panel parser thanks setSkin(Image) method).

Returns:

the width.

getX

public int getX()

Gets the relative x coordinate of this widget set by the front panel parser thanks setX(int) method).

Returns:

the relative x coordinate.

getY

public int getY()

Gets the relative y coordinate of this widget set by the front panel parser thanks setY(int) method).

Returns:

the relative y coordinate.

isOver

public boolean isOver(int x,
                      int y)

Tells whether the specified point is inside the bounds of the wanted form. In other terms, if this widget must receive an event when the mouse is over this point.

The point is relative to the composite of this widget.

By default, return true if the point is inside the bounds of the widget (rectangle) AND id the point is inside the filtering area (@see setFilter(Image)).

Parameters:

x - the x coordinates of the point to check.

y - the y coordinates of the point to check.

Returns:

true if the point is over this widget, false otherwise.

repaint

public void repaint()

Asks a repaint of the receiver on the device. The effective repaint is platform dependent. Framework cannot ensure the result nor the synchronization.

repaint

public void repaint(int x,
                    int y,
                    int width,
                    int height)

Asks a repaint of a part of the receiver on the device. The effective repaint is platform dependent. Framework cannot ensure the result nor the synchronization.

Parameters:

x - x coordinate of area to repaint

y - y coordinate of area to repaint

width - width of area to repaint

height - height of area to repaint

setCurrentSkin

public void setCurrentSkin(Image skin)

Sets the current skin to render according the widget state.

This skin will be rendered on the device. If the skin is null, the receiver will be invisible. The method repaint() is called just after the update to force to render the new currebt skin.

Parameters:

skin - the new skin to render.

See Also:

getCurrentSkin()

setFilter

public void setFilter(Image filter)

Sets an image which defines a filtering area. The method isOver(int, int) returns false if the given coordinates are inside the skin area but outside the filtering area.

The filter image and the widget size must have the same size. If not, an error will be thrown when the parser will check the widget configuration (finalizeConfiguration()).

The filtering area is defined by the pixels whose color is not fully transparent (alpha > 0).

By default there is no filtering area and all pixels in skin are considered inside the filtering area.

This method should only be called by front panel parser.

Parameters:

filter - the image which defines the filtering area.

setHeight

public void setHeight(int height)

Sets the height of this widget.

Parameters:

height - the height coordinate to set.

Throws:

IllegalArgumentException - when the height is negative.

setLabel

public void setLabel(String label)

Sets the label (tag) of this widget. When null or not set, the default string "" (empty string) is used. This label is useful to retrieve a specific widget in the device hierarchy.

This method should only be called by front panel parser.

Parameters:

label - the widget label.

See Also:

Device.getWidget(Class, String)

setOverlay

public final void setOverlay(boolean overlay)

Sets the repaint policy. If true, the current skin (getCurrentSkin() is drawn over the existent image; otherwise the background and the other widgets behind are drawn before rendering this widget.

By default, overlay is false.

This method should only be called by front panel parser.

Parameters:

overlay - the repaint policy.

See Also:

repaint(), repaint(int, int, int, int)

setSkin

public void setSkin(Image skin)

Sets the default skin of this widget.

The skin defines too the widget bounds (width and height). It may be null, in this case the widget will be not rendered.

When not null, the bounds optionaly set by setWidth(int) and setHeight(int) will be replaced by skin bounds during the widget configuration (finalizeConfiguration()).

Default skin is null.

This method should only be called by front panel parser.

Parameters:

skin - the skin to set.

setWidth

public void setWidth(int width)

Sets the width of widget.

Parameters:

width - the width coordinate to set.

Throws:

IllegalArgumentException - when the width is negative.

setX

public void setX(int x)

Sets the x relative coordinate of this widget. The coordinate is relative to the widget's composite position.

Default position is 0,0.

This method should only be called by front panel parser.

Parameters:

x - the x coordinate to set.

setY

public void setY(int y)

Sets the y relative coordinate of this widget. The coordinate is relative to the widget's composite position.

Default position is 0,0.

This method should only be called by front panel parser.

Parameters:

y - the y coordinate to set.

showYourself

public void showYourself(boolean appearSwitchedOn)

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.

Parameters:

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

start

public void start()

Starts the widget. For instance a widget can start a thread, call methods on other widgets (all widgets are created and finalized, see finalizeConfiguration()).

Main implementation does nothing.

This method should only be called by front panel engine.