org.havi.ui.event

Class HEventRepresentation

java.lang.Object

org.havi.ui.event.HEventRepresentation

public class HEventRepresentation
extends Object

This class is able to describe the representation of an event generator as a string, color or symbol (such as a triangle, '>', for 'play'). This allows an application to describe a button on an input device correctly for a given platform.

The particular text, color, or symbol can be determined by calling the getString, getColor or getSymbol methods respectively. All available events should return a valid text representation from the getString method.

If supported the six colored key events (VK_COLORED_KEY_0 thru VK_COLORED_KEY_5) must also be represented by a color, i.e. the getColor method must return a valid java.awt.Color object.

Key events may also be represented as a symbol - if the platform does not support a symbolic representation for a given event, then the application is responsible for rendering the symbol itself. The rendering of keys with a commonly known representation should follow the guidelines given here, as defined in the following table.

Event	Implied symbol	Sample
VK_GO_TO_START	Two equilateral triangles, pointing at a line to the left
VK_REWIND	Two equilateral triangles, pointing to the left
VK_STOP	A square
VK_PAUSE	Two vertical lines, side by side
VK_PLAY	One equilateral triangle, pointing to the right
VK_FAST_FWD	Two equilateral triangles, pointing to the right
VK_GO_TO_END	Two equilateral triangles, pointing to a line at the right
VK_TRACK_PREV	One equilateral triangle, pointing to a line at the left
VK_TRACK_NEXT	One equilateral triangle, pointing to a line at the right
VK_RECORD	A circle, normally red
VK_EJECT_TOGGLE	A line under a wide triangle which points up
VK_VOLUME_UP	A ramp, increasing to the right, near a plus sign
VK_VOLUME_DOWN	A ramp, increasing to the right, near a minus sign
VK_UP	An arrow pointing up
VK_DOWN	An arrow pointing down
VK_LEFT	An arrow pointing to the left
VK_RIGHT	An arrow pointing to the right
VK_POWER	A circle, broken at the top, with a vertical line in the break

The parameters to the constructors are as follows, in cases where parameters are not used, then the constructor should use the default values.

Default parameter values exposed in the constructors

Parameter	Description	Default value	Set method	Get method
None.

Default parameter values not exposed in the constructors

Description	Default value	Set method	Get method
None.

Field Summary

Fields

Modifier and Type	Field and Description
static int	ER_TYPE_COLOR The event representation type for the current event is supported as a color.
static int	ER_TYPE_NOT_SUPPORTED The event representation type for the current event is not supported.
static int	ER_TYPE_STRING The event representation type for the current event is supported as a string.
static int	ER_TYPE_SYMBOL The event representation type for the current event is supported as a symbol.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	HEventRepresentation() An interoperable application shall not subclass the HEventRepresentation class.

Method Summary

Methods

Modifier and Type	Method and Description
Color	getColor() This returns the color representation (generally used for colored soft keys) of the current event code.
String	getString() Returns the text representation of the current event code.
Image	getSymbol() This returns an image-based representation (generally used for symbolic keys) of the current event code.
int	getType() This returns the type of representation(s) available for the event code which this instance of HEventRepresentation represents.
boolean	isSupported() This method returns true if the current event is supported by the platform.
protected void	setColor(Color aColor) Sets the Color representation for this HEventRepresentation.
protected void	setString(String aText) Sets the string representation for this HEventRepresentation.
protected void	setSymbol(Image aSymbol) Sets the symbolic representation for this HEventRepresentation.
protected void	setType(int aType) Sets the type of representation(s) available for the event code which this this instance of HEventRepresentation represents.

Methods inherited from class java.lang.Object

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

Field Detail

ER_TYPE_NOT_SUPPORTED

public static final int ER_TYPE_NOT_SUPPORTED

The event representation type for the current event is not supported.

The four ER_TYPE integers describe if an input mechanism is not supported, or is described by a string, color or symbol.

The values of the four ER_TYPE integers are required to be bitwise distinct, and the value of ER_TYPE_NOT_SUPPORTED should be 0.

See Also:

ER_TYPE_STRING, ER_TYPE_COLOR, ER_TYPE_SYMBOL, Constant Field Values

ER_TYPE_STRING

public static final int ER_TYPE_STRING

The event representation type for the current event is supported as a string.

See Also:

ER_TYPE_NOT_SUPPORTED, Constant Field Values

ER_TYPE_COLOR

public static final int ER_TYPE_COLOR

The event representation type for the current event is supported as a color.

See Also:

ER_TYPE_NOT_SUPPORTED, Constant Field Values

ER_TYPE_SYMBOL

public static final int ER_TYPE_SYMBOL

The event representation type for the current event is supported as a symbol.

See Also:

ER_TYPE_NOT_SUPPORTED, Constant Field Values

Constructor Detail

HEventRepresentation

protected HEventRepresentation()

An interoperable application shall not subclass the HEventRepresentation class.

Creates an HEventRepresentation object. See the class description for details of constructor parameters and default values.

This method is protected to allow the platform to override it in a different package scope.

Method Detail

isSupported

public boolean isSupported()

This method returns true if the current event is supported by the platform.

setType

protected void setType(int aType)

Sets the type of representation(s) available for the event code which this this instance of HEventRepresentation represents. If no representation(s) are available then aType should be set to ER_TYPE_NOT_SUPPORTED. Otherwise the representation should be set to the sum of one or more of the following: ER_TYPE_STRING, ER_TYPE_COLOR, ER_TYPE_SYMBOL.

For example, if both string and color representations are available then the system should call this method with the parameter set to ER_TYPE_STRING + ER_TYPE_COLOR.

This method is protected to allow the platform to override it in subclasses of HEventRepresentation. It is not intended for use by the application and conformant applications shall not use this method.

Parameters:

aType - the type of representation(s) available for this event

getType

public int getType()

This returns the type of representation(s) available for the event code which this instance of HEventRepresentation represents.

If the event code can be represented in multiple ways, then the returned type will be the sum of the supported types, e.g. an event generated by a key with a particular font representation of an "A" in yellow might return ER_TYPE_STRING + ER_TYPE_COLOR + ER_TYPE_SYMBOL. Where the string representation is "A", the color representation is "yellow" and the symbol representation might be a likeness of the "A glyph" from a particular font.

setColor

protected void setColor(Color aColor)

Sets the Color representation for this HEventRepresentation. Any previous value is overwritten.

This method is protected to allow the platform to override it in subclasses of HEventRepresentation. It is not intended for use by the application and conformant applications shall not use this method.

Parameters:

aColor - - the color to be associated with this event.

getColor

public Color getColor()

This returns the color representation (generally used for colored soft keys) of the current event code.

Returns:

The color representation of the current event code, or null if not available.

setString

protected void setString(String aText)

Sets the string representation for this HEventRepresentation. Any previous value is overwritten.

This method is protected to allow the platform to override it in subclasses of HEventRepresentation. It is not intended for use by the application and conformant applications shall not use this method.

Parameters:

aText - - the text string to be associated with this event.

getString

public String getString()

Returns the text representation of the current event code.

Returns:

The text representation of the current event code, or null if not available.

setSymbol

protected void setSymbol(Image aSymbol)

Sets the symbolic representation for this HEventRepresentation. Any previous value is overwritten.

This method is protected to allow the platform to override it in subclasses of HEventRepresentation. It is not intended for use by the application and conformant applications shall not use this method.

Parameters:

aSymbol - - the symbol image to be associated with this event.

getSymbol

public Image getSymbol()

This returns an image-based representation (generally used for symbolic keys) of the current event code.

Note that it is platform specific whether this method will return a valid Image, in particular it is a valid implementation option to always return null. Note that for non-null Images, the size and other Image characteristics are dependent on particular manufacturer implementation.

Returns:

The symbolic representation of the current event code, or null if not available.