Microsoft

Technical Technical White Paper

Document

Getting Started with Windows

MultiPoint Mouse SDK 1.5
January 10, 2010
 Getting Started with Windows MultiPoint Mouse SDK 1.5 - 2

Legal Information
This document is provided “as-is”. Information and views expressed in this document, including URL and other Internet Web site
references, may change without notice. You bear the risk of using it.

Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or
should be inferred.

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and
use this document for your internal, reference purposes.

© 2009 Microsoft Corporation. All rights reserved.

Microsoft, C#, C++, Expression Blend, MultiPoint, .NET, Visual Basic, Visual Studio, Windows, and Windows Vista are trademarks
of the Microsoft group of companies.

All other trademarks are property of their respective owners.

CONTENTS
Introduction............................................................................................................................................. 3
Getting Started with the SDK .................................................................................................................. 3
Software Requirements ..................................................................................................................... 3
Installing the MultiPoint Mouse SDK .................................................................................................. 4
Referencing the Required Libraries ................................................................................................... 4
Initializing the MultiPoint Mouse SDK ................................................................................................ 4
Running Your Application .................................................................................................................. 5
Handling Mouse Addition and Removal ............................................................................................. 6
Building a MultiPoint Mouse-Enabled UI ................................................................................................ 7
Adding a MultiPoint Control ............................................................................................................... 7
Handling MultiPoint Mouse Clicks ...................................................................................................... 8
Determining Which Mouse Was Clicked ............................................................................................ 9
Customizing MultiPoint Mouse .............................................................................................................. 10
Assigning Pointer Colors ............................................................................................................ 10
Assigning Custom Images .......................................................................................................... 10
Freezing the Mouse Devices ........................................................................................................... 12
Advanced Topics .................................................................................................................................. 12
Excluding Pointers from a Region on the Screen ............................................................................. 12
Assigning Specific Mouse Functions (AKA Teacher Mouse) ............................................................ 12
Appendix A: Usage Scenarios .............................................................................................................. 13
The Map Sample Usage Scenario ................................................................................................... 13
The Quiz Sample Usage Scenario................................................................................................... 15

© 2009 Microsoft Corporation

 Getting Started with Windows MultiPoint Mouse SDK 1.5 - 3

Introduction
The Windows® MultiPoint™ Mouse Software Development Kit (SDK) is a development framework that
allows developers to build applications that enable up to 25 individual mouse devices to work
simultaneously on one computer. As a developer, you can use the MultiPoint Mouse SDK to create
educational applications for schools with limited technological infrastructure, thus increasing the amount
of time any one student can spend on a computer. Initial pilot programs conducted in India by Microsoft®
Research show that for certain subjects, collaborative learning technologies like Windows MultiPoint help
1
enhance learning when compared to a 1:1 computing scenario .
MultiPoint Mouse SDK should not be confused with applications that allow multiple people to control
multiple mouse devices to perform standard operations. In those cases, the system traditionally cannot
identify which mouse has made which changes, and there is normally no option for controlling the
permissions of the various devices. MultiPoint Mouse SDK includes a development framework that
enables developers to build applications to take advantage of multiple mouse devices, including the ability
to handle mouse clicks from different users, independently, and to assign different permissions to each
mouse. For example, the mouse that a teacher uses in a learning application might need additional
permissions to control the activity.
This document will help you get started with the MultiPoint Mouse SDK by providing an overview of such
items as namespaces, classes, useful properties and functions, and by discussing common issues and
considerations for building applications by using MultiPoint Mouse SDK.

Getting Started with the SDK

This section outlines the steps required to get started building applications with the MultiPoint Mouse
SDK. It assumes that the reader is comfortable with building Windows Presentation Foundation (WPF)
applications on Microsoft® .NET Framework and will concentrate only on aspects related to implementing
MultiPoint Mouse functionality. For more information about building applications with WPF, see Appendix
A in this document.

Software Requirements
The recommended programming environment is Microsoft Expression Blend® with Visual Studio 2008 or
Visual Studio 2010. Expression Blend is a graphical user interface (GUI) for designing interfaces. Visual
Studio provides a similar functionality, which, although not as rich in features as Expression Blend, should
be sufficient to develop applications with the MultiPoint Mouse SDK.
The following software is required to run the MultiPoint Mouse SDK:

 A 32-bit or 64-bit version of Windows® 7 operating system is recommended. The MultiPoint

Mouse SDK is compatible with Windows Vista® Service Pack 2 (SP2) and Windows® XP SP3.
 Visual Studio 2008, Visual Studio 2010 Express, or a later version of Visual Studio.

 If you are developing Windows Presentation Foundation applications, you should use Expression
Blend.

Note: The MultiPoint Mouse SDK will install the appropriate template for your version of Visual Studio.

1
The findings of Microsoft Research reports on the effects of collaborative technologies can be found on the MultiPoint Web site at
http://www.microsoft.com/unlimitedpotential/TransformingEducation/MultiPoint.mspx.

© 2009 Microsoft Corporation

 Getting Started with Windows MultiPoint Mouse SDK 1.5 - 4

Note: The MultiPoint Mouse SDK does not support Windows Forms UI development.

Installing the MultiPoint Mouse SDK

After you install the SDK, the Windows MultiPoint Mouse SDK folder appears on the Start menu. The
folder includes the following items:

 Samples Solution, which includes:

o Tic-Tac-Toe: a basic sample that illustrates a two-player game
o Map: a map-based learning sample in which students compete to locate cities as quickly as
possible
o Quiz: a quiz learning sample in which students are allocated a region on the screen where
they have to answer as many questions as possible in a set amount of time
o Control: a MultiPoint Mouse-enabled check box
 SDK documentation: a reference for developing applications by using the SDK

The following additional folders are added to the installation location (by default, C:\Program
Files\Windows Multipoint Mouse SDK):

 Bin: Contains the MultiPoint Mouse DLLs and a MSM merge file for use with MSI-based installers.
 Docs: Contains the MultiPoint Mouse SDK documentation.
 License: Contains license terms for using the SDK.
 Samples: Contains all of the source code for the sample applications and the sample MultiPoint
Mouse control.

Referencing the Required Libraries

To build an application by using the MultiPoint Mouse SDK, your project must reference the following
libraries, which are located in the Global Assembly Cache (GAC):

 Microsoft.Multipoint.Sdk.dll
 Microsoft.Multipoint.Sdk.Controls.dll

For a summary of the libraries and the classes that they contain, including useful methods and properties,
see the Overview of the SDK section below.

Initializing the MultiPoint Mouse SDK

Before an application can accept input from multiple mouse devices, the MultiPoint Mouse SDK must be
initialized. To do this, the application must initialize the MultipointSdk object by associating it with a WPF
window. This is best done as part of the Window.Loaded event of the primary window of your
application, as described in the following procedure.

To initialize the MultiPoint Mouse SDK on an application

1. Declare and set up a Window.Loaded event handler. Because the initialization steps should only be
performed after the window has been loaded, you should include the initialization steps in the
Window.Loaded event handler.
2. Call the Initialize method on the MultipointSdk object, passing in the current window. Behind the
scenes, MultiPoint Mouse DLLs carry out the following steps:

© 2009 Microsoft Corporation

 Getting Started with Windows MultiPoint Mouse SDK 1.5 - 5

a. Registers the current window to specify to the SDK which window to monitor for MultiPoint Mouse
events. Because the SDK needs the information about the parent window that is responsible for
the visuals, you must register the current window before any device visuals are drawn for the
mouse devices.
b. Registers mouse devices. This registration enumerates through all input devices attached to the
computer, and builds a list of registered mouse devices available to the application.

Note: MultiPoint Mouse SDK does not recognize “track pads” on a laptop computer as an input device.
Therefore, you should use the USB mouse device to develop and test applications created by using
MultiPoint Mouse.

c. Draws a mouse device visual for each attached mouse device and assigns a default pointer to
each.
d. Hides the system pointer. In an application created using MultiPoint Mouse SDK, the system
pointer is not used for any of the attached devices, so it is hidden to avoid confusion.

The following code example shows the initialization procedure.

// 1. Set up the Window Loaded Event Handler,

// and Initialize the SDK
private void Window1_Loaded(object sender, EventArgs e)
{
// 2. Initialize the MultiPoint Mouse SDK
MultipointSdk.Instance.Initialize(this);
}

Running Your Application

Run the application and a pointer should appear on the screen for each mouse device connected to the
computer. It might be difficult to exit the application because the mouse devices cannot click on standard
controls, such as the Close button in the top-right corner of a screen. It is a good idea to add a keyboard
event handler that can be used to exit the application when a certain key (for example, the ESC key) is
pressed. Do this by adding a KeyEventHandler declaration in the constructor for the main application
window, as follows:

// Declare KeyEventHandler to handle keyboard events

this.KeyDown += KeyDown_Event;

After adding the KeyEventHandler declaration, create an event handler as follows:

© 2009 Microsoft Corporation

 Getting Started with Windows MultiPoint Mouse SDK 1.5 - 6

// Handle keyboard events

private void KeyDown_Event(object sender, KeyEventArgs e)
{
if (e.Key == Key.Escape)
{
MultipointSdk.Instance.Dispose();
App.Current.Shutdown();
}
}

Handling Mouse Addition and Removal

As part of building an application that allows multiple mouse devices, you should include functionality that
enables devices to be added and removed while the application is running. MultiPoint Mouse SDK
exposes events that are raised when devices are added and removed which can be used to assign
different pointers to each mouse device that is connected.

To handle an addition of a mouse device

1. Declare a handler for the device arrival event. This should be declared when the application is
initialized, either in the constructor or in the Window.Loaded event handler for the main application
window. For example:

MultipointSdk.Instance.DeviceArrivalEvent +=
MultipointDeviceArrivalEvent;

2. Set up the event handler function (as declared in parentheses in the previous code example) to
trigger the following event:

private void MultipointDeviceArrivalEvent(object sender,

DeviceNotifyEventArgs e)
{
// add code to handle the arrival of the device here
}

3. Assign a pointer to the new mouse device. For example:

© 2009 Microsoft Corporation

 Getting Started with Windows MultiPoint Mouse SDK 1.5 - 7

e.DeviceInfo.DeviceVisual.CursorBitmap = bitmap;

To see a complete example of how to manage pointers and assign them to new mouse devices, look at
Microsoft.Multipoint.Sdk.Samples.Common\CursorAssignments.cs.
You can also handle the removal of a mouse device in your code by using the DeviceRemovalEvent
handler. However, the SDK automatically removes the mouse and its associated pointer when the mouse
is disconnected. If you do not need to perform any custom operations when a mouse device is removed
and can safely omit this step.

Building a MultiPoint Mouse-Enabled

UI
MultiPoint Mouse SDK intercepts low-level Windows messages and allows simultaneous use of multiple
mouse devices. This means that most of the standard WPF controls will not respond to mouse devices.
MultiPoint Mouse SDK ships with its own control that should be used to trap mouse events. This section
demonstrates how to use this control to build a MultiPoint Mouse-enabled UI.

Adding a MultiPoint Control

To add a control to the new window that can accept and act on MultiPoint Mouse click events, you will
add a control that implements the IMultipointMouseEvents interface. The
Microsoft.Multipoint.Sdk.Controls namespace provides MultipointButton control to use. By
implementing the IMultipointMouseEvents interface, these controls gain the ability to monitor and
handle events generated by the mouse devices.

To add a MultiPoint Mouse control

1. Import the namespace in your Window1 code below, as follows:

using Microsoft.Multipoint.Sdk.Controls;

2. Add a reference to this namespace in the Window1.xaml file, as follows:

© 2009 Microsoft Corporation

 Getting Started with Windows MultiPoint Mouse SDK 1.5 - 8

<Window
x:Class="MultipointBasicApp.Window1"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:mp="clr-namespace:Microsoft.Multipoint.Sdk.Controls;
assembly=Microsoft.Multipoint.Sdk.Controls"
Title="Window1"
WindowState="Maximized">

Because the system pointer is not completely disabled, but rather just hidden, it is recommended that
you set the WindowState to “Maximized” to prevent the system pointer from being able to
inadvertently click on other windows when it is outside of the application window area.
3. Add a MultipointButton object to the window by adding the following code to the Window1.xaml file:

<Grid>
<mp:MultipointButton
Name="mpButton"
Content="Click Me"
Click="mpButton_Click" />
</Grid>

Handling MultiPoint Mouse Clicks

Now that there is a control (button) capable of handling mouse clicks, you can declare an event handler.

To declare an event handler to handle mouse clicks

1. Declare a click event handler on mpButton by adding the following declaration in the constructor:

// Declare MultiPoint mouse button handler

mpButton.MultipointClick += mpButton_Click;

2. Create the handler as follows:

// Handle Clicks on the mpButton MultiPointButton

private void mpButton_Click(object sender,
RoutedEventArgs e)
{
mpButton.Content = "Click";
}

© 2009 Microsoft Corporation

 Getting Started with Windows MultiPoint Mouse SDK 1.5 - 9

Determining Which Mouse Was Clicked

With MultiPoint Mouse SDK, you can identify the mouse that clicked the button and then display that
mouse pointer‟s ID on the button.

To identify the mouse that clicked the button

1. Get an instance of the button that was clicked.
2. Cast the „sender‟ object to a MultipointButton, as follows:

MultipointButton btn = (MultipointButton)sender;

3. To get information about the mouse device that was clicked, cast the RoutedEventArgs to a
MultipointMouseEventArgs as follows:

MultipointMouseEventArgs multipointargs =
e as MultipointMouseEventArgs;

The as operator is used here to prevent InvalidCastExceptions if the cast fails.

4. Test that multipointargs is not null before performing the required action, as follows:

if (multipointargs != null)
{
// perform required action
}

5. To determine which mouse was clicked, view the Id property in the DeviceInfo object. You can output
this information to the button as follows:

mpButton.Content =
String.Format("Mouse #{0} Clicked me",
multipointargs.DeviceInfo.Id);

© 2009 Microsoft Corporation

 Getting Started with Windows MultiPoint Mouse SDK 1.5 - 10

Customizing MultiPoint Mouse

New mouse devices are allocated the default mouse pointer. This can become confusing because it is
difficult to distinguish between the mouse devices since all their pointers look alike. You can customize
MultiPoint Mouse by assigning your own colors or pointers.

Assigning Pointer Colors

DeviceInfo.DeviceVisual contains the property CursorColor. To set the first mouse‟s pointer to red,
use:

MultipointSdk.Instance.MouseDeviceList[0].DeviceVisual.
CursorColor = Colors.Red;

Assigning Custom Images

It is possible to assign bitmap images to pointers instead of assigning colors.

To assign custom images to mouse pointers

1. Find or create pointer images to use – these can be in .jpg, .gif, or .png format – and add them as
resources to the project.

2. To access these resources as Bitmap objects, import the System.Drawing namespace, as follows:

using System.Drawing;

3. Create a new lookup function called GetCursorImage, passing in the ID. This function returns an
image instead of a color, as follows:

© 2009 Microsoft Corporation

 Getting Started with Windows MultiPoint Mouse SDK 1.5 - 11

private Bitmap GetCursorImage(int id)

{
switch (id)
{
case 0:
return Properties.Resources.boy_01;
case 1:
return Properties.Resources.boy_02;
case 2:
return Properties.Resources.boy_03;
case 3:
return Properties.Resources.boy_04;
default:
return Properties.Resources.boy_05;
}
}

For a complete example, see Microsoft.Multipoint.Sdk.Samples.Common.CursorAssignments.cs.

© 2009 Microsoft Corporation

 Getting Started with Windows MultiPoint Mouse SDK 1.5 - 12

Freezing the Mouse Devices

In some classroom scenarios, the teacher might want to be able to freeze the students‟ mouse pointers;
for example, to get their attention.
To enable this functionality set the DisableMovement property of the MultipointMouseDevice object to
true. To freeze all mouse devices, iterate through the list of devices, freezing each one.

private void FreezeMice()

{
foreach(var deviceInfo in
MultipointSdk.Instance.MouseDeviceList)
{
deviceInfo.DeviceVisual.DisableMovement = true;
}
}

For a complete example, see:

Microsoft.Multipoint.Sdk.Samples.Quiz.Model.PlayerManager.ToggleMiceFrozen.

Advanced Topics
Excluding Pointers from a Region on the Screen
In the Quiz sample, the players are restricted to their own question region on the screen. When a player‟s
mouse attempts to exit this region, it is forced in again by calling the
MultipointMouseDevice.SetPosition method.
For details on this technique, see:
Microsoft.Multipoint.Sdk.Samples.Quiz.Model.PlayerManager.HandleMouseMovement.

Assigning Specific Mouse Functions (AKA Teacher Mouse)

In the Map sample, the teacher‟s mouse has special access to Control Panel; all other mouse devices are
excluded from this area. The teacher‟s mouse is specified by entering a predefined pattern, in this case
an M key press, followed by a right-click within two seconds. A customized pointer is assigned to the
teacher‟s mouse so that it is clearly identifiable. This is just one example of how to use a pattern of clicks
and/or key presses to assign functionality to a specific mouse.
For details on this technique, see:

© 2009 Microsoft Corporation

 Getting Started with Windows MultiPoint Mouse SDK 1.5 - 13

Microsoft.Multipoint.Sdk.Samples.Map.WindowMain.OnKeyDown
Microsoft.Multipoint.Sdk.Samples.Map.WindowMain.OnMultipointMouseDown

Appendix A: Usage Scenarios

This section contains the usage scenarios for the Map sample and the Quiz sample.
We will use the following scenario as the basis for each of the usage scenarios:
Mrs. Adams is a third-grade teacher at an elementary school in an underprivileged area. The school
cannot afford to provide a computer for each child. Mrs. Adams has a classroom of 30 students, each
with a wireless mouse device connected to her computer. Her computer display is projected onto a large
screen at the front of the classroom.

The Map Sample Usage Scenario

Mrs. Adams‟s class is going to engage in an activity based on the Map sample. The objective of the
activity is for students to point to a location on the map when prompted by a question on the screen.
When the sample starts, the options for the activity are loaded and displayed on the right side of the
screen. The first option, Cities Around the World, is loaded automatically, and the first question is
displayed above the map.

Figure 1: The Map Sample

© 2009 Microsoft Corporation

 Getting Started with Windows MultiPoint Mouse SDK 1.5 - 14

Figure 1 shows the prompt “Where is Sydney?” above a map. Three customized pointers that correspond
to three players are visible on the map, and are also shown at the bottom of the screen in the Connected
Players List. The list on the right side displays the available activity options in the sample.
The application waits for each connected player to click the place on the map that matches the prompted
location. Once a player responds, the result is recorded and displayed on the Scoreboard on the left side
of the window. The Scoreboard shows the time it took for the student to choose a spot on the map to
click, and whether the answer was correct (green) or incorrect (red).
Once all of the connected players have responded to the question, a new prompt appears asking for the
location of another city. The process repeats until all locations within the activity are completed. The
teacher can move ahead to the next location at any time by clicking the Next Location button on the
screen. When an activity is finished, the application automatically proceeds to the next activity. Activities
also can be selected by clicking the Next Activity button on the screen.

© 2009 Microsoft Corporation

 Getting Started with Windows MultiPoint Mouse SDK 1.5 - 15

The Quiz Sample Usage Scenario

Mrs. Adams‟s class is going to engage in an activity based on the Quiz sample.
In the Quiz sample, there are four separate player areas on the screen. Each player area displays a
question, and the player must answer the question by clicking one of the answer button.

Figure 2: The Quiz Sample

Each player‟s pointer is bound to its corresponding player region, so a player can answer only the
questions relevant to his or her area. A timer displays a countdown of one minute, and the aim of the
sample is to correctly answer as many questions as possible in one minute.

© 2009 Microsoft Corporation