Skip to main content

Focus Management

Introduction​

Focus management is a critical aspect of the Maestro Web SDK, especially for BBD (Browser Based Devices) applications that need to support keyboard and remote navigation. The SDK provides mechanisms for managing focus between your application and the SDK's UI components, ensuring a seamless navigation experience.

Focus Architecture​

The Maestro Web SDK uses the Norigin Spatial Navigation library for managing focus within its UI components. This library provides a grid-based navigation system that works well for TV-like interfaces where users navigate with directional (up/down/left/right) controls.

┌─────────────────────┐                  ┌─────────────────────┐
│                     │                  │                     │
│   Parent App UI     │◄──Focus Transfer─►   Maestro SDK UI    │
│                     │                  │                     │
└─────────────────────┘                  └─────────────────────┘
      Your Controls                          Panel Controls

Focus Transfer Interface​

// In IMaestroEventDelegate (implemented by parent app)
interface IMaestroEventDelegate {
  // Called when focus should return to parent app
  startFocusManagement(): Promise<void>;
  // ... other methods ...
}

// In IMaestroEvent (implemented by SDK)
interface IMaestroEvent {
  // Called when focus should transfer to SDK UI
  startFocusManagement(): Promise<void>;
  // ... other methods ...
}

Table of Contents​

Key Concepts​

  • Focus Transfer:
    Focus transfer occurs when navigation moves from your application's UI to the SDK's UI (and vice versa). This transfer needs to be handled explicitly to ensure a smooth user experience.

  • Focus Entry Points:
    When focus enters the SDK UI, it typically starts at the first focusable element in the panel. The SDK uses predefined focus IDs for key elements to ensure consistent focus behavior.

  • Directional Navigation:
    The SDK uses directional navigation (up/down/left/right) rather than tab-based navigation, which is more appropriate for TV-like interfaces controlled by remotes or game controllers.

  • Autonomous Focus Regions:
    The SDK UI operates as an autonomous focus region, handling internal focus navigation independently from your application. When focus leaves this region, control is handed back to your application.

Implementation Examples​

Here's a simplified example of how focus transfer is typically implemented:

// In your parent application
class MyEventDelegate implements IMaestroEventDelegate {
  startFocusManagement(): Promise<void> {
    // When focus returns from SDK to your app,
    // focus an appropriate element
    const appControl = document.getElementById('app-control');
    if (appControl) {
      appControl.focus();
    }
    return Promise.resolve();
  }
  
  // ... other methods ...
}

// When navigating from your app to the SDK
function navigateToPanel() {
  // Get the event view model
  const eventViewModel = SDK.getMaestroEventViewModel();
  
  // Blur the currently focused element in your app
  (document.activeElement as HTMLElement)?.blur();
  
  // Start focus management in the SDK
  eventViewModel.startFocusManagement();
}
Last updated on