Quickstart: Identifying pointer devices (XAML)
This Quickstart walks you through identifying the input devices that are connected to your users' systems. We'll also show how to retrieve the capabilities and attributes of each device that affect how a user can interact with your application.
Roadmap: How does this topic relate to others? See:
- Roadmap for Windows Runtime apps using C# or Visual Basic
- Roadmap for Windows Runtime apps using C++
Objective: To learn how to identify connected input devices and their capabilities.
Prerequisites
We assume that you can create a basic Windows Runtime app using C++, C#, or Visual Basic.
To complete this tutorial, you need to:
- Install Windows 8
- Install Microsoft Visual Studio.
- Get a developer license. For instructions, see Develop using Visual Studio 2013.
- Create your first Windows Runtime app using C++, C#, or Visual Basic.
- Review Adding controls and content (Windows Runtime apps using C#/VB/C++ and XAML) to learn about Windows Runtime app using C++, C#, or Visual Basic objects and controls.
Instructions
1. Retrieve mouse properties
The Windows.Devices.Input namespace contains the MouseCapabilities class that is used to retrieve the properties exposed by one or more connected mice. Just create a new MouseCapabilities object and get the properties you're interested in.
Note The values returned by the properties discussed here are based on all the mice connected: Boolean properties return non-zero if at least one mouse supports a specific capability, and numeric properties return the maximum value exposed by any one mouse.
The following code uses a series of TextBlock elements to display the individual mouse properties and values.
private void GetMouseProperties()
{
MouseCapabilities mouseCapabilities = new Windows.Devices.Input.MouseCapabilities();
MousePresent.Text = mouseCapabilities.MousePresent != 0 ? "Yes" : "No";
VertWheel.Text = mouseCapabilities.VerticalWheelPresent != 0 ? "Yes" : "No";
HorzWheel.Text = mouseCapabilities.HorizontalWheelPresent != 0 ? "Yes" : "No";
SwappedButtons.Text = mouseCapabilities.SwapButtons != 0 ? "Yes" : "No";
NumButtons.Text = mouseCapabilities.NumberOfButtons.ToString();
}
2. Retrieve keyboard properties
The Windows.Devices.Input namespace contains the KeyboardCapabilities class that is used to retrieve whether a keyboard is connected. Just create a new KeyboardCapabilities object and get the KeyboardPresent property.
The following code uses a TextBlock element to display the keyboard property and value.
private void GetKeyboardProperties()
{
KeyboardCapabilities keyboardCapabilities = new Windows.Devices.Input.KeyboardCapabilities();
KeyboardPresent.Text = keyboardCapabilities.KeyboardPresent != 0 ? "Yes" : "No";
}
3. Retrieve touch properties
The Windows.Devices.Input namespace contains the TouchCapabilities class that is used to retrieve whether any touch digitizers are connected. Just create a new TouchCapabilities object and get the properties you're interested in.
Note The values returned by the properties discussed here are based on all the touch digitizers connected: Boolean properties return non-zero if at least one digitizer supports a specific capability, and numeric properties return the maximum value exposed by any one digitizer.
The following code uses a series of TextBlock elements to display the touch properties and values.
private void GetTouchProperties()
{
TouchCapabilities touchCapabilities = new Windows.Devices.Input.TouchCapabilities();
TouchPresent.Text = touchCapabilities.TouchPresent != 0 ? "Yes" : "No";
Contacts.Text = touchCapabilities.Contacts.ToString();
}
4. Retrieve pointer properties
The Windows.Devices.Input namespace contains the PointerDevice class that is used to retrieve whether any devices are connected that support pointer input (touch, pen, or mouse). Just create a new PointerDevice object and get the properties you're interested in.
Note The values returned by the properties discussed here are based on all the pointer devices connected: Boolean properties return non-zero if at least one device supports a specific capability, and numeric properties return the maximum value exposed by any one pointer device.
The following code uses a table to display the properties and values for each pointer device.
private void GetPointerDevices()
{
IReadOnlyList<PointerDevice> pointerDevices = Windows.Devices.Input.PointerDevice.GetPointerDevices();
int gridRow = 0;
int gridColumn = 0;
for (int i = 0; i < pointerDevices.Count; i++)
{
// Pointer device type.
TextBlock textBlock1 = new TextBlock();
Grid_PointerProps.Children.Add(textBlock1);
textBlock1.Text = (i + 1).ToString() + " Pointer Device Type:";
Grid.SetRow(textBlock1, gridRow);
Grid.SetColumn(textBlock1, gridColumn);
TextBlock textBlock2 = new TextBlock();
textBlock2.Text = pointerDevices[i].PointerDeviceType.ToString();
Grid_PointerProps.Children.Add(textBlock2);
Grid.SetRow(textBlock2, gridRow++);
Grid.SetColumn(textBlock2, gridColumn + 1);
// Is external?
TextBlock textBlock3 = new TextBlock();
Grid_PointerProps.Children.Add(textBlock3);
textBlock3.Text = (i + 1).ToString() + " Is External?";
Grid.SetRow(textBlock3, gridRow);
Grid.SetColumn(textBlock3, gridColumn);
TextBlock textBlock4 = new TextBlock();
Grid_PointerProps.Children.Add(textBlock4);
textBlock4.Text = pointerDevices[i].IsIntegrated.ToString();
Grid.SetRow(textBlock4, gridRow++);
Grid.SetColumn(textBlock4, gridColumn + 1);
// Maximum contacts.
TextBlock textBlock5 = new TextBlock();
Grid_PointerProps.Children.Add(textBlock5);
textBlock5.Text = (i + 1).ToString() + " Max Contacts:";
Grid.SetRow(textBlock5, gridRow);
Grid.SetColumn(textBlock5, gridColumn);
TextBlock textBlock6 = new TextBlock();
Grid_PointerProps.Children.Add(textBlock6);
textBlock6.Text = pointerDevices[i].MaxContacts.ToString();
Grid.SetRow(textBlock6, gridRow++);
Grid.SetColumn(textBlock6, gridColumn + 1);
// Physical device rectangle.
TextBlock textBlock7 = new TextBlock();
Grid_PointerProps.Children.Add(textBlock7);
textBlock7.Text = (i + 1).ToString() + " Physical Device Rect:";
Grid.SetRow(textBlock7, gridRow);
Grid.SetColumn(textBlock7, gridColumn);
TextBlock textBlock8 = new TextBlock();
Grid_PointerProps.Children.Add(textBlock8);
textBlock8.Text = pointerDevices[i].PhysicalDeviceRect.X.ToString() + "," +
pointerDevices[i].PhysicalDeviceRect.Y.ToString() + "," +
pointerDevices[i].PhysicalDeviceRect.Width.ToString() + "," +
pointerDevices[i].PhysicalDeviceRect.Height.ToString();
Grid.SetRow(textBlock8, gridRow++);
Grid.SetColumn(textBlock8, gridColumn + 1);
// Screen rectangle.
TextBlock textBlock9 = new TextBlock();
Grid_PointerProps.Children.Add(textBlock9);
textBlock9.Text = (i + 1).ToString() + " Screen Rect:";
Grid.SetRow(textBlock9, gridRow);
Grid.SetColumn(textBlock9, gridColumn);
TextBlock textBlock10 = new TextBlock();
Grid_PointerProps.Children.Add(textBlock10);
textBlock10.Text = pointerDevices[i].ScreenRect.X.ToString() + "," +
pointerDevices[i].ScreenRect.Y.ToString() + "," +
pointerDevices[i].ScreenRect.Width.ToString() + "," +
pointerDevices[i].ScreenRect.Height.ToString();
Grid.SetRow(textBlock10, gridRow++);
Grid.SetColumn(textBlock10, gridColumn + 1);
gridColumn += 2;
gridRow = 0;
}
For the complete example, see Input: Device capabilities sample.
Summary
In this Quickstart, you created a series of basic functions that identify the input devices and their properties that are available to your app.
Related topics
Roadmap for Windows Runtime apps using C# or Visual Basic
Reference
Samples