SetGestureConfig 함수(winuser.h)

아티클
08/28/2023

Windows Touch 제스처에 대한 창에서 전송되는 메시지를 구성합니다.

구문

BOOL SetGestureConfig(
  [in] HWND           hwnd,
  [in] DWORD          dwReserved,
  [in] UINT           cIDs,
  [in] PGESTURECONFIG pGestureConfig,
  [in] UINT           cbSize
);

매개 변수

[in] hwnd

제스처 구성을 설정할 창에 대한 핸들입니다.

[in] dwReserved

이 값은 예약되어 있으며 0으로 설정해야 합니다.

[in] cIDs

전달되는 제스처 구성 구조의 수입니다.

[in] pGestureConfig

제스처 구성을 지정하는 제스처 구성 구조의 배열입니다.

[in] cbSize

제스처 구성(GESTURECONFIG) 구조체의 크기입니다.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 얻으려면 GetLastError 함수를 사용합니다.

설명

제스처 구성을 변경할 필요가 없는 경우 창 생성 시 SetGestureConfig 를 호출합니다. 제스처 구성을 동적으로 변경하려면 WM_GESTURENOTIFY 메시지에 대한 응답으로 SetGestureConfig를 호출합니다.

다음 표에서는 GESTURECONFIG 구조체의 dwID 멤버에서 지원하는 제스처의 식별자를 보여 줍니다. dwID를 0으로 설정한다는 것은 전역 제스처 구성 플래그가 설정되었음을 나타냅니다.

Name	값	Description
GID_ZOOM	3	확대/축소 제스처에 대한 구성 설정입니다.
GID_PAN	4	팬 제스처입니다.
GID_ROTATE	5	회전 제스처입니다.
GID_TWOFINGERTAP	6	두 손가락 탭 제스처입니다.
GID_PRESSANDTAP	7	누른 다음 제스처를 탭합니다.

dwID가 0으로 설정된 경우 다음 플래그가 사용됩니다.

Name	값	설명
GC_ALLGESTURES	0x00000001	모든 제스처.

dwID가 GID_ZOOM 설정된 경우 다음 플래그가 사용됩니다.

Name	값	설명
GC_ZOOM	0x00000001	확대/축소 제스처입니다.

dwID가 GID_PAN 설정된 경우 다음 플래그가 사용됩니다.

Name	값	설명
GC_PAN	0x00000001	모든 팬 제스처.
GC_PAN_WITH_SINGLE_FINGER_VERTICALLY	0x00000002	한 손가락으로 세로 이동
GC_PAN_WITH_SINGLE_FINGER_HORIZONTALLY	0x00000004	한 손가락으로 가로 이동
GC_PAN_WITH_GUTTER	0x00000008	이동 가능한 영역의 가장자리 주위에 배수로 경계가 있는 이동 배수로 경계는 배수로에서 벗어나기 위해 임계값에 도달할 때까지 수직 이동을 기본 방향으로 제한합니다.
GC_PAN_WITH_INTERTIA	0x00000010	이동 제스처가 중지될 때 원활히 느려지도록 관성으로 이동

참고 이동 제스처는 동작을 제어하기 위해 서로 함께 사용할 수 있습니다. 예를 들어 dwWant 비트를 한 손가락 가로로 이동하도록 설정하고 dwBlock 비트를 한 손가락 세로로 설정하면 이동이 가로 팬으로 제한됩니다. dwWant 비트를 포함 GC_PAN_WITH_SINGLE_FINGER_VERTICALLY | GC_PAN_WITH_SINGLE_FINGER_HORIZONTALLY 하도록 변경하고 dwBlock 비트에서 한 손가락 세로 창을 제거하면 세로 및 가로 이동이 모두 가능합니다.

참고 기본적으로 이동에는 관성 사용이 사용됩니다.

참고SetGestureConfig 에 대한 단일 호출은 0과 함께 다른 GID를 포함할 수 없습니다.

dwID가 GID_ROTATE 설정된 경우 다음 플래그가 사용됩니다.

Name	값	Description
GC_ROTATE	0x00000001	회전 제스처입니다.

dwID가 GID_TWOFINGERTAP 설정된 경우 다음 플래그가 사용됩니다.

Name	값	Description
GC_TWOFINGERTAP	0x00000001	두 손가락 탭 제스처입니다.

dwID가 GID_PRESSANDTAP 설정된 경우 다음 플래그가 사용됩니다.

Name	값	Description
GC_PRESSANDTAP	0x00000001	누른 다음 제스처를 탭합니다.

참고SetGestureConfig 를 호출하면 다음 제스처뿐만 아니라 창의 수명 동안 제스처 구성이 변경됩니다.

예제

다음 예제에서는 여백이 없고 관성 없이 가로 및 세로 한 손가락 이동이 수신될 수 있는 방법을 보여줍니다. 이는 Microsoft PixelSense Globe 애플리케이션과 같은 2D 탐색 애플리케이션에 대한 일반적인 구성입니다.

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

다음 예제에서는 한 손가락 팬 제스처를 수신하고 여백 이동 기능을 사용하지 않도록 설정하는 방법을 보여 줍니다. 메모장과 같은 텍스트를 스크롤하는 애플리케이션에 대한 일반적인 구성입니다.

참고 한 손가락 이동 제어 시 사용하거나 사용하지 않도록 설정하려는 모든 플래그를 명시적으로 설정해야 합니다.

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

다음 예제에서는 모든 제스처를 사용하지 않도록 설정하는 방법을 보여 줍니다.

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

다음 예제에서는 모든 제스처를 사용하도록 설정하는 방법을 보여 줍니다.

GESTURECONFIG gc = {0,GC_ALLGESTURES,0};

UINT uiGcs = 1;

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

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

다음 예제에서는 모든 Windows 7 제스처를 사용하도록 설정하는 방법을 보여 줍니다.

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

다음 예제 구성에서는 자식 창이 가로 팬만 지원하는 동안 확대/축소, 가로 팬 및 세로 창을 지원하도록 부모 창을 설정합니다.

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

요구 사항


지원되는 최소 클라이언트	Windows 7 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 R2 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	winuser.h(Windows.h 포함)
라이브러리	User32.lib
DLL	User32.dll