Tap-and-Hold Confirmation in eMbedded Visual Basic

Microsoft Corporation

June 2002

Summary: In the new Pocket PC 2002, you'll find improved support for tap-and-hold with a confirmation during the operation. This article provides sample code you can use to offer native support for tap-and-hold in your Microsoft eMbedded Visual Basic applications. (4 printed pages)

Applies to:
   Microsoft eMbedded Visual Basic®
   Microsoft eMbedded Visual Tools
   MessageCE control from IntelProg, Inc. The demo version of the control is fully functional, except for the nagging message you get every time you use the control
   Download 812-CF-DEV.zip)

Gotchas

The MessageCE control requires the atlce300.dll to be registered on your device. On some devices as well as the emulator, the required atlce300.dll is not in ROM, so you may need to install this file using Control Manager or by registering it manually. The atlce300.dll is located in your Microsoft® Windows® CE Tools directory (C:\Windows CE Tools\wce300\MS Pocket PC\atl\lib).

Contents

Tap-And-Hold Confirmation
Tap-And-Hold Confirmation Sample
Code Walkthrough
Conclusion

Tap-And-Hold Confirmation

On the new Pocket PC 2002 devices, you will get a confirmation during a tap-and-hold operation. This is a very nice way of showing the user that your application is aware of what is going on. However, there is no native support for tap-and-hold confirmations when you're using Microsoft eMbedded Visual Basic®. You have to add this support yourself.

First of all, you need to capture the window's messages sent to each control (most importantly the WM_LBUTTONDOWN message). You can do this by using a third-party control like MessageCE. For details on using this control, please see my article Capture Windows Messages Using the MessageCE Control. Then, you need to use the Windows CE API SHRecognizeGesture. This API will take care of showing the confirmation (a circle of small red circles appearing clockwise during the tap-and-hold operation), and also return a result code indicating whether the user held the stylus down long enough.

In the below sample, I've used the most common use of tap-and-hold operations—to show pop-up menus. For details on creating pop-up menus, please see my article Tap-and-Hold Pop-Up Menus in eMbedded Visual Basic.

Tap-And-Hold Confirmation Sample

To show you how it works, I have created a simple form, as shown in Figure 1, using eMbedded Visual Basic.

Figure 1. Tap-and-hold confirmation

You can see that I've selected some text in the first TextBox control and then I've held the stylus down for some time on that text. The confirmation animation starts and when it's complete a pop-up menu appears, as shown in Figure 2.

Figure 2. Context sensitive pop-up menu

The pop-up menu includes edit menu options (Cut, Copy, Paste, and so on) and all available options are fully functional. You can cut or copy some text from the first TextBox control to the second. For more details on creating edit menus, please see my article Create Edit Menus in eMbedded Visual Basic.

When I do a tap-and-hold operation on the ListView control, the confirmation is the same, but now I get another pop-up menu, as shown in Figure 3.

Figure 3. Tap-and-hold confirmation and pop-up menu in ListView

This pop-up menu is different because ListView controls normally has options to manipulate the rows.

Code Walkthrough

Let's look at the core of the tap-and-hold confirmation code. As I mentioned, you need to declare the SHRecognizeGesture API:

Public Declare Function SHRecognizeGesture Lib "aygshell" (ByVal SHRGINFO As String) As Long

You also need some API constants declared:

Public Const SHRG_RETURNCMD = &H1
Public Const GN_CONTEXTMENU = 1000

And here is the function to capture a tap-and-hold action:

Public Function IsContextMenuGesture(ByVal hWnd As Long, ByVal X As 
Single, ByVal Y As Single) As Boolean

  Dim lsSHRGINFO As String
  
  lsSHRGINFO = LongToBytes(20) & LongToBytes(hWnd) & _
               LongToBytes(X) & LongToBytes(Y) & _
               LongToBytes(SHRG_RETURNCMD)

  IsContextMenuGesture = (GN_CONTEXTMENU = _
                         SHRecognizeGesture(lsSHRGINFO))

End Function

You can see that I'm emulating a SHRGINFO structure by adding the member values to a string. The SHRGINFO structure looks like this:

typedef struct tagSHRGI {
  DWORD cbSize;
  HWND hwndClient;
  POINT ptDown;
  DWORD dwFlags;
} SHRGINFO, *PSHRGINFO;

And in the emulated structure (the string, for example) I set the window's handle and coordinates to the corresponding members of the structure. The SHRG_RETURNCMD value of the dwFlags member tell the API to return a GN_CONTEXTMENU value if the user holds the stylus down long enough.

Most of the other code in the sample is discussed in my other articles mentioned above.

Conclusion

Making use of tap-and-hold in your eMbedded Visual Basic applications will improve the user experience. It will also make your applications work and look more like other Pocket PC 2002 applications. With the sample code provided in this article, you have most of what you need to get going!