Getting Started With Windows Multi Point Mouse SDK (1)

Microsoft

Technical

Document

Technical White Paper

Getting Started with Windows MultiPoint Mouse SDK 1.5

January 10, 2010

Getting Started with Windows MultiPoint Mouse SDK 1.5 - 2

© 2009 Microsoft Corporation

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



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 enhance learning when compared to a 1:1 computing scenario

1.

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.

http://www.microsoft.com/unlimitedpotential/TransformingEducation/MultiPoint.mspx



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:



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.

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:

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

// Declare KeyEventHandler to handle keyboard events

this.KeyDown += KeyDown_Event;

// 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);

}



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:

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

trigger the following event:

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

private void MultipointDeviceArrivalEvent(object sender,

DeviceNotifyEventArgs e)

{

// add code to handle the arrival of the device here

}

MultipointSdk.Instance.DeviceArrivalEvent +=

MultipointDeviceArrivalEvent;

// Handle keyboard events

private void KeyDown_Event(object sender, KeyEventArgs e)

{

if (e.Key == Key.Escape)

{

MultipointSdk.Instance.Dispose();

App.Current.Shutdown();

}

}



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:

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

using Microsoft.Multipoint.Sdk.Controls;

e.DeviceInfo.DeviceVisual.CursorBitmap = bitmap;



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:

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:

2. Create the handler as follows:

// Handle Clicks on the mpButton MultiPointButton

private void mpButton_Click(object sender,

RoutedEventArgs e)

{

mpButton.Content = "Click";

}

// Declare MultiPoint mouse button handler

mpButton.MultipointClick += mpButton_Click;

<Grid>

<mp:MultipointButton

Name="mpButton"

Content="Click Me"

Click="mpButton_Click" />

</Grid>

<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">



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:

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

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:

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);

if (multipointargs != null)

{

// perform required action

}

MultipointMouseEventArgs multipointargs =

e as MultipointMouseEventArgs;

MultipointButton btn = (MultipointButton)sender;



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:

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:

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

using System.Drawing;

MultipointSdk.Instance.MouseDeviceList[0].DeviceVisual.

CursorColor = Colors.Red;



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

private Bitmap GetCursorImage(int id)

{

switch (id)

{

case 0:

return Properties.Resources.boy_01;

case 1:


case 2:


case 3:


default:


}

}



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.

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:

private void FreezeMice()

{

foreach(var deviceInfo in

MultipointSdk.Instance.MouseDeviceList)

{

deviceInfo.DeviceVisual.DisableMovement = true;

}

}



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



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.



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.

Documents

Getting Started With Windows Multi Point Mouse SDK (1)