Working with Input Handlers in MCML

Working with Input Handlers in MCML

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.

The following example is a simple way to use rules to show focus from mouse and keyboard input:

<Mcml xmlns="http://schemas.microsoft.com/2006/mcml"
      xmlns:me="Me">

  <UI Name="Grid">
    <Content>
      <Panel>
        <Layout>
          <FlowLayout Orientation="Vertical" Spacing="5,0" ItemAlignment="Center"/>
        </Layout>
        <Children>
          <me:Row />
          <me:Row />
        </Children>
      </Panel>
    </Content>
  </UI>

  <UI Name="Row">
    <Content>
      <Panel>
        <Layout>
          <FlowLayout Orientation="Horizontal" Spacing="5,0"/>
        </Layout>
        <Children>
          <me:Box />
          <me:Box />
        </Children>
      </Panel>
    </Content>
  </UI>

  <!-- The box changes color when it has key or mouse focus. -->
  <UI Name="Box">

    <Rules>
      <!-- Input.KeyInteractive determines whether this UI can receive key focus. -->
      <Default Target="[Input.KeyInteractive]" Value="true" />
      
      <!-- When the item has keyboard or mouse focus, change the color of the box outline. -->
      <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>
</Mcml>

The following example uses a key handler to detect when the ENTER key is pressed. For additional examples, see the Media Center Markup Language Sampler.

<Mcml
  xmlns="http://schemas.microsoft.com/2006/mcml" >

  <UI Name="EnterUI">

    <!-- Define the properties for this object. -->
    <Properties>
      <Color Name="BackgroundColor" Color="DimGray"/>
      <Color Name="BackgroundPressedColor" Color="White"/>
      <Color Name="LabelColor" Color="White"/>
      <Color Name="LabelPressedColor" Color="Red"/>
    </Properties>

    <Locals>
      <!-- Use the key handler to handle key press events. -->
      <KeyHandler Name="EnterHandler" Key="Enter" />
    </Locals>

    <Rules>
      <!-- Rules to define the behavior when ENTER key is pressed. -->

      <!-- Change the background color while the ENTER key is pressed. -->
      <Condition Source="[EnterHandler.Pressing]" SourceValue="true">
        <Actions>
          <Set Target="[Background.Content]" Value="[BackgroundPressedColor]" />
        </Actions>
      </Condition>

      <!-- Change the label text to indicate that the ENTER key was pressed. -->
      <Changed Source="[EnterHandler.Invoked]">
        <Actions>
          <Set Target="[Label.Color]" Value="[LabelPressedColor]" />
          <Set Target="[Label.Content]" Value="Enter" />
        </Actions>
      </Changed>

    </Rules>

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

  </UI>

</Mcml>

See Also