SHRecognizeGesture

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function is used to recognize the stylus tap-and-hold gesture and the Action button press-and-hold gesture.

Syntax

WINSHELLAPI DWORD SHRecognizeGesture(
  SHRGINFO * shrg
);

Parameters

• shrg
  [in] Pointer to a SHRGINFO structure.

Return Value

If a context menu gesture was recognized, a WM_CONTEXTMENU message will be sent to shrg->hwndClient and propagated up the parent chain if not handled. In addition, one of the following actions will be taken based on the value of shrg->dwFlags:

• If shrg->dwFlags is SHRG_RETURNCMD, the function will return GN_CONTEXTMENU notification message. If an application uses this flag, it should be aware that bringing up context menus in direct response to the return value makes those menus inaccessible to hardware navigation. To enable hardware navigation, the application should do context menu handling in response to WM_CONTEXTMENU (see Remarks section below).
• If shrg->dwFlags is SHRG_NOTIFYPARENT, a WM_NOTIFY message with GN_CONTEXTMENU set will be sent to the parent of shrg->hwndClient. The function will return the return value that came from processing the WM_NOTIFY message.
• If shrg->dwFlags is SHRG_LONGDELAY, a WM_NOTIFY message with GN_CONTEXTMENU set will be sent to shrg->hwndClient, and the function will return the return value that came from processing the WM_NOTIFY message.

This function returns 0 if there was no context menu gesture.

Remarks

The only gesture currently supported is for context menus, where a context menu gesture is defined as a user tapping on the screen and holding the stylus in the same spot for some amount of time, or the user pressing and holding the action button for some amount of time. This amount of time can be controlled by the OEM through a registry setting.

Typically, a control will call this function during the WM_LBUTTONDOWN processing (for tap and hold recognition) or during the WM_KEYDOWN processing (for action press and hold recognition). If a gesture is recognized messages are sent to the application as specified in the Return Values section, and it is the responsibility of the application to bring up the context menu in response to the messages sent.

Applications should do context menu handling in response to WM_CONTEXTMENU whenever possible to ensure proper hardware navigation behavior. The GN_CONTEXTMENU notification should be used by the application only when the extra information provided by this message is needed.

If you do not want to provide the standard animation feedback for a tap-and-hold gesture, set the SHRG_NOANIMATION flag when calling the SHRecognizeGesture function. The following code example shows this setting.

case WM_LBUTTONDOWN:
{
  SHRGINFO    shrg;
  HMENU       hmenu;
  shrg.cbSize = sizeof(shrg);
  shrg.hwndClient = hWnd;
  shrg.ptDown.x = LOWORD(lParam);
  shrg.ptDown.y = HIWORD(lParam);
  shrg.dwFlags = SHRG_RETURNCMD
SHRG_NOANIMATION;
  if (SHRecognizeGesture(&shrg) == GN_CONTEXTMENU) {
    hmenu = GetSubMenu(g_hMainMenu, 0);
    TrackPopupMenuEx(hmenu,
                     TPM_LEFTALIGN,
                     LOWORD(lParam),
                     HIWORD(lParam),
                     hWnd,
                     NULL);
  }
  break;
}

Requirements