Keyset class
Keyset objects permits HbbTV applications to define which key events they request to receive. Keys they do not choose to receive will be left to the device to handle. This means an application does not override the functionality of keys unless it has an explicit reason to do so.
The Keyset object is a property of the [ApplicationPrivateDate](/references/application-management-apis/the-applicationprivatedata-class) object.
When an HbbTV application becomes activated, it does not automatically have any access to key events, the application needs to call Keyset.setValue() in order to receive key events.
HbbTV Applications should not rely on receiving any key events not requested through the Keyset object, for example when the end user is inputting text into an input field. However, the set of key events requested via a Keyset object only identifies the minimum set of keys that may be sent to an application, and so applications should not rely on receiving only those key events.
The key events that can be generated by a device for an HbbTV application are:
| Button (for conventional remote controls) | Key event | Availability |
|---|---|---|
| Four colour buttons (red, green, yellow, blue) | VK_RED, VK_GREEN, VK_YELLOW, VK_BLUE | Always available to applications |
| Four arrow buttons (up, down, left, right) | VK_UP, VK_DOWN, VK_LEFT, VK_RIGHT | Always available to applications |
| ENTER or OK button | VK_ENTER | Always available to applications |
| BACK button | VK_BACK | Always available to applications |
| Number keys | VK_0 to VK_9 inclusive | Only available to applications once |
| activated | ||
| Play, stop, pause | VK_STOP and either VK_PLAY and VK_PAUSE or VK_PLAY_PAUSE | Only available to applications once |
| activated (some exception exist) | ||
| Fast forward and fast rewind | VK_FAST_FWD VK_REWIND | Only available to applications once |
| activated (some exception exist) | ||
| Record | VK_RECORD | Only support if PVR feature supported |
| Only available to applications once | ||
| activated. |
Constants
Common key events are represented as constants defined for the object. These can be combined in a bit-wise mask to identify a set of key events. Less common keys (i.e. VK_RECORD) are not included in one of the defined constants and are controlled through an extended ‘other’ mechanism.
| Constant name | Numeric Value | Use |
| RED | 0x001 | Used to identify the VK_RED key event. |
| GREEN | 0x002 | Used to identify the VK_GREEN key event. |
| YELLOW | 0x004 | Used to identify the VK_YELLOW key event. |
| BLUE | 0x008 | Used to identify the VK_BLUE key event. |
| NAVIGATION | 0x010 | Used to identify the VK_UP, VK_DOWN, VK_LEFT, VK_RIGHT, VK_ENTER and VK_BACK key events. |
| VCR | 0x020 | Used to identify the VK_PLAY, VK_PAUSE, VK_STOP, VK_NEXT, VK_PREV, VK_FAST_FWD, VK_REWIND, VK_PLAY_PAUSE key events. |
| SCROLL | 0x040 | Used to identify the VK_PAGE_UP and VK_PAGE_DOWN key events. |
| INFO | 0x080 | Used to identify the VK_INFO key event. |
| NUMERIC | 0x100 | Used to identify the number events, 0 to 9. |
| ALPHA | 0x200 | Used to identify all alphabetic events. |
| OTHER | 0x400 | Used to indicate key events not included in one of the other constants in this class. |
Properties
readonly Integer value |
| The value of the keyset which an HbbtTV application will receive. |
readonly Integer otherKeys[] |
This is only used on devices that support the VK_RECORD key event (i.e. PVR devices). This is used in combination with maximumOtherKeys to enable an HbbTV application to request the VK_RECORD key.If the OTHER bit in the value property is set then this indicates those key events which are available to the application which are not included in one of the constants defined in this class, If the OTHER bit in the value property is not set then this property is meaningless. |
readonly Integer maximumValue |
In combination with maximumOtherKeys, this indicates the maximum set of key events which are available to an application. When a bit in this maximumValue has value 0, the corresponding key events are never available to the application. |
readonly Integer maximumOtherKeys[] |
This is only used on devices that support the VK_RECORD key event (i.e. PVR devices). This is used in combination with otherKeys to enable an HbbTV application to request the VK_RECORD key.If the OTHER bit in the maximumValue property is set then, in combination with maximumValue, this indicates the maximum set of key events which are available to an application. For key events which are not included in one of the constants defined in this class (e.g. VK_RECORD), if they are not listed in this array then they are never available to the browser. If the OTHER bit in the value property is not set then this property is meaningless. |
Boolean supportsPointer |
| HbbTV applications that have been designed to handle Mouse Events can express it by using this property. Applications should set this property to true to indicate that they support a pointer based interaction model, i.e. that they listen to and handle Mouse Events. They should set it to false otherwise. If not set, a HbbTV device will assume that the application does not support a pointer based interaction model. Based on the value of this property, a HbbTV device may decide to enable or disable the rendering of a free moving cursor. Note: HbbTV devices are not required to support a pointer based input device even though they are recommended to do so. If pointer based input devices are supported, this is expressed via the +POINTER UI Profile fragment returned by the application/oipfCapabilities embedded object. |
Methods
Integer setValue(Integer value, Integer otherKeys[]) | |
| Sets the value of the keyset which an HbbTV application requests to receive. Arguments | |
value | The value is a number which is a bit-wise mask of the constants defined in this class. For example:const myKeyset = myApplication.privateData.keyset; |
otherkeys | This parameter is optional. If the value parameter has the OTHER bit set then it is used to indicate the key events that the application wishes to receive which are not represented by constants defined in this class. |
String getKeyIcon(Integer code) | |
| Return the URI of the icon representing the physical key or other mechanism that is used by the terminal to generate the key event for the given keycode passed. It SHALL return null if the key has no icon associated with it. The icons returned by the are 32 x 32 pixels. Arguments | |
code | The VK_ constant for the key whose icon should be returned. |