8.6 User Interface Model

The user interface model consists of an input model and a display model. The input model includes remote control support and other user inputs. The display model supports graphics and video display functions that are available in typical television-based systems, including support for nonsquare pixels, and graphics plus video overlays.

8.6.1 Input Model

Applications can accept input from a remote control, a keyboard, or a pointing device. Remote control input is provided with classes in the org.havi.ui.event package. The keyboard and pointer device inputs are supported by functions in the java.awt and java.awt.event packages. The org.havi.ui and org.havi.ui.event packages include classes that allow the application to determine the user input capabilities of the platform on which the application is running. A large number of events are optional, allowing manufacturers to customize and add value to their products.

8.6.2 Remote Control Support

The remote control classes are extended from the java.awt.event key event classes. All of the events that are added for the remote control are optional. The remote control keys fall into two categories: colored keys and dedicated keys. The intention of these keys is to provide the user with direct access to various functions; however, the platform may implement a virtual (on-screen) mechanism to generate these events, but should take care in this case not to hide the application. Remote control key events are repeated.

8.6.3 Colored Keys

Up to six colored soft keys can be included on a remote control. These are optional, and are to be identified with a color . If implemented, these keys are to be oriented from left to right, or from top to bottom in ascending order. The application can determine how many colored keys are implemented, and what colors are to be used, so that the application can match the controls.

8.6.4 Dedicated Keys

The org.havi.ui.HRcEvent class defines a number of dedicated remote control events that can be used by applications. Although none of the events are required to be implemented, events for power, volume up and down, and channel up and down are highly recommended.

Although the dedicated remote control events are themselves device independent, the precise set of dedicated keys that is implemented is device dependent. Applications can discover which events are implemented and how these are to be labeled to match the platform implementation.

8.6.5 Keyboard

Applications can determine which keyboard events are supported and access those supported events via the java.awt.event package. Systems that do not include a physical keyboard can enable user input of alphanumeric key events, for example, via a "soft" on-screen keyboard.

8.6.6 Pointing Device

Support for pointing devices (e.g., pointing device or trackball ) is optional and it can be detected . Access to most events is provided via the java.awt.event package. Applications should be written in such a way that a free roaming cursor is not required for correct operation. Programs that do require the use of a pointing device need to determine whether most capabilities are present before execution. In the event that a required pointing device capability is not found, notify the user which capability is required but seems missing to enable proper use.

8.6.7 Determining Input Capabilities

Three classes are available in the org.havi.ui.event package to determine the capabilities of the user input for a given platform: HKeyCapabilities , HMouseCapabilities , and HRcCapabilities . Each of these classes includes a method called getInputDeviceSupported() , which returns true if the particular device is known to be available.

The org.havi.ui.event.HRcCapabilities class includes a method called getRepresentation() , which returns an object of type org.havi.ui.event.HEventRepresentation . This class defines an event as having a known representation as a string, color, or symbol, or having no supported representation. The particular text, color, or symbol can be determined by calling getString() , getColor() , or getSymbol() , respectively. This allows an application to describe a button on an input device correctly for a given platform. All available events should have a text representation from getString() .

The six colored key events, VK_COLORED_KEY_1 , ... , VK_COLORED_KEY_6 , if implemented, are associated with a color via the getColor() method that returns a java.awt.Color object. Because the java.awt.Color object does not support alpha blending, an RGBA color object was introduced in JavaTV that is used by HAVi.

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. Application rendering of keys without a symbolic representation, but with a commonly known representation, should follow the guidelines as defined in the javadoc definition of the class.

8.6.8 Java Widgets

The user interface components supplied with early versions of Java (that are still present in the java.awt package in JDK 1.1) are normally implemented using native methods to provide a platform specific look and feel. These components are implemented using native code.

Heavyweight components couple each component class with a peer that provide the interface between the abstract Java component class and the native code. The disadvantages of these existing components are that they take twice as many classes to implement and that they are not able to create transparent, non-rectangular shapes .

Lightweight components, on the other hand, have no direct peer and they are required to implement their own look and feel using Java code. Each lightweight widget is created by subclassing the java.awt.Component class. Because lightweight components lack an associated peer class, they handle their own presentation using the paint() method.

The application developer has two choices: use the resident widgets or extend the java.awt.Component and java.awt.Container classes to provide a fully customized look and feel. The first approach provides some flexibility while retaining a compact application size. The latter approach allows the greatest flexibility, but with extra complexity in the application.

As a result, only a subset of the standard JDK1.1 java.awt package is required to be present on a HAVi platform. The required subset of java.awt includes all of the classes needed to support the lightweight user interface framework. HAVi applications that rely on the presence of the complete JDK 1.1 java.awt package cannot be considered interoperable with all HAVi implementations .

The java.awt package is not considered TV friendly. Therefore, these classes are not required to be present in systems supporting the HAVi L2 GUI framework. TV friendly equivalents of these are provided through the HAVi L2 GUI API, which can be extended to support alternative look and feel. Applications wishing to be interoperable with all devices supporting the HAVi L2 GUI should not make use of java.awt classes, because they may not be supported by all devices supporting the HAVi L2 GUI. HAVi L2 GUI does not prevent a manufacturer implementing a particular device using java.awt .

The design of the HAVi L2 GUI packages was guided by the following observations:

The main base classes, java.awt.Component and java.awt.Container are required to build the lightweight components.
Other classes, such as java.awt.Font , are required for all general drawing and painting.
The layout classes, such as java.awt.FlowLayout and java.awt.BorderLayout are retained to provide flexible layout of components on various output devices.

Table 8.2 presents the list of java.awt classes available to interoperable HAVi applications, where '*' denotes interfaces. The classes in Table 8.2 are not necessarily sufficient to enable a full implementation of a HAVi compliant device. For example a device compliant with the HAVi L2 GUI could be implemented using JDK 1.1 which might present additional requirements on the implementation beyond the requirements presented by HAVi L2 GUI.

Table 8.2. List of java.awt Classes Available to Interoperable HAVi Applications

java.awt	java.awt.event	java.awt.image
`Adjustable*`	`ActionListener*`	`ImageConsumer*`
`ItemSelectable*`	`AdjustmentListener*`	`ImageObserver*`
`LayoutManager*`	`ComponentListener*`	`ImageProducer*`
`LayoutManager2*`	`ContainerListener*`	`ColorModel`
`LightweightPeer*`	`FocusListener*`	`DirectColorModel`
`AWTError`	`ItemListener*`	`IndexColorModel`
`AWTEvent`	`KeyListener*`	`MemoryImageSource`
`AWTEventMulticaster`	`MouseListener*`	`PixelGrabber`
`AWTException`	`MouseMotionListener*`
`BorderLayout`	`TextListener*`
`CardLayout`	`WindowListener*`
`Color`	`ActionEvent`
`Component`	`AdjustmentEvent`
`Container`	`ComponentAdapter`
`Cursor`	`ContainerEvent`
`Dimension`	`FocusAdapter`
`Event`	`FocusEvent`
`EventQueue`	`InputEvent`
`FlowLayout`	`ItemEvent`
`Font`	`KeyAdapter`
`FontMetrics`	`KeyEvent`
`Graphics`	`MouseAdapter`
`GridLayout`	`MouseEvent`
`IllegalComponentStateException`	`MouseMotionAdapter`
`Image`	`PaintEvent`
`Insets`	`TextEvent`
`MediaTracker`	`WindowAdapter`
`Panel`	`WindowEvent`
`Point`	`ComponentEvent`
`Polygon`
`Rectangle`
`Shape`
`Toolkit`

8.6.9 Relationship to PersonalJava API

PersonalJava 1.1 includes interfaces that are not found in JDK 1.1 but are useful for a TV friendly API. To provide the functionality offered by these interfaces without requiring PersonalJava, the HAVi L2 GUI includes the synonymous HAVi interfaces listed in Table 8.3.

Table 8.3. Mapping between Related HAVi and PersonalJava Interfaces

HAVi interface	PersonalJava AWT Interface
`org.havi.ui.HnoInputPreferred`	`com.sun.awt.NoInputPreferred`
`org.havi.ui.HkeyboardInputPreferred`	`com.sun.awt.KeyboardInputPreferred`
`org.havi.ui.HactionInputPreferred`	`com.sun.awt.ActionInputPreferred`

These interfaces imply the same meaning as their corresponding PersonalJava interfaces and remove any implicit implementation requirements. The HAVi L2 GUI specification is intentionally silent on the mechanisms used to implement the Java environment for a HAVi implementation. An extra HAVi specific interface org.havi.ui.HAdjustmentInputPreferred is also included. The org.havi.ui.HNoInputPreferred interface disallows user navigation.

A component implementing HNoInputPreferred indicates that the user may not navigate to this component. However, if a component implementing this interface is extended, so that the subclassed component implements another input preferred interface, then in all cases, this other interface should take precedence. In contrast, the method isFocusTraversable() should always return true for components implementing the interfaces org.havi.ui.HKeyboardInputPreferred , org.havi.ui.HActionInputPreferred , and org.havi.ui.HAdjustmentInputPreferred . The org.havi.ui.HKeyboardInputPreferred interface indicates that it is intended to accept alphanumeric input from the user. Platforms without keyboards should provide another means for generating such alphanumeric input when this component is edited, for example, by offering an on-screen virtual keyboard. The org.havi.ui.HActionInputPreferred interface indicates that it is intended to be auctioned by the user. The org.havi .ui.HAdjustmentInputPreferred interface indicates that it is intended to offer increment and decrement functionality to the user.