Quickstart: Identifying pointer devices (HTML)

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.

In Windows 8, a pointer device refers to a class of device that provides mouse, pen/stylus, or touch functionality.

In this context, the following devices are supported:

Objective: To learn how to identify connected input devices and their capabilities.

Prerequisites

We assume that you can create a basic Windows Store app using JavaScript that uses the Windows Library for JavaScript template.

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 Store app using JavaScript.
• Review Quickstart: Adding WinJS controls and styles to learn about WinJS 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 true 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 div elements to display the individual mouse properties and values.

function getMouseProperties() {
  var mouseCapabilities = new Windows.Devices.Input.MouseCapabilities();
  id("mousePresent").innerHTML = (mouseCapabilities.mousePresent == true ? "True" : "False");
  id("verticalWheelPresent").innerHTML = (mouseCapabilities.verticalWheelPresent == true ? "True" : "False");
  id("horizontalWheelPresent").innerHTML = (mouseCapabilities.horizontalWheelPresent == true ? "True" : "False");
  id("swapButtons").innerHTML = (mouseCapabilities.swapButtons == true ? "True" : "False");
  id("numberOfButtons").innerHTML = mouseCapabilities.numberOfButtons;
}

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 div element to display the keyboard property and value.

function getKeyboardProperties() {
  var keyboardCapabilities = new Windows.Devices.Input.KeyboardCapabilities();
  id("keyboardPresent").innerHTML = (keyboardCapabilities.keyboardPresent == true ? "True" : "False");
}

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 true 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 div elements to display the touch properties and values.

function getTouchProperties() {
  var touchCapabilities = new Windows.Devices.Input.TouchCapabilities();
  id("touchPresent").innerHTML = (touchCapabilities.touchPresent == true ? "True" : "False");
  id("contacts").innerHTML = touchCapabilities.contacts;
}

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 true 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.

function getPointerDeviceProperties() 
{
  var pointerDevices = Windows.Devices.Input.PointerDevice.getPointerDevices();
  var htmlWrite = "";
  for (i = 0; i < pointerDevices.size; i++) 
  {
    var displayIndex = i + 1;
    htmlWrite += "<tr><td>(" + displayIndex + ") Pointer Device Type</td>  <td>" + 
      getPointerDeviceType(pointerDevices[i].pointerDeviceType) + "</td></tr>";
    htmlWrite += "<tr><td>(" + displayIndex + ") Is External</td><td>" + 
      (pointerDevices[i].isIntegrated == true ? "False" : "True") + "</td></tr>";
    htmlWrite += "<tr><td>(" + displayIndex + ") Max Contacts</td><td>" + 
      pointerDevices[i].maxContacts + "</td></tr>";
    htmlWrite += "<tr><td>(" + displayIndex + ") Physical Device Rect</td><td>" +
      pointerDevices[i].physicalDeviceRect.x + "," +
      pointerDevices[i].physicalDeviceRect.y + "," +
      pointerDevices[i].physicalDeviceRect.width + "," +
      pointerDevices[i].physicalDeviceRect.height + "</td></tr>";
    htmlWrite += "<tr><td>(" + displayIndex + ") Screen Rect</td><td>" +
      pointerDevices[i].screenRect.x + "," +
      pointerDevices[i].screenRect.y + "," +
      pointerDevices[i].screenRect.width + "," +
      pointerDevices[i].screenRect.height + "</td></tr>";
  }
  id("pointerDevices").innerHTML = htmlWrite;
}

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

Conceptual

Responding to user interaction

Developing Windows Store apps (JavaScript and HTML)

Touch interaction design

Reference

Windows.Devices.Input

Samples (DOM)

HTML scrolling, panning and zooming sample

Input: DOM pointer event handling sample

Input: Instantiable gestures sample

Samples (Windows Store app APIs)

Input: Device capabilities sample