function onKeyEvent(key as String, press as Boolean) as Boolean
end function


The 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.

The 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:

backBackleft-pointing arrow at top of remote 
upUpup-pointing caret of remote directional pad 
downDowndown-pointing caret of remote directional pad 
leftLeftleft-pointing caret of remote directional pad 
rightRightright-pointing caret of remote directional pad 
OKOKkey usually labeled OK near or in the center of remote directional pad 
replayReplaykey usually labeled with a circular-pointing arrow 
playPlay/Stopkey usually labeled with a right-pointing triangle and two bars 
rewindRewindkey usually labeled with two left-pointing triangles 
fastforwardFast Forwardkey usually labeled with two right-pointing triangles 
optionsOptionskey 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.


The press parameter is a boolean value that is true if the key was pressed, and false if the key was released.

The 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  button is pressed, 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.

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.).


The following onKeyEvent() example handles supported remote control key presses other than the Back key by displaying a warning message until the OK key is pressed.

onKeyEvent() Event Handling Example
function onKeyEvent(key as String, press as Boolean) as Boolean
  handled = false 
  if press then
    if (key = "back") then
      handled = false
      if (m.warninglabel.visible = false)
        if (key = "OK") then
        end if
      end if
      handled = true
    end if
  end if
  return handled
end function


See Events and Observers Markup for more details and a downloadable sample showing how to add key event support to a channel.