Skip to main content

Handling Remote Control

Hosanna routes input through platform adapters into a shared input model. TV remotes, browser keyboard events, mouse movement, touch gestures, debug controls, and Roku-emulation commands can all feed the same focus and selection system.

Input Flow​

platform event -> input adapter -> InputAdapterManager -> FocusManager.handleInputEvent(event) -> focused view

For key input, InputAdapterManager forwards normalized HsInputEvent objects to FocusManager.handleInputEvent. Focusable views receive onInputEvent, and directional keys can trigger focus resolution through findNextFocusable and nextFocusMap.

Remote Keys​

Hosanna normalizes the common TV navigation keys:

  • Arrows move focus.
  • OK or Enter selects focused content.
  • Back navigates back or dismisses UI.
  • Options and long press are available where a control or row supports them.

Use onInputEvent when a focusable view needs custom behavior:

import { Key } from 'hosanna-ui/hosanna-bridge-lib/api';
import { KeyState, type HsInputEvent } from 'hosanna-ui/hosanna-bridge-lib/IFocusManager';

Button({
  text: 'Close',
  styleKey: 'controls.Button.secondary',
}).onInputEvent((event: HsInputEvent) => {
  if (event.key === Key.Back && event.keyState === KeyState.Press) {
    this.closePanel();
    event.preventDefault = true;
    event.consumed = true;
  }
});

Set preventDefault when the handler should stop default focus or bubbling behavior.

Web Input Adapters​

Web adapter registration can be filtered with ?adapters=:

?adapters=keyboard,mouse,touch
?adapters=roku,touch
?adapters=webkeyboard

Supported adapter names:

  • keyboard: maps browser keyboard events to Roku-style remote input.
  • webkeyboard: enables browser keyboard input events for text-focused paths.
  • debug: debug hover and highlight input.
  • mouse: hover, click, and wheel input.
  • touch: touch pointer input.
  • roku: Roku emulation profile.

Mouse and touch input are converted into Hosanna design coordinates before hit testing. CollectionView uses this for hover focus, click selection, wheel scrolling, touch drag, and momentum. ScrollView uses it for wheel and touch-drag scrolling.

Touch Remote​

Use ?touch=true on web to show the touch remote overlay. It provides d-pad, OK, and Back controls for mobile testing and sends the same normalized key events as a remote.

See Web Expression, DPI, and Touch Input for launch parameters, DPI, and touch details.

Remote Debugging​

The remote debug tools can inspect focus state, send keys, inspect views, and capture handler traces. Use them when debugging navigation, focus restoration, CollectionView row behavior, or native/device-only input issues.