- Orientation
- The On-Screen Keyboard
- The Hardware Keyboard
- The User Interface
- The Code-Behind
- The Finished Product
This chapter is from the book
This chapter is from the book
This chapter is from the book
The On-Screen Keyboard
The on-screen keyboard is the primary mechanism for typing on a Windows phone. For many models, it is the only way. It is sometimes called the software input panel (SIP). When it appears, it covers the bottom 339 pixels of the screen in the portrait orientation or the bottom 259 pixels in the landscape orientations. (In landscape, its keys expand horizontally but shrink vertically.) It occupies an additional 62 pixels when text suggestions are given, or when copy/paste has been used.
There are no APIs for interacting with the on-screen keyboard. Instead, it automatically slides up when a text box or password box gets focus (normally from a user tapping on it) and it automatically slides down when the text box or password box loses focus (normally from a user tapping on something else or pressing the hardware Back button). There is no way to leverage the on-screen keyboard in your app without using a text box or password box.
Can I force the on-screen keyboard to appear without requiring the user to tap on a text box or password box?
Yes, but you still need a text box or password box to get focus and receive the keystrokes. Therefore, you can accomplish this by programmatically giving it focus. This can be done by calling its Focus method, although this call can fail (and return false) under certain conditions. For example, you cannot set focus on a control from a page's constructor; it's too early. You can, however, call it from a page's Loaded event.
The design guidelines recommend automatically showing the on-screen keyboard when navigating to a page only when doing so does not obscure other parts of the page. So for "In Case of Emergency," this behavior is not appropriate.
The most interesting aspect of the on-screen keyboard, and what gives it a big advantage over a hardware keyboard, is its ability to change its display depending on the context. For example, it can show a ".com" button when it knows you need to type a URL, or a phone keypad when it knows you need to type a phone number.
Can I force the on-screen keyboard to disappear without requiring the user to tap on something else?
Yes, by programmatically giving focus to a control other than the text box or password box. This is commonly done in response to the user tapping the Enter key, because this key otherwise does nothing except for multiline text boxes. This chapter's app demonstrates this technique.
The on-screen keyboard can currently appear in 11 different modes. You can choose which one to use by marking the relevant text box with an appropriate input scope. An input scope is basically a pre-defined label that can be assigned to a text box's InputScope property. Some examples are Default, Url, and PhoneNumber. It can be assigned in XAML as follows:
<TextBox InputScope="PhoneNumber"/>
The list of allowed input scopes is provided by the InputScopeNameValue enumeration. The confusing thing about input scopes, however, is that there are 62 valid values despite there being only 11 distinct keyboard modes!
Marking a text box with an input scope as specific as possible (such as TelephoneAreaCode) is a good idea even if it has no effect compared to a more generic choice. Consider it as extra documentation for any developer who reads your code. Plus, because you're communicating your intent to the operating system, one day a future version might provide a better experience for your chosen context. (For TelephoneAreaCode, you could imagine a future experience where you can see the geographic name corresponding to the chosen area code, or where you can even search for area codes geographically.)
So how do 62 values map into 11 modes? Some values are simply synonyms for the same concept, such as Numbers versus Digits. Some values express different intent, but there is no meaningful way for the keyboard to show distinct displays, such as PersonalGivenName versus PersonalMiddleName versus PersonalSurname. Some values would ideally produce different displays (and might in a future release) but are currently lumped together, such as CurrencyAmount versus CurrencyAmountAndSymbol. Many other values are simply not implemented and produce the default display instead, such as Password, CurrencyChinese, and Bopomofo. Table 3.1 lists all 62 values grouped into the 11 distinct modes and shows the resulting on-screen keyboard.
Table 3.1. The Valid Values for a Text Box's Input Scope and the Resulting Keyboard Display
|
Name |
Description |
Result |
Default AlphanumericFullWidth AlphanumericHalfWidth Bopomofo CurrencyChinese EnumString FileName FullFilePath Hanja Hiragana KatakanaFullWidth KatakanaHalfWidth LogOnName NumberFullWidth OneChar Password PhraseList RegularExpression Srgs Yomi |
The default mode. It starts on a page with letter keys, and has a "&123"button to switch to a page with number and symbol keys. |
|
Number Digits AddressStreet CurrencyAmount CurrencyAmountAndSymbol DateDay DateMonth DateYear PostalAddress PostalCode Time TimeHour TimeMinorSec TelephoneNumber TelephoneAreaCode TelephoneCountryCode TelephoneLocalNumber |
"Numeric mode." This is still the default keyboard, but it starts on the page with number and symbol keys. You can switch to the page of letter keys by pressing the "abcd" button. |
|
TelephoneNumber TelephoneAreaCode TelephoneCountryCode TelephoneLocalNumber |
Used for entering a phone number. Shows a keypad that looks similar to the Phone app's keypad. Adds an extra column of keys for backspace, space, comma, and period. The latter two are there in case you want to use this mode as a better "numeric mode." |
|
Url |
Used for entering a URL. Shows a ".com" button instead of a comma and restyles the Enter key.(The comma still appears on the numbers and symbols page.) I wish the enter key always looked like this, because I sometimes confuse the default one with the backspace key! |
|
EmailNameOrAddress EmailSmtpAddress EmailUserName |
Used for entering an email address. Shows a ".com" button and duplicates the @ key from the numbers and symbols page for quick access. Unlike for Url, the @ and ".com" buttons are present on both pages of keys. |
|
NameOrPhoneNumber |
"SMS mode," for entering a recipient of an SMS message. Like the default mode, but the comma key is replaced with an @ key and a semicolon key. (The semicolon is useful for delimiting consecutive names/numbers.) Note that there is a "123" button instead of the usual "&123" button. This brings up a phone-style numeric keypad that only has numbers and a backspace key. |
|
AddressCity AddressCountryName AddressCountryShortName AddressStateOrProvince Date DateDayName DateMonthName PersonalFullName PersonalGivenName PersonalMiddleName PersonalNamePrefix PersonalNameSuffix PersonalSurname Text Chat |
"Capitalized mode." Like the default mode, but with shift depressed to make the first letter capital. The keyboard returns to lowercase after the first letter is typed. |
|
Text Chat |
Like the default mode, but with a bar of text suggestions and an emoticons button that gives access to two pages of common emoticons. (The first page of emoticons is pictured to the right.) It also starts out with shift depressed so the first letter is capitalized. Although one could imagine that Chat mode would use a dictionary with slang and abbreviations (LOL, ROFL, brb,...) whereas Text mode could use a "proper" dictionary, these two modes are actually identical and use the same dictionary. As shown in the picture, this dictionary indeed includes several slang terms and abbreviations that would make your English teacher weep. |
|
Maps ApplicationEnd |
Matches the keyboard used by the Maps app (and Bing app). Adds the text suggestions bar to the default mode, but with the restyled Enter key and no emoticons button. Again, although you can imagine a customized dictionary that only includes terms relevant for a map, this mode uses the same dictionary as every mode with the text suggestions bar. |
|
Search |
Like the default mode, but with a restyled enter key. Oddly, this is not the keyboard used by the Bing app because there are no text suggestions. Instead, the Maps value matches what Bing uses. |
|
Private |
This mode should not be used. It is exactly like the default mode, but with a text suggestions bar that is always empty. |
|
Do not use the Password input scope!
Because this input scope is no different than Default, it does not provide the proper password-entering experience (which shows a dot for each letter). To get this experience, you should use a password box (the PasswordBox control) instead of a text box. Note that password boxes do not support input scopes; you can only get the default on-screen keyboard with them.
How do I make the keyboard show only number keys and nothing else?
You can't. The TelephoneNumber input scope is the closest thing to a pure-number keyboard, but even that has some non-numeric keys. Also, the phone keypad styling is not very desirable for contexts that have nothing to do with a phone number. An app that wants this behavior, such as the Tip Calculator app in Chapter 10, is usually better off creating its own grid of numeric buttons.
How do I restrict what gets typed into a text box (such as only allowing numbers)?
You must write code that manually filters out unwanted characters; input scopes do not help in this regard. For most input scopes, the user can still find a way to type every possible character via the on-screen keyboard. And even when an input scope with a limited on-screen keyboard is used, such as TelephoneNumber, users with a hardware keyboard can still type every character possible! Input scopes are about providing convenience to the user; they are not about restricting or validating input.
Unfortunately, you can't reliably restrict input in all cases. Instead, you can only reliably remove characters after the fact with a TextChanged event handler. The following code should enable the rejection of non-digit keystrokes, but it currently does work due to a bug that causes the pressing of Shift to not be reported:
voidTextBox_KeyDown(objectsender,KeyEventArgse) {switch(e.Key) {caseKey.D0:caseKey.D1:caseKey.D2:caseKey.D3:caseKey.D4:caseKey.D5:caseKey.D6:caseKey.D7:caseKey.D8:caseKey.D9:if((Keyboard.Modifiers &ModifierKeys.Shift) ==ModifierKeys.Shift) {// Shift is reported as being pressed! (This doesn't currently happen// due to a bug.) That means we just caught a !, @, #, $, %, ^, &, *,// (, or ) pretending to be a digit!// This is not allowed. Swallow the keystroke!e.Handled =true; }else{// This is allowed. There's nothing more to do!}break;default:// This is not allowed. Swallow the keystroke!e.Handled =true;break; } }
Can I supply a custom context-specific dictionary for the text suggestions bar?
No. The XAML Editor app in Chapter 11 deals with this limitation by mimicking the text suggestions bar with its own set of words.
The on-screen keyboard has several nice behaviors that you might not be aware of. For example, you can hold down or double-tap the shift key to turn on Caps Lock and tap it later to turn it off. You can also hold down many keys to get alternatives related to that key. Figure 3.2 shows a few examples of this.
)
Figure 3.2 Holding down the ".com" key shows other top-level domains, holding down a vowel shows variations with accents, holding down the dollar sign shows other units of currency, and holding down 1, 2, or 3 shows fractions and exponents.