Virtual keyboard in Windows Store Apps (Metro) via the TouchScreenKeyboard class

(This isn’t a real “question”, as I intend to answer it myself and leave a record for people in need of this.)

How do I use the TouchScreenKeyboard class in Windows Store Apps, in order to show the virtual keyboard on touch devices like Microsoft’s Surface? Furthermore, can I test it if I don’t have a touch device?

Important Update: According to the release notes, Unity 4.5.3 added support for TouchScreenKeyboard.text in Windows Store Apps, and now shows the virtual keyboard without the need to set keyboard.active = true. This essentially makes the following paragraphs and example usage kind of obsolete, as you should now be able to use the virtual keyboard like in other platforms :slight_smile: The testing paragraph at the end is still useful, though.

Note: this is about Windows Store Apps; i.e. Metro apps running in desktop Windows 8 or 8.1. In Windows Phone you should be able to use keyboard.text as normal.


As of Unity 4.5, TouchScreenKeyboard works in Windows Store Apps, making it possible to programatically open the virtual keyboard in Metro without the rather problematic solution of including an overlayed XAML text box.

Contrasting with other platforms, you must set keyboard.active = true after calling TouchScreenKeyboard.Open, or the keyboard will not appear. You also can’t use the usual keyboard.text to set/get the keyboard text. Instead, you must rely on Unity’s Input.inputString, which contains characters written this frame (the backspace key also generates a character, '\b', which you have to detect to delete characters).

The following C# script exemplifies how to use the keyboard in Windows Store Apps. For other platforms (code not included) you should use keyboard.text as normal, and call with an initial text instead of null (I use null because the value is ignored in Metro anyway).

Place this script on an object and drag a TextMesh over the TextObject reference in Unity’s Inspector. Press the GUI’s “Open Keyboard” button to open the keyboard (will only work on touch devices!). It closes when you write with your physical keyboard or touch anywhere outside the virtual keyboard overlay.

using UnityEngine;

public class VirtualKeyboardTester : MonoBehaviour
{
	// drag an object with a TextMesh here, in Unity's inspector
	public TextMesh TextObject;

	private TouchScreenKeyboard keyboard;
	private string text = "Starting text!";

	void OnGUI()
	{
		// "Open" has several arguments. If you want special functionality, see
		// http://docs.unity3d.com/ScriptReference/TouchScreenKeyboard.Open.html

		if (GUI.Button(new Rect(10, 10, 300, 50), "Open Keyboard"))
		{
			if (keyboard == null) {
				keyboard = TouchScreenKeyboard.Open(null);
			}
			keyboard.active = true;
		}
	}

	void Update()
	{
		// for each character inserted this frame
		foreach (char c in Input.inputString)
		{
			if (c == '\b' && text.Length > 0)
			{
				// backspace: remove last char
				text = text.Substring(0, text.Length - 1);
			}
			else if (c == '

’ || c == ‘\r’)
{
// New line (“Enter” was pressed).
// Possibly handle it as “confirm”, or do “text += c” for multiline text.
}
else
{
// add any other char to the string
text += c;
}
}

		TextObject.text = text;
	}
}

If you want to display the text somewhere other than a TextMesh (such as GUI labels), adapt TextObject.text = text. The for cycle should remain in the Update method.

For those that don’t have a Microsoft Surface tablet, beware that the virtual keyboard will only open if Windows recognizes a touch screen (unless I’m mistaken and there are other conditions). This is a problem for people without touch screen devices. However, you can simulate this in Visual Studio by running the app in the Simulator (instead of “Local Machine”) and then selecting “Basic touch mode” in the simulator icons on the right (below “Mouse mode”).