8.11 Pluggable Look

The HAVi L2 GUI framework provides pluggable look , also known as pluggable skin , using the HLook interface. Intuitively, the HLook interface may be regarded as a mechanism to allow a pluggable paint method to be automatically attached to the component. Pluggable looks allow implementers to extend the set of looks available to their application. Instead of having to subclass the entire component to change its look, it is possible to simply implement an HLook class and then associate this HLook implementation with the component. The following pre-defined looks are provided:

• HAnimateLook : Presentation of an animated image sequence.

• HGraphicLook : Presentation of graphical content.

• HRangeLook : Presentation of a value within a range.

• HTextLook : A simple presentation mechanism for textual content.

• HSinglelineEntryLook : Single line of textual content that can be edited by the user .

• HMultilineEntryLook : Multiple lines of textual content that can be edited by the user.

This basic set allows the construction of most typical interactive user interfaces when used in conjunction with the component behaviors to define a widget set. It can however be extended in a general fashion to provide new categories of look .

8.11.1 Borders

An implementation of HLook also includes code to draw implementation-specific borders. The application or component can query the reserved space for an HLook with the getInsets() method.

The border area is included in the overall size of the component. Therefore, the border effectively constrains the area available for rendering content to the rectangle that has an upper-left corner location of (insets.left, insets.top), and has a size of width “ (insets.left + insets.right) by height “ (insets.top + insets .bottom).

8.11.2 Invocation of showLook

The showLook() method of the HLook interface is called by the havi.ui framework in response to the paint method of the HVisible being called by the AWT lightweight component framework. Applications should simply invoke the component repaint method as in normal AWT, rather than calling the showLook() method directly. The showLook() method is invoked under the following conditions:

• If the class implements one of the following interfaces, the showLook() method is invoked when the trigger events specified in Table 8.9 are processed .

• If the implementing class is an HVisible , then the showLook() method is invoked when content is set on that HVisible .

Table 8.9. Interfaces and Their Triggering Events

Interface	Trigger Events
HNavigable	HFocusEvent
HActionable	HFocusEvent , HActionEvent
HSwitchable	HFocusEvent , HActionEvent
HAdjustmentValue	HFocusEvent , HAdjustmentEvent
HItemValue	HFocusEvent , HItemEvent
HTextValue	HFocusEvent , HTextEvent

8.11.3 Text Look

The HTextLook class is used by any HVisible component to display static text content (see Figure 8.11). This is the default look that is used by HListElement , HStaticText , and their subclasses. The HTextLook class draws the content set on an HVisible and therefore its rendering id platform dependent. It uses the getTextContent(int state) method with the current state of the HVisible to determine the content to render. In addition to the basic class behavior defined by the HLook interface the HTextLook associated with a given HVisible should use HVisible.getTextLayoutManager() to determine the HTextLayoutManager to perform the rendering. If the returned object is null, then the text should not be rendered.

Figure 8.11. Example of a HAVi SDK menu ( courtesy of Sharp Laboratories of America, Inc.).

All rendering of content is deferred to the associated HTextLayoutManager . Therefore, implementations of HTextLook need not use the alignment mode methods on HVisible .

8.11.4 Animate Look

The HAnimateLook class is used by any HVisible component to display animated graphical content (see Figure 8.12). It is the default look that is used by HStaticAnimation and its subclasses. It draws the content set on an HVisible . It uses the getAnimateContent(int state) method with the current state of the HVisible to determine the content to render. Additionally the content-based behavior of the HAnimateLook class is defined as follows :

• If there is only one image referenced in the sequence, then that image is rendered statically in a similar manner to HGraphicLook .

• If there is more than one image referenced in the sequence, then these are rendered in sequence, giving the effect of an animation.

• If a referenced image is inaccessible, then it is skipped .

Figure 8.12. Example of Animate Look (Sharp Laboratories of America, Inc.).

The HAnimateLook is not required to present consecutive images (Figure 8.13) in the animation with the delay specified in its associated HStaticAnimation . For example, if the time taken to retrieve or render an image is longer than the delay, then it is rendered as soon as possible. Implementations of HAnimateLook should use the appropriate methods on HVisible to determine which scaling and alignment modes to use when rendering content.

Figure 8.13. Example image sequence (courtesy of Sharp Laboratories of America, Inc.).

Alignment can be controlled using the VALIGN_JUSTIFY and HALIGN_JUSTIFY alignment modes. The results of applying those for animated graphical content are defined to identical to VALIGN_CENTER and HALIGN_CENTER modes, respectively, as justification is meaningless in this context.

8.11.5 Graphic Look

The HGraphicLook class is used by any HVisible component to display static graphical content, and used as default look for HStaticIcon and its subclasses. It draws the content set on an HVisible , and therefore its rendering is platform dependent. It uses the getGraphicContent () method with the current state of the HVisible to determine the content to render.

Implementations of HGraphicLook should use the appropriate methods on HVisible to determine which scaling and alignment modes to use when rendering content. HGraphicLook may support scalable graphical content. As a minimum, all implementations support the RESIZE_NONE scaling mode, and all alignment modes.

The results of applying the VALIGN_JUSTIFY and HALIGN_JUSTIFY alignment modes for graphical content are defined to identical to VALIGN_CENTER and HALIGN_CENTER modes respectively, as justification is meaningless in this context.

8.11.6 Range Look

The HRangeLook class is used to display a slider or scroll bar type range control onscreen (see Figure 8.14). It is used by specific HVisible components which implement the HAdjustmentValue interface to present a graphical representation of the value to the user. This is the default look that is used by HStaticRange and its subclasses. This look is provided by the platform and the exact way in which it is rendered is platform dependent. This look does not use content set on the HVisible .

Figure 8.14. Example of HRangeLook (Sharp Laboratories of America Inc.).

8.11.7 Single-line Entry

The HSinglelineEntryLook class is used by the HSinglelineEntry component to display the entering of text. It draws the content set on an HSinglelineEntry and therefore its rendering is platform dependent. The getTextContent(int state) method is used to determine the content to render. This is the default look that is used by HSinglelineEntry and its subclasses. The interaction state of the HSinglelineEntry is ignored.

8.11.8 Multi-line Entry

The HMultilineEntryLook class is used by the HMultilineEntry component to display the entering of text (see Figure 8.15). It is the default look that is used by HMultilineEntry and its subclasses. It uses the getTextContent(int state) method to determine the content to render. The interaction state of the HMultilineEntry is ignored.

Figure 8.15. Example of HMultilineEntryLook (Sharp Laboratories of America Inc.).

8.11.9 ListGroup Look

The HListGroup is a user interface component representing a list of selectable items ( HListElements ) which contain static read-only graphical or textual content. By default this component uses the HListGroupLook class to render itself. This component can be navigated to, namely it can have the input focus. It also responds to HItemEvent events as follows:

• When the component has focus, sending an ITEM_START_CHANGE event to the component causes it to enter selection mode.

• When the component has focus, sending an ITEM_END_CHANGE event to the component causes it to leave selection mode.

• When the component has focus and is in selection mode, the current item can be set by sending ITEM_SET_CURRENT, ITEM_SET_PREVIOUS, and ITEM_SET_NEXT events to the component.

• When the component has focus and is in selection mode, sending an ITEM_TOGGLE_SELECTED event causes the current item to be toggled between a selected and unselected state.

HListGroup responds to a SCROLL_PAGE_MORE or SCROLL_PAGE_LESS HItemEvent by adjusting the scroll position with the value returned by HListGroupLook.getNumVisible(HVisible visible) , or an implementation-specific value if no look has been set on this widget. Sending an ITEM_SELECTION_CLEARED event to the component causes the current selection set to be cleared irrespective of focus and selection mode.

HListGroup has the following properties that differentiate it from the other platform components:

• It uses the HTextLayoutManager to render text from the elements. It is not required to respect the default horizontal and vertical content alignments specified by HVisible . Programmers should make calls to setHorizontalAlignment() and setVerticalAlignment() to enforce the alignments required.

• The resize mode as defined by HVisible determines how the icons are scaled.

• Focus traversal applies to the entire list component. The elements in the list are not components in their own right and never receive focus. The concept of the current element is handled through HItemEvent events.

• For the purpose of layout management of the HListGroup component, the following constraints are applied:

• The minimum size is the size to present one element or an implementation specific minimum (e.g., 32 x 32) if no elements are present.

• The preferred size is that set by setDefaultSize() rounded down to the nearest element (minimum of one) or the size required to present 5 elements if a default size is not set.

• The maximum size is that required to present all elements.

Figure 8.16. Example of toggle buttons (courtesy of Sharp Laboratories of America, Inc.).

Interoperable HAVi applications do not add HListElements more than once. If an application requires items with identical contents (label or icon), then additional items are created. The behavior of the HListGroup if duplicates are added is implementation specific.

8.11.10 Event Handling

Although implementations of HVisible may enable certain java.awt.AWTEvents , applications should assume that an HVisible class does not generate or respond to any java.awt.AWTEvents . If this behavior is required, the standard AWT mechanisms (i.e., processEvent() and similar functions) may be used to handle events on HVisible or subclasses. However, component implementors should use the HAVi events defined in the org.havi.ui .event package.

For example, a component wishing to respond 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.