The Windows Mobile 6.5 Gestures API: An Introduction

This article contains a brief look into the new Gestures API that is available for Windows Mobile 6.5 Professional Edition. We will walk through creating a small Smart Device application that is able to read gestures made by the user, and report back information about these gestures to the screen.

Introduction

This article describes a simple application for Windows Mobile 6.5 Professional Edition which is a useful exercise for familiarizing ourselves with the Gestures API that is newly available in Windows Mobile 6.5.

Background

Readers of this article should be somewhat familiar with the basics of Win32 GUI development as well as have a beginner to intermediate familiarity with C/C++. If you do not know what HWND, Window Procedure, or MSG are, then I highly recommend reading through "A Generic Sample Application" found at MSDN under Windows API or better yet, if you can obtain a copy of Programming Windows by Charles Petzold, a good understanding of the first section, labeled "Section I: The Basics" should be sufficient for this exercise. Additionally, you will need Visual Studio 2005 or 2008 Professional Edition, and the Windows Mobile 6.0 and 6.5 SDKs (Professional Edition) installed on your machine in order to build and execute the code. Some familiarity with the Visual Studio environment (creating projects, navigating, adding files, etc...) is also assumed.

Using the Code

First we need to set up our environment. We will be building a simple application and will need to include some files from the Windows Mobile SDK. Open Visual Studio (I am using Visual Studio 2008 Professional, but 2005 Professional should also be fine) and create a new project. Select Visual C++ for the language type, and then select the "Smart Device" project type and the "Win32 Smart Device Project" template.

Give your project a name such as "GesturesTest" or whatever makes you happy.

Click "OK and the Win32 Smart Device Project Wizard will launch. Hit "next" on the "Overview" page. On the platforms page, we need to select the proper SDK that we will be using to develop our application. The Gestures API is only available in Windows Mobile 6.5 Professional, which requires the Windows Mobile 6 Professional SDK (note that the Windows Mobile 6.5 Professional SDK must be installed on your machine, however when selecting our platform, we must use the Windows Mobile 6 Professional SDK). Hit "Next" to continue.

Finally on the "Application Settings" page, for Application type, select "Windows Application". Also, for the sake of keeping this project simple, check the box that reads "Empty project" and make sure the ATL box is unchecked. Click "Finish" to complete the Smart Device Project Wizard.

Now that we have a ready project, we need to add a code file so we can begin writing our application. Right-click on "Source Files" and add a new .cpp file to our project. We also need to add some critical library references to our project. Right click on the project icon and select "Properties". Under "Configuration Properties", "C/C++", "General" add the "Include" directory from the Windows Mobile 6 Professional SDK to the "Additional Include Directories" property. The default path to this is typically "%Program Files%\Windows Mobile 6 SDK\PocketPC\Include\Armv4i".

Finally, we need to explicitly add two .lib files to the project. Under "Linker", "Input", "Additional Dependencies", add references to AygShell.lib and TouchGestureCore.lib. AygShell.lib contains some GUI API code we will be calling in this application. TouchGestureCore.lib contains the code required to execute the Gestures API.

Since we are building a native Windows App, we will need to start with our WinMain function. This article assumes some familiarity with topics such as creating a Windows GUI application using the Win32 API, so we will breeze through this part pretty quickly to get to the meat of this article, which is the Gestures API.

This should be fairly straightforward. We are capturing the various Window Messages that we are interested in for the purposes of this application. Note the WM_GESTURE case. When the application screen is touched, a WM_GESTURE message is generated and sent to the message loop. We'll talk about this more in a bit. You may also wonder what we are doing in the WM_ACTIVATE case. The default behavior for a Windows Mobile application is to remain live but inactive when the user hits the "close" button. We don't require that type of behavior for our little test app, so we are checking for WM_ACTIVATE messages with the WA_INACTIVE flag and simply closing our program when this message is received.

Our next function is the OnCreate function. This will handle any initial construction required for our application. In this case, we will be building a label to display our gesture data, and a (blank) menu bar to replace the thumb buttons.

Now let's build the OnColorStatic function. We'll be using this to set the colors for our label. Note that you can use any colors you like, but for my app I have chosen to use a plain black background and green text.

We have two functions left. First let's look at the simpler of the two, which is GetGestureDirection. This function evaluates whether or not a DWORD value is equivalent to a number of constants which are defined in the header gesture.h. If the DWORD is equal to one of the predefined direction constants, an OUT parameter will contain a string that corresponds to the direction. If the DWORD cannot be matched to an existing constant, the OUT parameter will read "NONE" (note that there is also a defined constant that corresponds to this as well).

All that is left is to write the OnGesture function. This is the more complicated (but not terribly so) of our functions and will require more explaining. It contains all of the actions that take place when a user touches the screen. First let's look at the function prototype:

LRESULT WINAPI OnGesture(HWND hwnd, WPARAM wParam, LPARAM lParam);

Recall that we are calling the OnGesture function from our Window Procedure whenever we receive a WM_GESTURE message. According to MSDN, when WndProc receives a WM_GESTURE message, wParam contains a DWORD that corresponds to the Gesture ID, and lParam contains a handle to a GESTUREINFO structure (which also contains the Gesture ID). The GESTUREINFO structure contains data which we are interested in such as coordinates of the gesture, direction, and velocity. Let's take a look at the function:

Points of Interest

I used MSDN pretty heavily when getting an initial grip on using WM_GESTURE messages. One frustrating point was that the MSDN documentation made no mention of the TouchGestureCore.lib file being required as a project dependency, or even that it exists at all. Fortunately it wasn't so cryptically named that I couldn't find it for myself.

One other item of note was that after playing with the app for a bit, it was easy to see that the Gestures API in Windows Mobile 6.5 supports multi-touch (at least on my HTC Imagio), so it's curious that I have yet to see an app out there that takes advantage of this feature.

Share

About the Author

Software Engineer from Western NC specializing in C#, .Net Framework, Javascript, and C/C++ development. I love solving complex problems and injecting witty sarcasm into the situation. When one gets out of control I apply the other. Currently working as a Software Development Engineer at Microsoft, where I have constructed a test automation harness for Microsoft Fixit products ,a native code application for Windows Mobile Marketplace, a WCF service, an abstraction library for Microsoft Log Parser that allows Log Parser records to be processed with Linq as they are returned, and a Windows Sidebar Gadget.

Comments and Discussions

Hi.Nice example but from my point of view it's too difficult to be used in every project. Isn't it possible nowadays (2011) to do it using for example a Control, event or in any other quick way?I need to create Windows Mobile 6.5 Pro application in VB.NET (VS 2005) and I don't want to write such a huge code just to run this small functionality..

Hi Valenci. Thank you for your kind words. I don't see how this article would be inapplicable, however, to devices that don't support multi-touch. This program works as advertised regardless of whether the hardware supports multi-touch or not. It's an important distinction that the Gestures API has the capability of addressing touch events on multiple threads; of course the hardware must support this first. Unfortunately most Windows Mobile devices don't seem to support multi-touch. My guess would be that most hardware manufacturers have opted to hold off until the release of Windows Mobile 7 before introducing such significant enhancements to the hardware. I'm glad I've received all this feedback though because I am working on a Windows Mobile touch-based game. Had I not known that the Imagio was the exception rather than the rule, I might have tried to incorporate multi-touch.

Also, you mention in your article that gestures support multitouch. As far as I know, Windows Mobile 6.5 does not support multitouch. The only Windows Mobile device which supports multitouch is the HTC HD2 with a capacitive display, and the Multitouch capabilities are added by HTC.

I gave the program a try and it works nicely. I have one concern however. When you double tap, you get a GID_SELECT message first and then GID_DOUBLESELECT, but what if I want to handle both messages differently? Like for example in a game where I want SELECT and DOUBLESELECT to do different things exclusively. I don't want the SELECT code executing when the user DOUBLESELECTs. Is this a valid concern?

This is a behavior of the Gestures API, not my code. In fact the reason I wrote this program was so that I could discover through practice what effect different gestures would have. Excellent point about clicking once leading to a select message even before a doubleselect message occurs. I don't see a lot of touch apps that take advantage of the doubleselect feature, perhaps this is the reason why.

Thank you putting together this little "getting to understand" gestures. I am eager to try it as soon as I have updated my system.

A few hours later ... I realize I don't want to got back to C++ to learn how to use gestures. Any chance you can put together a C# version (given that you're a C# developer yourself)? Alternatively, is there a corresponding example somewhere in the bewildering MSDN site?

There's not a lot of documentation out there on managed versions of the Gestures API. I'll see what I can dig up.

[EDIT - 11/02/2009] Here's an update based on what I have found. Essentially .Net CF (in it's present form at least) doesn't have native support for the Gestures API. Windows Mobile Developer Center has a webcast that describes how to access the API from .Net. It involves overloading the Window Procedure (in C#) in order to launch Gesture Events that correspond to the .Net event driven pattern. I was actually thinking about doing something along these lines myself to get the API into .Net. Now I may not have to, though I haven't watched the webcast, only looked at the code, so I'm not certain about whether or not the source code is under a redistributable license.