Keyboard Support

In order for a keyboard event to be received, the object must have focus; otherwise, keyboard events are not generated. There are two levels of focus: focus at the plug-in level, and focus at the level of an individual UI element within the Silverlight content area.

A Silverlight plug-in gains focus when the user clicks the plug-in area, tabs to it from the browser-level tab sequence, or provides the appropriate activation action for the plug-in model. You can also call the HTML DOM Focus method in most cases if you want to force focus at the HTML level. The exact focus behavior when Silverlight content is first loaded varies. This depends on whether content is browser hosted, and also can vary for specific browser hosts.

An individual element gains focus when the user clicks directly on that element in the layout, or uses the TAB key to step into a Silverlight tab sequence within the Silverlight content area. You can also call a control's Focus method to force focus, but only if the particular UIElement is also a Control. Generally, if you are forcing focus, you are doing so in order to enable keyboard input for that UI element, and only visible controls have a typical need to process any keyboard input.

If the user clicks an element in the Silverlight plug-in content area, both of these focus conditions occur simultaneously (and sometimes GotFocus fires twice in this case).

For more information about focus and its behavior in the API and through user interaction, see Focus Overview.

When a Silverlight-based application is hosted in a browser, different browsers might handle keyboard events differently, because of issues such as host keyboard handling that signify commands, and nonportable key codes. When you create an application that uses keyboard input, make sure to test the application in each of your target deployment browsers.

If an application is browser-hosted, the browser host determines which keystrokes it interprets as commands and which keystrokes it passes on to hosted content. This means that certain keystroke combinations cannot be retrieved from KeyDown and KeyUp event handler functions in some set of browser hosts. Most keystrokes that a browser hosts interprets as commands are shortcut or accelerator keystrokes, and when this happens the keystrokes are not passed as key events to Silverlight. For example, CTRL+D is a shortcut keystroke combination for adding a favorite URL to the Firefox and Internet Explorer browser hosts, and neither CTRL nor D is reported as a key event to the intermediate hosting layer that Silverlight must use as its input source when Silverlight-based applications are hosted by a browser.

Browser host behavior also influences auto-repeat behavior for the KeyDown event. Internet Explorer browser hosts can issue repeated key-down events at the browser level for cases where a key remains held down. This auto-repeat behavior is also surfaced by the Silverlight KeyDown event. But some browser hosts do not provide auto-repeat key-down information to their plug-in integration layer, and therefore Silverlight cannot auto-repeat KeyDown for these cases.

When a Silverlight plug-in is displayed in full-screen mode, and the application is either browser-hosted or out-of-browser without elevated trust, keyboard events for the full range of possible keys are prevented from being passed to keyboard event handlers in the application. The following considerations apply when an application is running in full-screen mode:

• The specific keys UP ARROW, DOWN ARROW, LEFT ARROW, RIGHT ARROW, SPACEBAR, TAB, PAGE UP, PAGE DOWN, HOME, END, ENTER still generate KeyDown and KeyUp. These keys can then be used to initiate actions in your application even if running in full-screen mode.

• All other keys do not raise KeyDown and KeyUp, and thus you cannot act on these key inputs.

• ESC is handled by Silverlight and returns theapplication to embedded mode.

This limitation of keyboard input during full-screen mode is a security feature. For more information, see Full-Screen Support.

However, an out-of-browser application that uses elevated trust does not have this restriction, and can handle all key events while operating in full-screen mode. For more information, see Trusted Applications.

The KeyDown event is raised if a key is pressed (likewise, KeyUp is raised if a key is released). Usually you are listening to the events in order to process a specific key value. To determine which key is pressed or released, check the Key value in the event data. Key returns either a value that is a portable key value (a member of the Key enumeration), or it returns Key.Unknown.

If Key is not Unknown, then the event represents a single specific portable key value, and you can check it against expected values in your handler to see whether your handler should respond further.

The portable key codes are a common subset of all the possible key codes of the supported platforms for Silverlight. For example, the keystroke 'v' is represented as a Key value of Key.V.

Certain keystrokes are not portable. An example is the SCROLL LOCK key in Microsoft Windows.

If Key equals Unknown, then a key has been pressed or released, but that key is specific to a particular platform. In this case, you can check the PlatformKeyCode property value. This property returns an integer. The integer must be evaluated in the context of what that integer value means for a particular platform and how it maps its key codes. For information about Microsoft Windows-specific key codes, see Virtual-Key Codes in the MSDN Library. For information on Macintosh-specific key codes, see Keyboard Layout Services Reference on the Apple Developer Connection Web site.

Note:

Determining the platform (which may be necessary to interpret a PlatformKeyCode property value) is not documented in this topic. Depending on your overall application design, you can do this at the HTML or browser host level, by analyzing the HTTP request headers of the hosting HTML page, or by setting a variable on installation of an out-of-browser application. Within the managed API, Silverlight provides the BrowserInformation class, as well as other types in the System.Windows.Browser namespace that might be useful for capturing information that is also available in the HTML DOM or to the browser host.

Certain keystrokes are considered to be modifier keys. These are keys that are usually pressed in conjunction with other keys. Modifier keys that are used on all platforms include the SHIFT and CTRL keys. Certain modifier keys are platform specific.

Note:
The key for CTRL may have different labeling on some keyboards. The string CTRL is used in this documentation to identify the key, because this matches the Key.Ctrl value in the API.

Usually you interpret modifier keys in order to check whether a modifier key is pressed and held down at the time that another key event is also received. This is because the other key plus a modifier represents a key combination that is of interest to your application. The modifier key information is not transmitted as part of the same event data in this case. Instead, you use the Keyboard utility class from within your event handlers to check for the modifiers, as part of handling the event for the key value that is potentially modified.

To determine which modifiers are applied, check the Modifiers value of the Keyboard static class. This property returns a ModifierKeys flag enumeration value. The value is a flag because multiple modifiers might be pressed.

However, independent of how you process modifiers for other non-modifier key events, a modifier key still generates its own key events. You can choose to handle these, and you can also choose to track your own modifier key state, but using the Modifiers value is generally more convenient.

Note:
The CTRL key in combination with a mouse click might be involved in producing a right-click mouse input equivalent on Macintosh platforms.

The following example is an event handler that handles KeyUp. This handler is specifically checking for the CTRL+V key combination. Any other key value (including an unmodified Key.V value) is ignored.

void Canvas_KeyUp(object sender, KeyEventArgs e)
{
    //check for the specific 'v' key, then check modifiers
    if (e.Key==Key.V) { 
        if ((Keyboard.Modifiers & ModifierKeys.Control) == ModifierKeys.Control) {
        //specific Ctrl+V action here
        }
    } // else ignore the keystroke
}

Private Sub Canvas_KeyUp(ByVal sender As Object, ByVal e As KeyEventArgs)
    'check for the specific v key, then check modifiers
    If (e.Key = Key.V) Then
        If ((Keyboard.Modifiers And ModifierKeys.Control) = ModifierKeys.Control) Then
            'specific Ctrl+V action here
        Else 'ignore the keystroke
        End If
    End If
End Sub

Depending on your event handling strategy, you might want only one event handler to react to a bubbling event. For instance, if you have a specific KeyUp handler for one of the Button objects, you might not want the parent panel to also handle the event. For this scenario, use the Handled property in the event data.

The purpose of Handled in a Silverlight routed event data class is to influence the behavior of the Silverlight routed event system, to report that some other handler you had registered earlier on the event route has already acted. When you set Handled to true in an event handler, that event stops routing and is not sent to successive parent elements.

The following example is a modification of the previous event-handler example, this time using Handled. If the event is already handled, the handler will not be able to respond. If the event is not already handled, the handler is invoked. In this case, the event handler also sets Handled to true so that any handlers attached further in the event route and the object tree will not be invoked.

void ButtonKB(object sender, KeyEventArgs e)
{
    if (e.Key!=Key.Unknown) {
        e.Handled=true;
        String msg = "The key " + e.Key.ToString();
        msg += " was handled while focus was on " 
            + (sender as FrameworkElement).Name;
        statusTextBlock.Text = msg;
    }
}

Private Sub ButtonKB(ByVal sender As Object, ByVal e As KeyEventArgs)
    If Not (e.Key = Key.Unknown) Then
        e.Handled=True
        Dim fe As FrameworkElement = sender
        Dim msg As String = "The key " & e.Key.ToString()
        msg = msg & " was handled while focus was on "
        msg = msg & fe.Name
        statusTextBlock.Text = msg
    End If
End Sub

You can use a special technique for attaching handlers that can act on events that already are marked handled. This technique uses the AddHandler method to register a handler, rather than using XAML attributes or language specific handler adding syntax such as += in C#. A limitation of this technique in general is that the AddHandler API takes a parameter of type RoutedEvent that identifies the routed event in question. Not all Silverlight routed events provide a RoutedEvent identifier, and this consideration thus affects which routed events can still be handled in the Handled case. The keyboard events KeyDown and KeyUp have routed event identifiers as fields on UIElement. So do TextInput , TextInputStart and TextInputUpdate. However, other related text entry events such as TextBox.TextChanged do not have routed event identifiers and thus cannot be used for the AddHandler technique.

In Silverlight 5, a small number of UI elements support commanding. Commanding is a concept that can apply either to mouse or keyboard input, because the input action is abstracted into the command itself. For more information, see the "Commanding" section of Mouse Support.