WM_POINTERUPDATE訊息

發行項
06/12/2023

張貼以在指標上提供更新，以在視窗的工作區上或將未擷取的指標停留在視窗的工作區上。當指標暫留時，訊息會以指標發生的視窗為目標。當指標與表面接觸時，指標會隱含地擷取至指標所建立的視窗，而該視窗會繼續接收指標的輸入，直到中斷接觸為止。

![重要]
傳統型應用程式應該知道 DPI。如果您的應用程式沒有 DPI 感知，則指標訊息和相關結構中包含的螢幕座標可能會因為 DPI 虛擬化而顯示不正確。 DPI 虛擬化可自動調整支援非 DPI 感知的應用程式，且預設為作用中， (使用者可以將其關閉) 。如需詳細資訊，請參閱撰寫高 DPI Win32 應用程式。

#define WM_POINTERUPDATE              0x0245

參數

wParam

包含指標的相關資訊。使用下列宏從 wParam 參數擷取資訊。

GET_POINTERID_WPARAM (wParam) ：指標識別碼。
IS_POINTER_NEW_WPARAM (wParam) ：指出此訊息是否代表新指標所產生的第一個輸入的旗標。
IS_POINTER_INRANGE_WPARAM (wParam) ：旗標，指出此訊息是否由指標在其存留期間產生。此旗標未在訊息上設定，指出指標具有左側偵測範圍
IS_POINTER_INCONTACT_WPARAM (wParam) ：旗標，指出此訊息是否由與視窗介面接觸的指標產生。這個旗標不會在指出暫留指標的訊息上設定。
IS_POINTER_PRIMARY_WPARAM (wParam) ：表示此指標已指定為主要指標。
IS_POINTER_FIRSTBUTTON_WPARAM (wParam) ：指出是否有主要動作的旗標。
- 這類似于滑鼠左鍵向下鍵。
- 觸控指標在與數位板表面接觸時，將會有此設定。
- 當手寫筆指標與數位板表面接觸且未按下任何按鈕時，就會有此設定。
IS_POINTER_SECONDBUTTON_WPARAM (wParam) ：指出是否有次要動作的旗標。
- 這類似于滑鼠右鍵向下。
- 當手寫筆指標與數位板表面接觸並按下手寫筆筒按鈕時，就會有這個設定。
IS_POINTER_THIRDBUTTON_WPARAM (wParam) ：指出指標類型是否有一或多個第三個動作的旗標;想要回應第三個動作的應用程式必須擷取指標類型特定的資訊，以判斷按下哪三個按鈕。例如，應用程式可以呼叫 GetPointerPenInfo 並檢查指定按鈕狀態的旗標，來判斷手寫筆的按鈕狀態。
IS_POINTER_FOURTHBUTTON_WPARAM (wParam) ：指出指定的指標是否採取第四個動作的旗標。想要回應第四個動作的應用程式必須擷取指標類型特定的資訊，以判斷按下第一個擴充滑鼠 (XButton1) 按鈕。
IS_POINTER_FIFTHBUTTON_WPARAM (wParam) ：指出指定指標是否採取第五個動作的旗標。想要回應第五個動作的應用程式必須擷取指標類型特定的資訊，以判斷是否按下第二個擴充滑鼠 (XButton2) 按鈕。

如需詳細資訊 ，請參閱指標旗標 。

注意

暫留指標未設定任何按鈕旗標。這類似于滑鼠移動，沒有滑鼠按鍵向下移動。應用程式可以藉由呼叫 GetPointerPenInfo 並檢查指定按鈕狀態的旗標，來判斷暫留畫筆的按鈕狀態。

lParam

包含指標的點位置。

注意

因為指標可能會透過非簡單區域與裝置接觸，所以這個點位置可能是更複雜的指標區域簡化。可能的話，應用程式應該使用完整的指標區域資訊，而不是點位置。

使用下列宏來擷取點的實體螢幕座標。

GET_X_LPARAM lParam () ：x (水準點) 座標。
GET_Y_LPARAM (lParam) ：y (垂直點) 座標。

傳回值

如果應用程式處理此訊息，它應該會傳回零。

如果應用程式未處理此訊息，它應該呼叫 DefWindowProc。

備註

每個指標在其存留期內都有唯一的指標識別碼。指標的存留期會在第一次偵測到指標時開始。

如果偵測到暫留指標，就會產生 WM_POINTERENTER 訊息。如果偵測到非暫留指標，就會產生WM_POINTERDOWN訊息，後面接著WM_POINTERENTER訊息。

在存留期間，指標可能會在指標暫留或連絡時產生一系列 WM_POINTERUPDATE 訊息。

指標的存留期會在不再偵測到指標時結束。這會產生 WM_POINTERLEAVE 訊息。

當指標中止時， 會設定POINTER_FLAG_CANCELED 。

當非擷取的指標在視窗界限外移動時，也可能會產生 WM_POINTERLEAVE 訊息。

若要取得指標的水準和垂直位置，請使用下列專案：

xPos = GET_X_LPARAM(lParam); 
yPos = GET_Y_LPARAM(lParam);

MAKEPOINTS宏也可以用來將 lParam 參數轉換成POINTS結構。

GetKeyState函式可用來判斷與此訊息相關聯的鍵盤修飾詞按鍵狀態。例如，若要偵測已按下 ALT 鍵，請檢查 GetKeyState 是否 (VK_MENU) < 0。

如果應用程式未處理此訊息， DefWindowProc 可能會在來自這個的輸入序列以及可能將其他指標辨識為手勢時，產生一或多個 WM_GESTURE 訊息。如果無法辨識手勢， DefWindowProc 可能會產生滑鼠輸入。

如果應用程式選擇性地取用某些指標輸入，並將其餘部分傳遞至 DefWindowProc，則產生的行為未定義。

使用 GetPointerInfo 函式擷取此訊息的相關進一步資訊。

如果應用程式不會儘快處理這些訊息，可能會聯合一些移動。您可以使用 GetPointerInfoHistory 函式來擷取合併至此訊息的輸入歷程記錄。

範例

下列程式碼範例示範如何使用 GET_X_LPARAM、 GET_Y_LPARAM、 IS_POINTER_FIRSTBUTTON_WPARAM和 IS_POINTER_SECONDBUTTON_WPARAM ，從 WM_POINTERUPDATE 訊息的 wParam 和 lParam 參數擷取相關資訊。

int xPos = GET_X_LPARAM(lParam);
int yPos = GET_Y_LPARAM(lParam);

if (IS_POINTER_PRIMARYBUTTON_WPARAM(wParam))
{
    // process pointer move while down, similar to mouse move with left button down
}
else if (IS_POINTER_SECONDARYBUTTON_WPARAM(wParam))
{
    // process pointer move while down, similar to mouse move with right button down
}

下列程式碼範例示範如何使用 GET_POINTERID_WPARAM ，從 WM_POINTERUPDATE 訊息的 wParam 參數擷取指標識別碼。

POINTER_INFO pointerInfo;
UINT32       pointerId = GET_POINTERID_WPARAM(wParam);

// Retrieve common pointer information
if (!GetPointerInfo(pointerId, &amp;pointerInfo))
{
    // failure, call GetLastError()
}
else
{
    // success, process pointerInfo
}

下列程式碼範例示範如何處理不同的指標類型。

POINTER_TOUCH_INFO   touchInfo;
POINTER_PEN_INFO     penInfo;
POINTER_INFO pointerInfo;
UINT32       pointerId = GET_POINTERID_WPARAM(wParam);
POINTER_INPUT_TYPE pointerType = PT_POINTER;

// default to unhandled to enable call to DefWindowProc
fHandled = FALSE;

if (!GetPointerType(pointerId, &pointerType))
{
    // failure, call GetLastError()
    // set PT_POINTER to fall to default case below
    pointerType = PT_POINTER;
}

switch (pointerType)
{
case PT_TOUCH:
    // Retrieve touch information
    if (!GetPointerTouchInfo(pointerId, &touchInfo))
    {
        // failure, call GetLastError()
    }
    else
    {
        // success, process touchInfo
        // mark as handled to skip call to DefWindowProc
        fHandled = TRUE;
    }
    break;
case PT_PEN:
    // Retrieve pen information
    if (!GetPointerPenInfo(pointerId, &penInfo))
    {
        // failure, call GetLastError()
    }
    else
    {
        // success, process penInfo
        // mark as handled to skip call to DefWindowProc
        fHandled = TRUE;
    }
    break;
default:
    if (!GetPointerInfo(pointerId, &pointerInfo)) 
    {
        // failure.
    } 
    else 
    {
        // success, proceed with pointerInfo.
        fHandled = HandleGenericPointerInfo(&pointerInfo);
    }
    break;
}

規格需求

需求	值
最低支援的用戶端	Windows 8 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2012 [僅限傳統型應用程式]
標頭	Winuser.h (包含 Windows.h)

另請參閱

訊息
參考
指標旗標
GET_POINTERID_WPARAM
IS_POINTER_NEW_WPARAM
IS_POINTER_INRANGE_WPARAM
IS_POINTER_INCONTACT_WPARAM
IS_POINTER_PRIMARY_WPARAM
IS_POINTER_FIRSTBUTTON_WPARAM
IS_POINTER_SECONDBUTTON_WPARAM
IS_POINTER_THIRDBUTTON_WPARAM
IS_POINTER_FOURTHBUTTON_WPARAM
IS_POINTER_FIFTHBUTTON_WPARAM

WM_POINTERUPDATE訊息

參數

傳回值

備註

範例

規格需求

另請參閱

意見反應

意見反應

其他資源