Keyboard and Numeric Keypad

Surface 1.0 SP1

If your Microsoft Surface application requires text input from users, you can add an on-screen alphanumeric keyboard or numeric keypad to an application. For example, you might use an on-screen keyboard or keypad in the following situations:

  • A single text field where users enter an account name, password, PIN, search field on a map, or note on a postcard.

  • Multiple text fields for a single user in a form that requires a name and a password.

The on-screen keyboard provides the basic typewriter keys along with four arrow keys. An application can use multiple layouts (such as an on-screen keyboard and a numeric keyboard), but it can display only one keyboard at a time.

Keyboard - Alphanumeric layout Keyboard - Numeric keypad layout

Using the Keyboard Functionality

Keyboard functionality is provided by the Shell API, so it is not a specific feature of the Presentation layer or the Core layer. As a result, the keyboard always appears on top of the application that uses it. Users can move a keyboard but they cannot resize it. If users switch from an application that use a keyboard to an application that does not use a keyboard, the keyboard does not appear. However, when users return to the application that uses the keyboard, the keyboard reappears in place.

Because Microsoft Surface units enable multiple touches, the unit does not use the concept of "focus" to describe active features, as in the Microsoft Windows operating systems. But focus is important for the on-screen keyboard. When users touch a text control on a Microsoft Surface unit, they "activate" the control and the keyboard and a cursor appear in the text box. Whatever the user types on the keyboard appears at the cursor position in the text control. In addition, the keyboard and the text in the text control interact like they do in a typical word processor, with a finger substituting for a mouse. That is, users can reposition the cursor in the text control with a finger touch or select a contiguous block of text in the text control by dragging a finger across the text.

An application can specify whether a text control uses an alphanumeric keyboard or a numeric keypad.

When users finish entering text, they can touch the Hide Keyboard button on top of the keyboard. The keyboard then disappears. If users touch another control on the unit while text is being entered, the text control loses its "focus" but the keyboard remains on top.

For more information about keyboard functionality, see the SurfaceKeyboard class.

Keyboards in the Presentation Layer

The Presentation layer offers two text controls:

  • A standard edit field. For more information, see the SurfaceTextBox class.

  • A password field (in which user input displays as asterisks instead of typed characters and the password is treated more securely). For more information, see the SurfacePasswordBox class.

Both of these controls can be single-line or multi-line. For multiple text fields, you must create multiple controls. By default, the keyboard is the basic typewriter layout of the on-screen keyboard.

The Presentation text control automatically calls the Core keyboard API for you. That is, when a user touches a text control in an application, the Microsoft Surface unit automatically displays the keyboard. (The keyboard user interface is controlled by the Surface Shell keyboard API.) The text control treats the layout and position of the keyboard when it is activated as the default values. But you can change these values by editing the properties of the control.

Surface Shell must be running for the keyboard in an application to work. For example, if you test an application on a Microsoft Surface unit by using only Surface Input (and not Surface Shell) and you start the application from Microsoft Visual C# 2008 Express Edition (or Microsoft Visual Studio 2008), a keyboard in that application will not work because Shell is not running. For more information about how to test Microsoft Surface applications, see Testing and Debugging Applications on a Microsoft Surface Unit.

By default, Microsoft Surface sets the state of the CAPS LOCK key to off at the start of each Microsoft Surface session. During a session, the state of the CAPS LOCK key is retained from application to application. If you have an external keyboard that is attached to the Microsoft Surface unit (such as when running in user debug mode or administrator mode), the state of the external keyboard's CAPS LOCK key is synchronized with that of the on-screen keyboard, and vice-versa.


The keyboard's position is determined as follows:

  • If the keyboard is already visible, the suggested position matches the orientation of its current state.

  • If the keyboard is not yet visible, the text control estimates the user's position relative to the screen based on the orientation of the text box that the user touches (and factoring in any render or layout transforms). This orientation is rounded to the nearest edge-aligned value (0, 90, 180, 270). If the text box is oriented between two edge-aligned values, the longer edge wins (for example, a text box at 45 degrees would put the keyboard at 0 degrees). The position of the keyboard is then set so that the bottom of the keyboard (after it is rotated) is centered and flush against the edge were the user is estimated to be.

    This logic might cause the keyboard's position to overlap the text box. If this overlap occurs, the Microsoft Surface unit tries to shift the keyboard in various directions (first to 10 pixels to the left of the control, then 10 pixels to the right, and then 10 pixels above) to avoid covering the text box control. If the unit cannot find a way to avoid the overlap (for example, if the text box covers the entire screen), the unit uses the first suggested position.

    You can diverge from the default positioning behavior by specifying a position when you add the text control. You can also specify that the keyboard displays before users actually touch the text control.

Typically, users do not expect the keyboard to move around when they select different text boxes. They also prefer that the keyboard be connected to the bottom edge of the screen (relative to their position).

Keyboards in the Core Layer

When you are developing a Microsoft Surface application by using the Microsoft XNA development platform, you call the Shell keyboard API directly and specify the keyboard layout to use. You must create the text control and program all the specific interactions between it and the keyboard.

Input Language

The Microsoft Surface unit interprets input according to an input language setting. Microsoft Surface supports a subset of the input language settings that are available to the Windows Vista operating system.

The input language is specified on each Microsoft Surface unit, so it is not necessarily the same language that you use.

The alphanumeric keyboard and numeric keypad change based on the input language:

  • The alphanumeric keyboard uses different layouts for different languages.

  • On the numeric keypad, the BACK and ENTER keys are labeled by using the input language or by using arrows, but their functionality does not change from locale to locale.

The input language for each Microsoft Surface unit is set in the registry, or the Microsoft Surface software determines the best match. Applications cannot specify the input language. For more information, see Deploying Localized Microsoft Surface Applications.

During development and testing, you can use a physical keyboard to enter text into text controls. In testing configurations where Microsoft Surface Shell is running, the application that you are testing uses the Microsoft Surface input language, which might differ from the input language of Microsoft Windows applications. As a result, when you use the physical keyboard, the keyboard might use a different keyboard layout from non-Microsoft Surface applications.

Community Additions