8.8 Interface Design

The HAVi L2 GUI API is designed to enable application to present a TV-friendly GUI. The specification is explicitly designed to be suitable for use and implementation on a variety of consumer electronic devices. The APIs are contained in the org.havi.ui and org.havi.ui.event packages described in the accompanying Java documentation.

The HAVi L2 GUI allows applications, written in Java, to determine the user interface capabilities of its host display device, accept input from the user , draw to the screen and play audio clips. It uses the java.awt package component framework as its core and extends this with packages and classes specific to the HAVi platform. The HAVi component and container class-diagram relationships are depicted in Figures 8.4 and 8.5.

Figure 8.4. Class diagram for HAVi 1.1 containers.

Figure 8.5. Class diagram for HAVi 1.1 components .

The user interface model of java.awt is extended to support an optional remote control. A large number of events are optional, allowing manufacturers to customize and add value to their products. Implementations of KeyListeners in an execution environment should also expect to receive HRcEvent's (subclass of java.awt.event.KeyEvent ) and should deal with them appropriately. HAVi also adds classes to support graphics and video display functions that are available in typical television-based systems, including: support for nonsquare pixels, and graphics and video overlays.

8.8.1 Lightweight Interfaces

The HAVi framework consists of a base class, HVisible , and a set of interfaces that model the behaviors that different types of widgets may exhibit. The behavior is modeled on the number of states a widget may represent. For each such state a widget can present a particular representation (graphical, textual, and sound) to the user. The widget framework allows for simple user interface development by application authors. It also reduces the size of the developed application, because most of the presentation and interaction capability is resident on the device, so developers can concentrate on the specific functionality of their application.

8.8.2 Abstraction of Feel

To provide the necessary flexibility, the HAVi L2 GUI widget framework is defined around a core of abstract Component Behaviors. These effectively define the functionality and feel of each widget which is derived from one of the component behaviors. Behaviors are defined for widget types having a number of states, which may be used to mimic the behavior of typical widgets. In summary these component behaviors are as follows :

• HVisible : a simple, one-state Behavior providing basic display functionality.

• HNavigable : a two-state Behavior enabling widgets to receive navigational focus, and to define some kind of display change associated with focus change.

• HActionable : a three-state Behavior providing a third "actioned" state and allowing functionality to be invoked in response to that action.

• HSwitchable : a four-state Behavior allowing a widget to be actioned and to retain internal state information in addition to simple action behavior.

Additionally, the default LayoutManager for HContainer is defined to be null (i.e., absolute positioning) in contrast to the FlowLayout used in java.awt.Container .

8.8.2.1 HContainers

Components in the HAVi L2 GUI are explicitly allowed to overlap each other. Hence, the HAVi L2 GUI extensions adds additional Z-ordering related methods to org.havi.ui.HContainer. The HContainer class implements the HMatteLayer interface and provides Z-ordering capabilities, which are required since components in the HAVi L2 GUI are explicitly allowed to overlap each other. These Z-ordering capabilities ( addBefore() , addAfter() , pop() , popInFrontOf() , popToFront() , push() , pushBehind() , and pushToBack() ) is implemented by (implicitly) reordering the child components within the HContainer , so that the standard AWT convention that the Z-order is defined as the order in which components are added to a given container is maintained . For example, one implementation of popToFront() might be to make the specified component become the first Component added to the parent Container by removing all components from that container, adding the specified container first, and then adding the remaining components in their current relative order to that container.

HContainer also adds the ability to determine whether it is completely opaque , by applications overriding the isOpaque() method. Additional semantics related to transparency of the HContainer itself and its Components, are also defined via the HMatteLayer interface. Based on these fundamental abstract Behaviors, all necessary HAVi functionality can be provided through derived concrete widgets, either for the provision of HAVi specific user interfaces, or for HAVi specific widgets. In addition, these abstractions form the basis on which other interactive applications may be built without the requirement for the use of HAVi specific widgets. Thus, the HAVi widget framework is more generally applicable to interactive application execution, rather than exclusively focused on HAVi.

An HContainer may be rendered as follows:

• If the container is ungrouped , the container's background is first rendered and then composited with the container's matte (i.e., the RGBA value of the container's background is combined with the alpha value from the matte). Then, in back to front order, each member of the container is rendered, composited with its matte, and then composited with the container.

• If the container is grouped, the container's background is first rendered. Then, in back to front order, each member of the container is rendered, composited with its matte, and then composited with the container. The result is then composited with the container's matte.

After an HContainer is rendered, it is composited with its parent. Compositing of an HScene is determined by the configuration of display devices (see Section 8.10 for details).

8.8.2.2 HComponents

This is the base class for all HAVi widgets. The org.havi.ui.HComponent class extends java.awt.Component to include additional semantics related to transparency of the HComponent , defined via the HMatteLayer interface. The HComponent class also adds the ability

• to determine whether hardware double buffering is present, using the isDoubleBuffered() method, and

• to determine whether the component is completely opaque, by applications overriding the isOpaque() method.

8.8.3 Component Grouping

A container is either grouped or ungrouped. When a container is ungrouped, its matte only influences the appearance of those regions of the container not covered by members of the container (i.e., exposed regions of the container's background). When a container is grouped, its matte influences the appearance of its background and all members of the container. For example, grouping a container and setting its matte to indicate 50% transparency should fade the container's background and all members of the container. If it is ungrouped only the background should fade.

8.8.3.1 HVisible

The HVisible class is the base class for all non-interactive components. As in traditional AWT, the layout manager associated with the Container into which an HVisible component is placed controls the size and location of that component. Subclassing from HVisible provides:

• support for interaction states

• an association with a pluggable HLook class to which all drawing is delegated

• support for state-related content that is drawn by an associated HLook

• support for scalable and alignable content

• support for customizable look-and-feel data

• support for preferred sizes when used with a layout manager

• control over the background painting behavior

• support for a pluggable text layout management mechanism

Interaction State

Interaction states for HVisible components are defined in the HState interface. The two interaction states valid for a plain (un-subclassed) HVisible are NORMAL_STATE and DISABLED_STATE, whose interpretation follows their names . The getInteractionState() method is provided to allow any class to read the current state of a component. Subclasses of HVisible may define other states. However, setInteractionState() is the only means by which state can be changed and throw an IllegalArgumentException if the state is not valid for a particular component type. Subclasses of HVisible are not allowed to manipulate state in other ways.

State-based Content

Specific content may be set for any interaction state defined by HState . It is recommended that HLook implementations be capable of drawing components in styles that allow visualizing the interaction state under all situations.

Content for any component, which is typically stored by reference, may be changed "on the fly" using the setContent() methods. However, some components (e.g., HStaticAnimation and HAnimation ) may be asynchronously referencing their content (i.e., through a separate implementation-specific animation thread).

Background Painting

Typically, the HLook associated with an HVisible does not paint the background of the HVisible , allowing for non-rectangular components and text overlaying bitmaps. However, HVisible provides for components which require their background to be painted through the setBackgroundMode() method.

Repaint Hints

HLook provides a hint-based mechanism for repainting an HVisible . These hints specify the change that triggered the redrawing. The widgetChanged() method should be called whenever the HVisible requires a redraw to change its appearance. The widgetChanged() method requires an array of one or more HChangeData objects, which contain a hint and associated data. All keys are java.lang.Integer objects, with values defined as constants in this class.

Preferred Sizes

As in AWT, components have default sizes. The setDefaultSize() and getDefaultSize() methods provide support for user-defined defaults which are passed to a layout manager through the HLook.getPreferredSize() method. The area available to the HLook for rendering the component excludes that HLook 's borders. Therefore when a layout manager is in use the actual size of the component is likely to be larger than this default size.

Constructors of HVisible and subclasses that accept width and height parameters set the default size as if these parameters were passed to setDefaultSize() . If a layout manager is in use, the actual size of the component is probably larger than this size after layout due to the HLook adding borders. However, if no layout manager is used, the width and height parameters are simply used to set the actual size of the component.

Private HLook Data

Private data for the use of an associated HLook to optimize the redraw of the component may be set on any HVisible . This includes cached bitmap representations of complex drawing operations, scrolling metrics, and positions and cached layout data.

Data is set using the setLookData() method, and retrieved with the getLookData() method. To keep the on-screen representation of an HVisible synchronized with its state, any class may call setLookData() with a parameter of null to invalidate any cached data. Instances of HLook are able to regenerate any data they store on HVisible classes at any time. This mechanism is intended for implementation optimization only and is not used for storing content.

Event Handling

Implementations of HVisible may enable certain java.awt .AWTEvents , however, applications should assume that the HVisible class ignores those events. The HAVi specification strongly recommends that component implementors use the HAVi events defined in the org.havi.ui.event package where possible. For example, a component responding to user action should normally subclass HComponent , implement the HActionInputPreferred interface, and handle HActionEvent events in the processHActionEvent() method, instead of overriding java.awt.Component.processEvent() or similar.

8.8.3.2 HNavigable

This interface is implemented by classes that are derived from HVisible for adding an additional state that is used to indicate if the widget is currently focused. The HNavigable interface also provides the functionality necessary to manage the focus navigation between widgets assuming a remote control style UP, DOWN, LEFT, RIGHT form of navigation, using the setFocusTraversal() method. The precise semantics of the HNavigable interface are defined in the javadoc.

Event Behavior

Subclasses of HComponent that implement HNavigable respond to HFocusEvent events. Developers should assume that HFocusEvent are the only events generated in response to all possible input event. One or more HFocusListener listeners may be added to a component. The focusGained() and focusLost() methods of the HFocusListener are invoked whenever the HNavigable gains or loses focus. An HNavigable is typically implemented using focus traversal tables that allow a four-way focus behavior of a set of components to be set using setFocusTraversal() , setMove() , and getMove() .

Interaction States

The HNavigable interface supports the four states of NORMAL _STATE, FOCUSED_STATE, DISABLED_STATE, and DISABLED_FOCUSED_STATE. The enable/.disable events switch between NORMAL and DISABLED states, while the focus events switch between NORMAL and FOCUSED states.

Platform Classes

The list of HAVi platform classes implementing or inheriting the HNavigable interface is given in Table 8.4. These classes generate HFocusEvent events in addition to any other events specified in the respective class descriptions.

Table 8.4. HNavigable HAVi Platform Classes

HAnimation	HToggleButton
HIcon	HListGroup
HText	HSinglelineEntry
HRange	HMultilineEntry
HGraphicButton	HRangeValue
HTextButton

8.8.3.3 HActionable

The HActionable interface extends HNavigable by adding an additional state that is used to indicate when the widget has been actioned. The HActionable interface provides the functionality necessary to associate ActionListeners with the widget, using the addActionListener() and removeActionListener() methods. These ActionListeners should be called when the widget is actioned.

A widget that implements the HActionable interface is actioned when it receives a havi.ui.event.HUIEvent.VK_ACTION key event. The widget should move into its actioned state by presenting its actioned look. Any associated ActionListeners should be called by the widget calling its HActionable.processActionEvent () method. When the ActionListeners have returned, the widget should return to its focused state.

8.8.3.4 HSwitchable

The HSwitchable interface extends HActionable by adding an additional state that is used to maintain an internal (on or off) value. The state transitions for HSwitchable are depicted in Figure 8.6.

Figure 8.6. HSwitchable transitions.

8.8.4 Content Scaling and Alignment

Some of these looks may support the scaling and alignment of their content as an implementation option. The scaling and alignment modes supported are specified in the class description of HVisible . Table 8.5 details which features the content-based platform looks should support. Implementations should support both scaling and alignment of content through implementation of the methods listed in Table 8.6.

Table 8.5. HLook Scaling and Alignment Requirements

HLook	Scaling	Alignment
HAnimateLook	Optional	Mandatory
HGraphicLook	Optional	Mandatory
HListGroupLook	Optional	Mandatory
HTextLook	Not used	Mandatory
HSinglelineEntryLook	Not used	Not used
HMultilineEntryLook	Not used	Not used

Table 8.6. HLook Methods for Implementing Alignment and Scaling

Alignment	Scaling
setHorizontalAlignment()	setResizeMode(int resize)
setVerticalAlignment()	getResizeMode()
getHorizontalAlignment()
getVerticalAlignment()

Implementations minimally support the RESIZE_NONE scaling mode. Looks should use the getHorizontalAlignment() and getVerticalAlignment() methods to retrieve the current alignment modes, and the getResizeMode() method to determine the active scaling mode, where supported. However, that HAVi platform HLooks that render text content using the HDefaultTextLayoutManager class delegate the alignment of text content to the layout manager.

8.8.4.1 Rendering Hints

HLook provides a widgetChanged() method which can be called by an HVisible with one or more hints to inform the look that something has changed. This method provides information to the look about what has changed, which allows smarter repainting than having the HVisible simply call its repaint method. The hint constants are defined on HVisible .

8.8.4.2 Private Data

Implementations of HLook may store private data on each instance of an HVisible to optimize the drawing of that component. However, this is an implementation option. Furthermore such data may be invalidated by another part of the system, for example if setLook() is called on HVisible . Therefore, if this mechanism is used by implementations of HLook , those implementations are capable of regenerating such data on the fly, according to the current state of the HVisible .

8.8.4.3 Platform Looks

The HAVi L2 GUI provides a number of classes implementing the HLook interface. Applications wishing to provide their own HLook s may directly implement this interface or may subclass those provided by the platform.

8.8.4.4 Default Behavior

Implementations of HLook should use the following default behavior:

• The foreground color of each associated HVisible should be determined using java.awt.Component . getForeground() .

• The background fill color of each associated HVisible should be determined using java.awt.Component.getBackground ().

• The current alignment mode of each associated HVisible should be determined using getHorizontalAlignment() and getVerticalAlignment() .

• The current scaling mode of each associated HVisible should be determined using getResizeMode() .

8.8.5 Event Processing Interfaces

HEventMulticaster handles event dispatching for the following events (see Figure 8.7):

• HBackgroundImageEvent : This event informs an application that a loading operation for an HBackgroundImage has finished. HScreenConfigurationEvent is sent to all registered HScreenConfigurationListeners when an HScreenDevice modifies its configuration. HScreenLocationModifiedEvent is generated by the system when a component is moved on-screen, rather than within a container.

• HActionEvent : This event is used to interact with a component implementing the HActionInputPreferred interface as follows:

  • An HActionEvent event may be sent from the system to the component to cause the component to become actioned.

  • An HActionEvent event is sent from the component to all registered HActionListeners whenever the component is actioned.

• HFocusEvent : This event is used to interact with a component implementing the HNavigationInputPreferred interface as follows:

  • An HFocusEvent event may be sent from the system to the component to inform it that it has gained or lost the input focus, or that it should transfer focus to another component.

  • An HFocusEvent event is sent from the component to all registered HFocusListener whenever the component focus status changes. Because the underlying focus mechanism is based on AWT, focus transfer events do not guarantee that another component actually gets the focus or that the current component loses focus.

• HItemEvent : This event is used to interact with a component implementing the HSelectionInputPreferred interface as follows:

  • An HItemEvent event may be sent from the system to the component to change the state of the component, and the selection set held by the component.

  • An HItemEvent event is sent from the component to all registered HItemListeners when a change to the component state or selection set occurs. This supports selecting and clearing individual or all elements and managing the currently focused element.

• HTextEvent : This event is used to interact with a component implementing the HKeyboardInputPreferred interface as follows:

  • An HTextEvent event may be sent to the component to cause a change to the caret position as a result of user interaction. A platform that lacks suitable caret positioning may choose to generate this event using a virtual keyboard user interface.

  • An HTextEvent event is sent from the component to all registered HTextListeners when a change to the text content, caret position, or editable mode of the component occurs.

• HAdjustmentEvent : This event is used to interact with a component implementing the HAdjustmentValue interface as follows:

  • An HAdjustmentEvent event may be sent from the system to a component to cause a change to its editable mode as a result of user interaction. For example, this event may be generated by a virtual keyboard on a platform even when it lacks adjustment keys.

  • An HAdjustmentEvent event is sent from the component to all registered HAdjustmentListeners when a change to the value or editable mode of the component occurs.

• HKeyEvent : This mechanism is intended to mirror that used in the AWT and based on the java.awt.event.KeyEvent . The key codes are shown in Table 8.7. The intention of these events is to provide a means for HAVi widgets to receive events in a platform independent manner without impairing performance.

  The HKeyEvent event is used to interact with a component implementing the HKeyboardInputPreferred interface as follows:

  • An HKeyEvent event may be sent from the system to inform the component about key-input. The source of the input may be either a real or a virtual keyboard.

  • An HKeyEvent event is sent from the component to all registered HKeyListeners whenever the component received input.

Figure 8.7. Class diagram for HAVi 1.1 events.

Table 8.7. Event Codes

Keycode	Meaning
VK_ACTION	HActionable widget should perform action
VK_START_CHANGE	HValue widget should enter change mode
VK_END_CHANGE	HValue widget should end change mode
VK_NEXT_CHAR	Text entry widget should move caret forward
VK_PREV_CHAR	Text entry widget should move caret back
VK_NEXT_LINE	Multiline text entry widget should move caret down
VK_PREV_LINE	Multiline text entry widget should move caret up
VK_ADJUST_MORE	HValue widget should increase value
VK_ADJUST_LESS	HValue widget should decrease value

The HAVi implementation should only generate KEY_PRESSED events. Neither KEY_TYPED nor KEY_RELEASED events should be generated. Furthermore, the system should collapse combined events. For example, a usual JVM generates for the letter A three events: KEY_PRESSED for modifier key Shift, KEY_PRESSED for letter A, and KEY_TYPED for A. This should be collapsed into one single KEY_PRESSED event with the letter A and the Shift modifier set. This simplifies the key event handling of applications.

HEventGroup represents a group of key codes. Groups do not keep a count of the number of times a particular key code is added or removed. Repeatedly adding an event to a group has no effect. Removing an event removes it regardless of the number of times it has been added. Groups are resolved when they are passed into the methods of HScene . Adding or removing events from the group after those method calls does not affect the subscription to those events.

8.8.5.1 Listeners (callbacks)

HBackgroundImageListener is used for receiving events related to HBackgroundImage objects. HScreenConfigurationListener is used to monitor when the configuration of an HScreenDevice is modified. HScreenLocationModifiedListener is used to monitor when a component on-screen location is modified. The HActionListener interface enables the reception of HActionEvent events, as generated by objects implementing HActionable . HFocusListener enables the reception of HFocusEvent events, as generated by objects implementing HNavigable . HItemListener enables the reception of HItemEvents , as generated by objects implementing HItemValue . HTextListener enables the reception of HTextEvents , as generated by objects implementing HTextValue . HKeyListener enables the reception of HKeyEvent events. HAdjustmentListener enables the reception of HAdjustmentEvents , as generated by objects implementing HAdjustmentValue .