function onKeyEvent(key as String, press as Boolean) as Boolean
onKeyEvent() function receives remote control key events from the firmware, and allows you to write event handlers for a node or component in response to the events. The function returns a message to the firmware to indicate that a particular event has been handled by the node or component, preventing the event from moving up the focus chain, to possibly be handled by parent nodes in the SceneGraph node tree, or by default firmware handlers.
Several node classes handle certain remote control key events automatically, so the
onKeyEvent() function is not required to handle those events, and should not be used for those events in those nodes. As an example of node classes that automatically handle certain remote control key events, grid node classes such as PosterGrid automatically handle Up, Down, Right, and Left key presses when the poster grid has focus. Typically, you should use the ifSGNodeField
observeField() method to handle changes in the subject node fields caused by automatic key event handling of the node.
Key event handling is easy to set up in XML by including an
onKeyEvent() function in the <script> element. When the XML component or its children have the key focus, the
onKeyEvent() function will be called whenever an unhandled key event bubbles up the focus chain to the XML component.
key parameter contains a string, which is case-sensitive, that identifies which button was pressed. The
key strings supported by the
onKeyEvent() function, and the corresponding remote key, are as follows:
|back||Back||left-pointing arrow at top of remote|
|up||Up||up-pointing caret of remote directional pad|
|down||Down||down-pointing caret of remote directional pad|
|left||Left||left-pointing caret of remote directional pad|
|right||Right||right-pointing caret of remote directional pad|
|OK||OK||key usually labeled OK near or in the center of remote directional pad|
|replay||Replay||key usually labeled with a circular-pointing arrow|
|play||Play/Stop||key usually labeled with a right-pointing triangle and two bars|
|rewind||Rewind||key usually labeled with two left-pointing triangles|
|fastforward||Fast Forward||key usually labeled with two right-pointing triangles|
|options||Options||key labeled with an asterisk|
There are one or more keys on any Roku remote control which are not handled by the
onKeyEvent() function (or any Roku application event handler), such as the Home key. Presses of these keys are handled by the global Roku firmware event handler in a default manner that cannot be modified by application code.
press parameter is a boolean value that is true if the key was pressed, and false if the key was released.
onKeyEvent() function must return
true if the XML component handled the event, or
false if it did not handle the event. Returning
false allows the event to continue bubbling up the focus chain so that ancestors of the XML component can handle the event.
The behavior of the Roku Options overlay has been modified, such that the Options overlay now slides in whenever the Video node is in focus, and the app does not have its OnKeyEvent() handler fired. When the Video node is not in focus, the Options overlay does not slide in and the OnKeyEvent() handler is fired.button is pressed, the
Starting from firmware version 8.1, literal key keypress events (such as keyboard letters, and so forth) that are sent to the channels via the mobile app or ECP keydown/keyup commands, now go to the onKeyEvent() handler. Previously, only keys that corresponded to remote keys went to the onKeyEvent handler.
Such keys are now sent at "Lit_" followed by the actual keypress ("A," "B," "C," etc.).
onKeyEvent() example handles supported remote control key presses other than the Back key by displaying a warning message until the OK key is pressed.
See Events and Observers Markup for more details and a downloadable sample showing how to add key event support to a channel.