Silverlight Keyboard Support

Article
11/08/2007

Microsoft Silverlight provides a set of keyboard events that enable you to respond to keystroke actions.

This topic contains the following sections:

Keyboard Events
Defining a Keyboard Event Handler
Platform Differences for Keyboard Events
Inputting Text

Keyboard Events

Silverlight provides the keyboard events described in the following table.

Event	Description
KeyDown	Occurs when a key is pressed while the plug-in has focus.
KeyUp	Occurs when a key is released while the plug-in has focus.

Note Handling keyboard events might vary between browsers. When you create an application that uses keyboard input, make sure to test the application in your target browsers.

The following XAML example shows how to define the KeyDown event for the Canvas object. Notice that the event-handler function cannot be called with parameter values, unlike JavaScript event-handler functions.

XAML
<Canvas xmlns="https://schemas.microsoft.com/client/2007" KeyUp="onKeyUp" />

Note Keyboard events can be defined only for the root Canvas object of a Silverlight plug-in.

The following example shows how to define a Silverlight keyboard event in JavaScript. If you attempt to define a keyboard event for any object other than the root Canvas object, a parser exception is thrown.

JavaScript
function onLoaded(sender, eventArgs) { // Set the root Canvas object to a KeyUp event handler function. sender.addEventListener("KeyUp", onKeyUp); }

Keyboard Events and Focus

In order for a keyboard event to be received, the Silverlight plug-in needs to have focus; otherwise, the events are not generated. A Silverlight plug-in can gain focus through user actions such as clicking the plug-in or tabbing to it.

Keyboard Events and the Browser

The browser determines which keystrokes it interprets as commands, and which keystrokes it passes on to hosted content. This means that certain keystrokes cannot be retrieved from KeyDown and KeyUp event-handler functions. Most keystrokes that a browser interprets as commands are shortcut, or accelerator, keystokes. For example, CTRL+D is a shortcut keystroke combination for adding a favorite URL to the Firefox and Internet Explorer browsers.

Keyboard Events and Full-Screen Mode

When a Silverlight plug-in is displayed in full-screen mode, keyboard events are prevented from being passed to keyboard event handlers in the application. The only valid keyboard input that is acted upon is the set of keystrokes that returns the Silverlight plug-in to embedded mode. This limitation of keyboard input during full-screen mode is a security feature. It is intended to minimize the possibility of unintended information being entered by a user. For more information on full-screen mode, see Silverlight Full-Screen Support.

Defining a Keyboard Event Handler

A Silverlight keyboard event-handler function contains two parameters, as described in the following table.

Parameter	Description
sender	Identifies the Silverlight object that generated the event. You can retrieve the type value of the object by calling the ToString method on the parameter value.
keyEventArgs	Identifies the set of argument values for the specific event. The keyEventArgs parameter contains the following values: Key -- An integer value that represents the key that is down. This value is the portable key code, which is not operating system-specific. PlatformKeyCode -- An integer value that represents the key that is down. This value is the non-portable key code, which is operating system-specific. Shift -- A Boolean value that determines whether the SHIFT key is down. Ctrl -- A Boolean value that determines whether the CTRL key is down.

sender

Identifies the Silverlight object that generated the event. You can retrieve the type value of the object by calling the ToString method on the parameter value.

keyEventArgs

Identifies the set of argument values for the specific event. The keyEventArgs parameter contains the following values:

Key -- An integer value that represents the key that is down. This value is the portable key code, which is not operating system-specific.
PlatformKeyCode -- An integer value that represents the key that is down. This value is the non-portable key code, which is operating system-specific.
Shift -- A Boolean value that determines whether the SHIFT key is down.
Ctrl -- A Boolean value that determines whether the CTRL key is down.

Note If the Silverlight event-handler function does not reference the sender and keyEventArgs parameters, you do not have to define them as part of the function declaration.

The following JavaScript example shows how to define a Silverlight event-handler function for the KeyDown event. In this case, the code displays a string in an alert dialog box that contains the version of the Silverlight plug-in.

JavaScript
function onKeyUp(sender, keyEventArgs) { // Determine whether the keystroke combination CTRL+V was detected. if ((keyEventArgs.key == 51) && (keyEventArgs.ctrl == true)) { // Retrieve a reference to the plug-in. var plugin = sender.getHost(); // Determine whether the 1.0 version of Silverlight is available. alert("Silverlight 1.0: " + plugin.isVersionSupported("1.0")); } }

function onKeyUp(sender, keyEventArgs)
{
    // Determine whether the keystroke combination CTRL+V was detected.
    if ((keyEventArgs.key == 51) && (keyEventArgs.ctrl == true))
    {
        // Retrieve a reference to the plug-in.
        var plugin = sender.getHost();
        // Determine whether the 1.0 version of Silverlight is available.
        alert("Silverlight 1.0: " + plugin.isVersionSupported("1.0"));
    }
}

Detecting the SHIFT and CTRL Keys in a Mouse Event Handler

The MouseEnter, MouseLeftButtonDown, MouseLeftButtonUp, and MouseMove events enable you to determine whether the SHIFT or CTRL keys are down when the mouse event-handling function is invoked. The following JavaScript example shows how to implement a MouseLeftButtonDown event-handler function that displays the values of the mouseEventArgs parameter.

JavaScript
function onMouseLeftButtonUp(sender, mouseEventArgs) { // Concatenate the values of the MouseEventArgs parameter. var msg = "x = " + mouseEventArgs.getPosition(null).x; msg += " y = " + mouseEventArgs.getPosition(null).y; msg += " shift = " + mouseEventArgs.shift; msg += " ctrl = " + mouseEventArgs.ctrl; alert(msg); }

function onMouseLeftButtonUp(sender, mouseEventArgs)
{
    // Concatenate the values of the MouseEventArgs parameter.
    var msg  = "x = " + mouseEventArgs.getPosition(null).x;
    msg += "  y = " + mouseEventArgs.getPosition(null).y;
    msg += "  shift = " + mouseEventArgs.shift;
    msg += "  ctrl = " + mouseEventArgs.ctrl;
    alert(msg);
}

Platform Differences for Keyboard Events

The keyboardEventArgs parameter of KeyDown and KeyUp events provides two types of key codes:

Key -- A portable key code that is not operating system-specific.
PlatformKeyCode -- A non-portable key code that is operating system-specific.

The portable key codes are a common subset of all the possible key codes of the supported operating systems, in this case, Macintosh and Windows. For example, the keystroke 'v' is represented as a Key value of 51, and a PlatformKeyCode value of 86. Certain keystrokes, however, are not portable, such as the Windows SCROLL LOCK key. In this case, the Key value is 255, which is the value for an unknown key, and the PlatformKeyCode is 145 on a Windows platform. For information about 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.

Detecting Platforms in JavaScript

When you visit a Web page, your browser sends the user agent string to the server that is hosting the site you are visiting. This string indicates which browser you are using, its version number, and details about your system, such as operating system and version. You can use this string to determine the platform the browser-hosted Silverlight plug-in is running on. The following JavaScript example shows how to create a set of variables that you can use in keyboard event-handling functions to determine the platform.

JavaScript
// Create variables to detect browser platform. var is_mac = (navigator.userAgent.indexOf("Macintosh") != -1); var is_win = (navigator.userAgent.indexOf("Windows") != -1);

Inputting Text

There is no "TextBox" control for Silverlight 1.0. To input text into a Silverlight-based application, you can overlay an HTML control such as TEXTAREA over your Silverlight-based application. You would then use JavaScript to pass the inputted text back and forth between the Silverlight-based application and the HTML TEXTAREA control. See Mixing Object Models for an example. Also, see Using Input Method Editors for Text Entry in Silverlight for a video that shows how to allow user text input.

Share via