Working with Input Handlers

  • Article

For a Windows Media Center page to process input from the remote in a meaningful way, certain elements on the page must be able to receive the focus. The focus enables the user to target elements on the page one at a time for selection (by pressing the OK button on the remote), for text input, for scrolling, or for other interactions available from the remote. The page must always provide a distinct visual highlight to indicate which item has the focus. The focus must always be on exactly one element at a time, and it must move in a logical way from one focusable item to the next when the user presses the Up, Down, Left, or Right arrow buttons.

Managing the focus involves the following main tasks:

  • Keeping track of where the focus is at all times.
  • Moving the focus correctly and logically in response to user input.
  • Highlighting the focus so the user can tell where it is.

MCML can handle different types of user input (mouse, keyboard, and remote control). In simple cases, you can use rules to respond to input. Or, you can use input handlers to respond to different types of user input, and you can configure multiple handlers in a UI. For example, the UI can respond to both mouse input and remote control input.

You can specify which types of user input to allow with the Input element. For example, you can allow double-clicks and disallow mouse focus for a particular UI. You can set these properties by using default rules in the Rules section of a UI:

<Default Target="[Input.KeyInteractive]" Value="true" />

In general, if you use input handlers rather than rules, you won't need to use or set properties such as MouseInteractive or KeyInteractive because the input handlers set these properties for you.

If you want any part of the UI to be mouse interactive, you must set the MouseInteractive property to true for each of those view items. By default, mouse interactivity is enabled for the root view item in a UI when a mouse-based input handler is configured or key interactivity is enabled. You can also set individual view items to be mouse interactive, but then the root view item is not automatically configured. In addition, mouse interactivity is not inherited. You can disable mouse interactivity within a UI by setting Input.Enabled to false.

Key interactivity always references the root view item for operations such as directional navigation. Use the NavigateInto method on a view item to send focus to it or one of its children.

You can use simple rules to implement a check for mouse and keyboard focus, or you can use the following handlers, which are placed in the Locals section of a UI. Then configure rules to respond to the input handler properties.

  • ClickHandler: Handles button input from the primary mouse button and the SPACEBAR and ENTER keys.
  • KeyHandler: Handles keyboard input.
  • MouseWheelHandler: Handles input from the movement of the mouse wheel.
  • ScrollingHandler: Handles input that is associated with scrolling, such as directional keys.
  • ShortcutHandler: Handles button input from the remote control.
  • TypingHandler: Handles typing input to provide edit box-like behavior.
  • GesturePanHandler: Handles touch input to provide pan gesture tracking behavior to a UI object.

The following example is a simple way to use rules to show focus from mouse and keyboard input. The box changes color when it has key or mouse focus.

<UI Name="FocusBox">

  <Rules>
    <Default Target="[Input.KeyInteractive]" Value="true" />
    <Condition Source="[Input.KeyFocus]" SourceValue="true">
      <Actions>
        <Set Target="[Outline.Content]" Value="Firebrick"/>
      </Actions>
    </Condition>
  </Rules>

  <Content>
    <ColorFill Name="Outline" Content="Green" Padding="5,5,5,5">
      <Children>
        <ColorFill Content="White" MinimumSize="100,100" Alpha=".5" Padding="3,3,3,3" />
      </Children>
    </ColorFill>
  </Content>
</UI>

The following example uses a key handler and rules to detect when the ENTER key is pressed, and then changes the background color and text.

<UI Name="EnterUI">

  <Locals>
    <KeyHandler Name="EnterHandler" Key="Enter" />
  </Locals>

  <Rules>

    <Condition Source="[EnterHandler.Pressing]" SourceValue="true">
      <Actions>
        <Set Target="[Background.Content]" Value="Yellow" />
      </Actions>
    </Condition>

    <Changed Source="[EnterHandler.Invoked]">
      <Actions>
        <Set Target="[Label.Color]" Value="Red" />
        <Set Target="[Label.Content]" Value="Enter" />
      </Actions>
    </Changed>

  </Rules>

  <Content>
    <ColorFill Name="Background" Content="White" Padding="5,5,5,5"  Layout="VerticalFlow">
      <Children>
        <Text Name="Label" Content="Press Enter" Color="Blue" Font="Arial,20" Margins="30,30,30,30"/>
      </Children>
    </ColorFill>
  </Content>

</UI>

Sample Explorer

  • Input > all samples
  • Input Handlers > all samples

See Also