SetGestureConfig function

Configures the messages that are sent from a window for Windows Touch gestures.

Syntax


BOOL WINAPI SetGestureConfig(
  _In_  HWND hwnd,
  _In_  DWORD dwReserved,
  _In_  UINT cIDs,
  _In_  PGESTURECONFIG pGestureConfig,
  _In_  UINT cbSize
);

Parameters

hwnd [in]

A handle to the window to set the gesture configuration on.

dwReserved [in]

This value is reserved and must be set to 0.

cIDs [in]

A count of the gesture configuration structures that are being passed.

pGestureConfig [in]

An array of gesture configuration structures that specify the gesture configuration.

cbSize [in]

The size of the gesture configuration (GESTURECONFIG) structure.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, use the GetLastError function.

Remarks

If you don't expect to change the gesture configuration, call SetGestureConfig at window creation time. If you want to dynamically change the gesture configuration, call SetGestureConfig in response to WM_GESTURENOTIFY messages.

The following table shows the identifiers for gestures that are supported by the dwID member of the GESTURECONFIG structure. Note that setting dwID to 0 indicates that global gesture configuration flags are set.

NameValueDescription
GID_ZOOM3Configuration settings for the zoom gesture.
GID_PAN4The pan gesture.
GID_ROTATE5The rotation gesture.
GID_TWOFINGERTAP6The two-finger tap gesture.
GID_PRESSANDTAP7The press and tap gesture.

 

The following flags are used when dwID is set to zero.

NameValueDescription
GC_ALLGESTURES0x00000001All of the gestures.

 

The following flags are used when dwID is set to GID_ZOOM.

NameValueDescription
GC_ZOOM0x00000001The zoom gesture.

 

The following flags are used when dwID is set to GID_PAN.

NameValueDescription
GC_PAN0x00000001All pan gestures.
GC_PAN_WITH_SINGLE_FINGER_VERTICALLY0x00000002Vertical pans with one finger.
GC_PAN_WITH_SINGLE_FINGER_HORIZONTALLY0x00000004Horizontal pans with one finger.
GC_PAN_WITH_GUTTER0x00000008Panning with a gutter boundary around the edges of pannable region. The gutter boundary limits perpendicular movement to a primary direction until a threshold is reached to break out of the gutter.
GC_PAN_WITH_INTERTIA0x00000010Panning with inertia to smoothly slow when pan gestures stop.

 

Note   Pan gestures can be used in conjunction with each other to control behavior. For example, setting the dwWant bits to panning with single-finger horizontal and setting the dwBlock bits to single-finger vertical will restrict panning to horizontal pans. Changing the dwWant bit to have GC_PAN_WITH_SINGLE_FINGER_VERTICALLY | GC_PAN_WITH_SINGLE_FINGER_HORIZONTALLY and removing single-finger vertical pan from the dwBlock bit will enable both vertical and horizontal panning.

Note   By default, panning has inertia enabled.

Note   A single call to SetGestureConfig cannot include other GIDs along with 0.

The following flags are used when dwID is set to GID_ROTATE.

NameValueDescription
GC_ROTATE0x00000001The rotation gesture.

 

The following flags are used when dwID is set to GID_TWOFINGERTAP.

NameValueDescription
GC_TWOFINGERTAP0x00000001The two-finger tap gesture.

 

The following flags are used when dwID is set to GID_PRESSANDTAP.

NameValueDescription
GC_PRESSANDTAP0x00000001The press and tap gesture.

 

Note   Calling SetGestureConfig will change the gesture configuration for the lifetime of the Window, not just for the next gesture.

Examples

The following example shows how you could receive horizontal and vertical single-finger panning with no gutter and no inertia. This is a typical configuration for a 2-D navigation application such as the Microsoft PixelSense Globe application.


// set up our want / block settings
DWORD dwPanWant  = GC_PAN_WITH_SINGLE_FINGER_VERTICALLY | GC_PAN_WITH_SINGLE_FINGER_HORIZONTALLY;
DWORD dwPanBlock = GC_PAN_WITH_GUTTER | GC_PAN_WITH_INERTIA;

// set the settings in the gesture configuration
GESTURECONFIG gc[] = {{ GID_ZOOM, GC_ZOOM, 0 },
                      { GID_ROTATE, GC_ROTATE, 0},
                      { GID_PAN, dwPanWant , dwPanBlock}                     
                     };    
                     
UINT uiGcs = 3;
BOOL bResult = SetGestureConfig(hWnd, 0, uiGcs, gc, sizeof(GESTURECONFIG));  

if (!bResult){                
    DWORD err = GetLastError();                                       
}


The following example shows how to receive single-finger pan gestures and disable gutter panning. This is a typical configuration for applications that scroll text such as Notepad.

Note   You should explicitly set all the flags that you want enabled or disabled when controlling single-finger panning.


// set up our want / block settings
DWORD dwPanWant  = GC_PAN | GC_PAN_WITH_SINGLE_FINGER_VERTICALLY;                    
DWORD dwPanBlock = GC_PAN_WITH_GUTTER;    

// set the settings in the gesture configuration
GESTURECONFIG gc[] = {{ GID_ZOOM, GC_ZOOM, 0 },
                      { GID_ROTATE, GC_ROTATE, 0},
                      { GID_PAN, dwPanWant , dwPanBlock}                     
                     };    
                     
UINT uiGcs = 3;
BOOL bResult = SetGestureConfig(hWnd, 0, uiGcs, gc, sizeof(GESTURECONFIG));  

if (!bResult){                
    DWORD err = GetLastError();                                       
}   


The following example shows how you can disable all gestures.


// set the settings in the gesture configuration
GESTURECONFIG gc[] = {0,0,GC_ALLGESTURES};
                     
UINT uiGcs = 1;
BOOL bResult = SetGestureConfig(hWnd, 0, uiGcs, gc, sizeof(GESTURECONFIG));  

if (!bResult){                
    DWORD err = GetLastError();                                       
}


The following example shows how you could enable all gestures.


GESTURECONFIG gc = {0,GC_ALLGESTURES,0};

UINT uiGcs = 1;

BOOL bResult = SetGestureConfig(hWnd, 0, uiGcs, &gc, sizeof(GESTURECONFIG));  

if (!bResult){                
    DWORD err = GetLastError();                                       
}              


The following example shows how you could enable all Windows 7 gestures.


// set the settings in the gesture configuration
GESTURECONFIG gc[] = {{ GID_ZOOM, GC_ZOOM, 0 },
                      { GID_ROTATE, GC_ROTATE, 0},
                      { GID_PAN, GC_PAN , 0},
                      { GID_TWOFINGERTAP, GC_TWOFINGERTAP , 0},
                      { GID_PRESSANDTAP, GC_PRESSANDTAP , 0}
                     };    
                     
UINT uiGcs = 5;
BOOL bResult = SetGestureConfig(hWnd, 0, uiGcs, gc, sizeof(GESTURECONFIG));  

if (!bResult){                
    DWORD err = GetLastError();                                       
}


The following example configuration would set the parent window to enable support for zoom, horizontal pan, and vertical pan while the child window would just support horizontal pan.


// set up our want / block settings for a parent window
DWORD dwPanWant  = GC_PAN_WITH_SINGLE_FINGER_VERTICALLY | GC_PAN_WITH_SINGLE_FINGER_HORIZONTALLY;
DWORD dwPanBlock = GC_PAN_WITH_GUTTER | GC_PAN_WITH_INERTIA;

// set the settings in the gesture configuration
GESTURECONFIG gcParent[] = {{ GID_ZOOM, GC_ZOOM, 0 },
                            { GID_PAN, dwPanWant , dwPanBlock}                         
                           };    

// Set the pan settings for a child window
dwPanWant  = GC_PAN_WITH_SINGLE_FINGER_HORIZONTALLY;
dwPanBlock = GC_PAN_WITH_SINGLE_FINGER_VERTICALLY | GC_PAN_WITH_GUTTER | GC_PAN_WITH_INERTIA;
                     
GESTURECONFIG gcChild[]  = {{ GID_ZOOM, 0, GC_ZOOM },
                            { GID_PAN, dwPanWant , dwPanBlock}                         
                           };    

UINT uiGcs   = 2;
BOOL bResult = FALSE;
                     
if (isParent){      
  bResult = SetGestureConfig(hWnd, 0, uiGcs, gcParent, sizeof(GESTURECONFIG));  
}else{
  bResult = SetGestureConfig(hWnd, 0, uiGcs, gcChild, sizeof(GESTURECONFIG));  
}

if (!bResult){                
    DWORD err = GetLastError();                                       
}


Requirements

Minimum supported client

Windows 7 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]

Header

Winuser.h (include Windows.h)

Library

User32.lib

DLL

User32.dll

See also

Functions
GetGestureConfig
GESTURECONFIG
WM_GESTURENOTIFY
Programming Guide for Gestures

 

 

Community Additions

ADD
Show:
© 2014 Microsoft