How to use input scope to change the touch keyboard

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

The touch keyboard can be used for text entry when your app runs on a device with a touch screen. The touch keyboard is invoked when the user taps on an editable input field, such as a TextBox or RichEditBox. You can make it much faster and easier for users to enter data in your app by setting the input scope of the text control to match the kind of data you expect the user to enter. The input scope provides a hint at the type of text input expected by the control so the system can provide a specialized touch keyboard layout for the input type.

For example, if a text box is used only to enter a 4-digit PIN, set the InputScope property to Number. This tells the system to show the number keypad layout, which makes it easier for the user to enter the PIN.

Important  The input scope does not cause any input validation to be performed, and does not prevent the user from providing any input through a hardware keyboard or other input device. You are still responsible for validating the input in your code as needed.

Tip  This info applies only to the touch keyboard. It does not apply to hardware keyboards or the On-Screen Keyboard available in the Windows Ease of Access options.

Changing the input scope of a text control

The input scopes that are available in a Windows Runtime app are members of the InputScopeNameValue enumeration. You can set the InputScope property of a TextBox or RichEditBox to one of these values.

In this procedure, you change the input scope of several text boxes to match the expected data for each text box. This procedure assumes that you have a Windows Runtime app with a page that contains these controls.

To change the input scope in XAML

1. In the XAML file for your page, locate the tag for the text control that you want to change.

   Here are some text boxes that might appear on a common customer-contact form.

   <StackPanel Width="300">
       <TextBox Header="Name"/>
       <TextBox Header="Email Address"/>
       <TextBox Header="Telephone Number"/>
       <TextBox Header="Web site"/>
   </StackPanel>
   

2. Add the InputScope attribute to the tag and specify the InputScopeNameValue value that matches the expected input.

   With the InputScope set, a touch keyboard with a suitable layout for the data shows for each text box.

   <StackPanel Width="300">
       <TextBox Header="Name" InputScope="Default"/>
       <TextBox Header="Email Address" InputScope="EmailSmtpAddress"/>
       <TextBox Header="Telephone Number" InputScope="TelephoneNumber"/>
       <TextBox Header="Web site" InputScope="Url"/>
   </StackPanel>
   

To change the input scope in code

1. In the XAML file for your page, locate the tag for the text control that you want to change. If it's not set, set the x:Name attribute so you can reference the control in your code.

   <TextBox Header="Telephone Number" x:Name="phoneNumberTextBox"/>
   

2. Instantiate a new InputScope object.

   InputScope scope = new InputScope();
   

3. Instantiate a new InputScopeName object.

   InputScopeName scopeName = new InputScopeName();
   

4. Set the NameValue property of the InputScopeName object to a value of the InputScopeNameValue enumeration.

   scopeName.NameValue = InputScopeNameValue.TelephoneNumber;
   

5. Add the InputScopeName object to the Names collection of the InputScope object.

   scope.Names.Add(scopeName);
   

6. Set the InputScope object as the value of the text control's InputScope property.

   phoneNumberTextBox.InputScope = scope;
   

Here's the code all together.

InputScope scope = new InputScope();
InputScopeName scopeName = new InputScopeName();
scopeName.NameValue = InputScopeNameValue.TelephoneNumber;
scope.Names.Add(scopeName);
phoneNumberTextBox.InputScope = scope;

The same steps can be condensed into this shorthand code.

phoneNumberTextBox.InputScope = new InputScope() 
{
    Names = {new InputScopeName(InputScopeNameValue.TelephoneNumber)}
};

Text prediction, spell checking, and auto-correction

The TextBox and RichEditBox controls have several properties that influence the behavior of the touch keyboard. To provide the best experience for your users, it's important to understand how these properties affect text input using touch.

• IsSpellCheckEnabled—When spell check is enabled for a text control, the control interacts with the system's spell-check engine to mark words that are not recognized. You can tap a word to see a list of suggested corrections.

  By default, spell check for the TextBox control is disabled on Windows, and enabled on Windows Phone. For the RichEditBox control, it's enabled on both platforms.

  For the Default input scope, this property also enables automatic capitalization of the first word in a sentence and autocorrection of words as you type. These autocorrection features might be disabled in other input scopes. For more info, see the tables later in this topic.

• IsTextPredictionEnabled—When text prediction is enabled for a text control, the system shows a list of words that you might be beginning to type. You can select from the list so you don't have to type the whole word.

  By default, text prediction is enabled for the TextBox and RichEditBox controls on Windows and Windows Phone.

  Text prediction might be disabled if the input scope is other than Default, even if the IsTextPredictionEnabled property is true. For more info, see the tables later in this topic.

  Note  For Windows Phone Store apps, text predictions and spelling corrections are shown in the area above the touch keyboard. If IsTextPredictionEnabled is set to false, this part of the keyboard is hidden and auto-correction is disabled, even if IsSpellCheckEnabled is true.

• PreventKeyboardDisplayOnProgrammaticFocus—When this property is true, it prevents the system from showing the touch keyboard when focus is programmatically set on a text control. Instead, the keyboard is shown only when the user interacts with the control.

Touch keyboard index for Windows and Windows Phone

These tables show the Windows and Windows Phone touch keyboard layouts for common input scope values. The effect of the input scope on the features enabled by the IsSpellCheckEnabled and IsTextPredictionEnabled properties is listed for each input scope. This is not a comprehensive list of available input scopes.

Note  The smaller size of the touch keyboard on the phone makes it particularly important for Windows Phone Store apps that you set the correct input scope. As we show here, Windows Phone provides a greater variety of specialized keyboard layouts. A text field that doesn't need to have its input scope set in a Windows Store app might benefit from having it set in a Windows Phone Store app.

Tip  You can toggle most touch keyboards between an alphabetic layout and a numbers-and-symbols layout. On Windows, toggle the &123 key. On Windows Phone, press the &123 key to change to the numbers-and-symbols layout, and press the abcd key to change to the alphabetic layout.

Default

<TextBox InputScope="Default"/>

The default keyboard.

Availability of features:

• Spell check: enabled if IsSpellCheckEnabled = true, disabled if IsSpellCheckEnabled = false
• Auto-correction: enabled if IsSpellCheckEnabled = true, disabled if IsSpellCheckEnabled = false
• Automaticcapitalization: enabled if IsSpellCheckEnabled = true, disabled if IsSpellCheckEnabled = false
• Text prediction: enabled if IsTextPredictionEnabled = true, disabled if IsTextPredictionEnabled = false

Windows	Windows Phone
	Important  On Windows Phone, text predictions and spelling corrections are shown in the area above the touch keyboard. If IsTextPredictionEnabled is set to false, this part of the keyboard is hidden and auto-correction is disabled, even if IsSpellCheckEnabled is true.

CurrencyAmountAndSymbol

<TextBox InputScope="CurrencyAmountAndSymbol"/>

The default numbers and symbols keyboard layout.

Windows	Windows Phone
Also includes page left/right keys to show more symbols. Availability of features: Spell check: off by default, can be enabled Auto-correction: always disabled Automaticcapitalization: always disabled Text prediction: always disabled	Availability of features: Spell check: on by default, can be disabled Auto-correction: on by default, can be disabled Automaticcapitalization: always disabled Text prediction: on by default, can be disabled

Url

<TextBox InputScope="Url"/>

Includes the .com and Go keys. Press and hold the .com key to display additional options (.org, .net, and region-specific suffixes).

Windows	Windows Phone
Also includes the :, -, and / keys. Availability of features: Spell check: off by default, can be enabled Auto-correction: always disabled Automaticcapitalization: always disabled Text prediction: always disabled	Press and hold the period key to display additional options ( - + & " : / ). Availability of features: Spell check: off by default, can be enabled Auto-correction: off by default, can be enabled Automaticcapitalization: off by default, can be enabled Text prediction: off by default, can be enabled

EmailSmtpAddress

<TextBox InputScope="EmailSmtpAddress"/>

Includes the @ and .com keys. Press and hold the .com key to display additional options (.org, .net, and region-specific suffixes).

Windows	Windows Phone
Also includes the _ and - keys. Availability of features: Spell check: off by default, can be enabled Auto-correction: always disabled Automaticcapitalization: always disabled Text prediction: always disabled	Press and hold the period key to display additional options ( - _ , ; ). Availability of features: Spell check: off by default, can be enabled Auto-correction: off by default, can be enabled Automatic capitalization: off by default, can be enabled Text prediction: off by default, can be enabled

Number

<TextBox InputScope="Number"/>

Windows	Windows Phone
Same as CurrencyAmountAndSymbol.	Keyboard contains numbers and a decimal point. Press and hold the decimal point key to display additional options ( , - ). Availability of features: Spell check: always disabled Auto-correction: always disabled Automatic capitalization: always disabled Text prediction: always disabled

TelephoneNumber

<TextBox InputScope="TelephoneNumber"/>

Windows	Windows Phone
Same as CurrencyAmountAndSymbol.	Keyboard mimics the telephone keypad. Press and hold the period key to display additional options ( , ( ) X . ). Press and hold the 0 key to enter +. Availability of features: Spell check: always disabled Auto-correction: always disabled Automatic capitalization: always disabled Text prediction: always disabled

Search

<TextBox InputScope="Search"/>

Includes the Search key instead of the Enter key.

Windows	Windows Phone
Availability of features: Spell check: off by default, can be enabled Auto-correction: always disabled Auto-capitalization: always disabled Text prediction: always disabled	Availability of features: Spell check: on by default, can be disabled Auto-correction: on by default, can be disabled Auto-capitalization: always disabled Text prediction: on by default, can be disabled

SearchIncremental

<TextBox InputScope="SearchIncremental"/>

Formula

<TextBox InputScope="Formula"/>

Includes the = key.

Windows	Windows Phone
Also includes the %, $, and + keys. Availability of features: Spell check: off by default, can be enabled Auto-correction: always disabled Automatic capitalization: always disabled Text prediction: always disabled	Press and hold the period key to display additional options ( - ! ? , ). Press and hold the = key to display additional options ( ( ) : < > ). Availability of features: Spell check: on by default, can be disabled Auto-correction: on by default, can be disabled Automatic capitalization: always disabled Text prediction: on by default, can be disabled

Chat

<TextBox InputScope="Chat"/>

Windows	Windows Phone
Same layout as Default. Availability of features: Spell check: off by default, can be enabled Auto-correction: always disabled Automatic capitalization: always disabled Text prediction: always disabled	Includes emoticons. Availability of features: Spell check: on by default, can be disabled Auto-correction: on by default, can be disabled Automatic capitalization: on by default, can be disabled Text prediction: on by default, can be disabled

NameOrPhoneNumber

<TextBox InputScope="NameOrPhoneNumber"/>

Windows	Windows Phone
Same layout as Default. Availability of features: Spell check: off by default, can be enabled Auto-correction: always disabled Automatic capitalization: always disabled Text prediction: always disabled	Includes the ; and @ keys. The &123 key is replaced by the 123 key, which opens the phone keypad (see TelephoneNumber). Availability of features: Spell check: off by default, can be enabled Auto-correction: off by default, can be enabled Automatic capitalization: off by default, can be enabled Text prediction: off by default, can be enabled