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) 結構。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請使用 GetLastError 函式。

備註

如果您不預期變更手勢設定，請在建立時段時呼叫 SetGestureConfig 。如果您想要動態變更手勢設定，請呼叫 SetGestureConfig 以回應 WM_GESTURENOTIFY 訊息。

下表顯示GESTURECONFIG結構的dwID成員所支援的手勢識別碼。請注意，將 dwID 設定為 0 表示已設定全域手勢設定旗標。

名稱	值	描述
GID_ZOOM	3	縮放手勢的組態設定。
GID_PAN	4	移動流覽手勢。
GID_ROTATE	5	旋轉手勢。
GID_TWOFINGERTAP	6	雙指點選手勢。
GID_PRESSANDTAP	7	按下並點選手勢。

當 dwID 設定為零時，會使用下列旗標。

名稱	值	描述
GC_ALLGESTURES	0x00000001	所有手勢。

當 dwID設定為 GID_ZOOM 時，會使用下列旗標。

名稱	值	描述
GC_ZOOM	0x00000001	縮放手勢。

當 dwID 設定為 GID_PAN 時，會使用下列旗標。

名稱	值	描述
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的單一呼叫不能包含其他 GID 以及 0。

當 dwID設定為 GID_ROTATE 時，會使用下列旗標。

名稱	值	描述
GC_ROTATE	0x00000001	旋轉手勢。

當 dwID設定為GID_TWOFINGERTAP時，會使用下列旗標。

名稱	值	描述
GC_TWOFINGERTAP	0x00000001	雙指點選手勢。

當 dwID 設定為 GID_PRESSANDTAP時，會使用下列旗標。

名稱	值	描述
GC_PRESSANDTAP	0x00000001	按下並點選手勢。

注意呼叫 SetGestureConfig 將會變更 Window 存留期的手勢設定，而不只是下一個手勢。

範例

下列範例示範如何接收水準和垂直單指移動流覽，且沒有通配線和無慣性。這是 2D 導覽應用程式的一般設定，例如 Microsoft PixelSense Globe 應用程式。

// 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