Handling Key Events to Enable Keyboard Functionality in Silverlight

Applicability

• Microsoft Silverlight, versions 3 and greater
• Silverlight managed programming model and Silverlight XAML

This technique relates to Success Criterion 2.1.1: Keyboard (Sufficient as a way to meet G90: Providing keyboard-triggered event handlers).

Description

The objective of this technique is to handle key events in a Silverlight application and enable application-specific keyboard functionality in a Silverlight application. The keyboard functionality might relate to a particular element of the Silverlight application user interface, or might be a handler for global key events within the application, such as an application-wide access key.

In Silverlight, application authors handle user input by attaching event handlers for input events. The input events are implemented on a class that is a base element in the Silverlight class hierarchy, such that all Silverlight UI elements can be the source of an input event if the user interacts with them. Typically, the event handler names are specified in XAML, although it is also possible to wire events in code. The implementation of the handlers for the Silverlight managed code programming model is always done in C# or Visual Basic code.

The most commonly used input events are the following:

• KeyUp, KeyDown - these are the key events. Which key is pressed is determined by event parameters passed to the handler.
• MouseEnter, MouseOver, MouseLeave
• MouseLeftButtonDown, MouseLeftButtonUp, MouseRightButtonDown, MouseRightButtonUp

Other forms of input that Silverlight supports include touch devices (with mouse promotion for cases where the application runs on devices that do not have touch input modes) and a related inking mode. For any UI interaction that uses mouse input or these other input modes, Silverlight application authors can write a parallel key event handler to provide users the keyboard equivalent.

Also, the Silverlight event system and control model combine to enable behavior whereby a mouse event and a keyboard event can be treated as the same event and can be handled by a common event handler. Using this technique, Silverlight authors can facilitate keyboard functionality in custom controls or as override behavior to existing Silverlight-supplied controls, and provide equivalence for mouse events or events that are specific to other input devices. Silverlight authors can also use controls that already have a keyboard equivalence as a built-in behavior.

The parallel key event handler case, and the built-in behavior case, are each shown in one of the examples.

All input events report a specific source that is communicated to handler code as an event parameter, so that the application author can identify which element in their Silverlight UI was being interacted with, and the application can perform an action that is relevant to that user input. In the case of mouse events, the event source is the element that the mouse pointer is over at the time. In the case of key events, the event source is the element that has focus. The element that has focus is visually indicated so that the user knows which element they are interacting with (see ). Assistive technologies often have parallel conventions whereby the user is made aware of which element is visually focused and is the current input scope presented by the assistive technology,

Examples

Two examples are given. The first example is for the scenario of a Silverlight application author that is simply incorporating an existing control into their application design, and is taking advantage of mouse-keyboard equivalence that is already defined by certain Silverlight core controls. The second example is from the perspective of a control author, or at least that of a Silverlight application author that intends to encapsulate behavior in a custom Silverlight control and use it in their own application. For this second example, the control will handle the general Silverlight input event KeyUp, in order to check for input from key(s) that are designated to have a specific input meaning for that control.

<UserControl x:Class="BuiltInKeyEquivalence.MainPage"
   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
>
   <Grid x:Name="LayoutRoot" Background="White" Loaded="LayoutRoot_Loaded">
       <Button Name="button1"
   AutomationProperties.Name="Equivalence test"
   Height="20" Width="150"
   Click="button1_Click">Click me, or press SPACE!</Button>
   </Grid>
</UserControl>

   private void button1_Click(object sender, RoutedEventArgs e)
   {
       MessageBox.Show("You clicked a button ... or maybe you hit the space bar ... or ENTER ... it's all the same to me.");
   }
   private void LayoutRoot_Loaded(object sender, RoutedEventArgs e)
   {
       System.Windows.Browser.HtmlPage.Plugin.Focus();
    }

<ControlTemplate TargetType="local:SimpleNumericUpDown">
  <Border Background="{TemplateBinding Background}"
          BorderBrush="{TemplateBinding BorderBrush}"
          BorderThickness="{TemplateBinding BorderThickness}" Name="controlFrame">
      <Grid>
          <Grid.ColumnDefinitions>
              <ColumnDefinition Width="*"/>
              <ColumnDefinition Width="30"/>
          </Grid.ColumnDefinitions>
          <TextBox x:Name="valueBox" Text="{Binding NumericValue, RelativeSource={RelativeSource TemplatedParent}}"/>
          <StackPanel Grid.Column="1">
              <Button Name="minusButton">-</Button>
              <Button Name="plusButton">+</Button>
          </StackPanel>
      </Grid>
  </Border>
</ControlTemplate>

   public class SimpleNumericUpDown : Control
   {
       public SimpleNumericUpDown()
       {
           this.DefaultStyleKey = typeof(SimpleNumericUpDown);
       }
       
       public override void OnApplyTemplate()
       {
           base.OnApplyTemplate();
           Button plusButton = GetTemplateChild("plusButton") as Button;
           Button minusButton = GetTemplateChild("minusButton") as Button;
           Border controlFrame = GetTemplateChild("controlFrame") as Border;
           plusButton.Click += new RoutedEventHandler(Increment);
           minusButton.Click += new RoutedEventHandler(Decrement);
           controlFrame.KeyUp += new KeyEventHandler(Handle_Accelerators);
       }
       private void Increment(object sender, RoutedEventArgs e)
       {
           this.NumericValue += 1;
       }
       private void Decrement(object sender, RoutedEventArgs e)
       {
           this.NumericValue -= 1;
       }
       private void Handle_Accelerators(object sender, KeyEventArgs e)
       {
           switch (e.Key)
           {
               case (Key.Left):
                   this.NumericValue -= 1; 
                   e.Handled=true;
                   break;
               case (Key.Right):
                   this.NumericValue += 1; 
                   e.Handled=true;
                   break;
               default: break;
           }
       }
       public Int32 NumericValue //definition omitted in this example
   }

Resources

Resources are for information purposes only, no endorsement implied.

• KeyUp
• Keyboard Support
• Focus Overview
• Creating a New Control by Creating a ControlTemplate
• Events Overview for Silverlight

Related Techniques

• G90: Providing keyboard-triggered event handlers

Tests