Share via

pesan WM_POINTERUPDATE

  • Artikel

Diposting untuk memberikan pembaruan pada penunjuk yang melakukan kontak melalui area klien jendela atau pada penunjuk yang tidak ditangkap melayang di atas area klien jendela. Saat penunjuk mengarah, pesan menargetkan jendela mana pun yang kebetulan penunjuk berakhir. Saat penunjuk bersentuhan dengan permukaan, penunjuk secara implisit ditangkap ke jendela tempat pointer melakukan kontak dan jendela tersebut terus menerima input untuk pointer sampai putus kontak.

! [Penting]
Aplikasi desktop harus diketahui DPI. Jika aplikasi Anda tidak mengetahui DPI, koordinat layar yang terkandung dalam pesan penunjuk dan struktur terkait mungkin muncul tidak akurat karena virtualisasi DPI. Virtualisasi DPI menyediakan dukungan penskalaan otomatis untuk aplikasi yang tidak diketahui DPI dan aktif secara default (pengguna dapat menonaktifkannya). Untuk informasi selengkapnya, lihat Menulis Aplikasi Win32 DPI Tinggi.

#define WM_POINTERUPDATE              0x0245

Parameter

wParam

Berisi informasi tentang penunjuk. Gunakan makro berikut untuk mengambil informasi dari parameter wParam.

  • GET_POINTERID_WPARAM(wParam): pengidentifikasi penunjuk.

  • IS_POINTER_NEW_WPARAM(wParam): bendera yang menunjukkan apakah pesan ini mewakili input pertama yang dihasilkan oleh pointer baru.

  • IS_POINTER_INRANGE_WPARAM(wParam): bendera yang menunjukkan apakah pesan ini dihasilkan oleh pointer selama masa pakainya. Bendera ini tidak diatur pada pesan yang menunjukkan bahwa penunjuk memiliki rentang deteksi kiri

  • IS_POINTER_INCONTACT_WPARAM(wParam): bendera yang menunjukkan apakah pesan ini dihasilkan oleh penunjuk yang bersentuhan dengan permukaan jendela. Bendera ini tidak diatur pada pesan yang menunjukkan penunjuk melayang.

  • IS_POINTER_PRIMARY_WPARAM(wParam): menunjukkan bahwa pointer ini telah ditetapkan sebagai primer.

  • IS_POINTER_FIRSTBUTTON_WPARAM(wParam): bendera yang menunjukkan apakah ada tindakan utama.

    • Ini dianalogikan dengan tombol kiri mouse ke bawah.
    • Penunjuk sentuh akan memiliki set ini ketika bersentuhan dengan permukaan digitizer.
    • Penunjuk pena akan memiliki set ini ketika bersentuhan dengan permukaan digitizer tanpa tombol yang ditekan.

  • IS_POINTER_SECONDBUTTON_WPARAM(wParam): bendera yang menunjukkan apakah ada tindakan sekunder.

    • Ini dianalogikan dengan tombol kanan mouse ke bawah.
    • Penunjuk pena akan memiliki set ini ketika bersentuhan dengan permukaan digitizer dengan tombol laras pena ditekan.

  • IS_POINTER_THIRDBUTTON_WPARAM(wParam): bendera yang menunjukkan apakah ada satu atau beberapa tindakan tersier berdasarkan jenis pointer; aplikasi yang ingin merespons tindakan tersier harus mengambil informasi khusus untuk jenis pointer untuk menentukan tombol tersier mana yang ditekan. Misalnya, aplikasi dapat menentukan status tombol pena dengan memanggil GetPointerPenInfo dan memeriksa bendera yang menentukan status tombol.

  • IS_POINTER_FOURTHBUTTON_WPARAM(wParam): bendera yang menunjukkan apakah penunjuk yang ditentukan mengambil tindakan keempat. Aplikasi yang ingin merespons tindakan keempat harus mengambil informasi khusus untuk jenis penunjuk untuk menentukan apakah tombol mouse diperluas (XButton1) pertama ditekan.

  • IS_POINTER_FIFTHBUTTON_WPARAM(wParam): bendera yang menunjukkan apakah pointer yang ditentukan mengambil tindakan kelima. Aplikasi yang ingin merespons tindakan kelima harus mengambil informasi khusus untuk jenis penunjuk untuk menentukan apakah tombol mouse diperluas kedua (XButton2) ditekan.

    Lihat Bendera Penunjuk untuk detail selengkapnya.

    Catatan

    Penunjuk mengarahkan kursor tidak memiliki bendera tombol yang diatur. Ini dianalogikan dengan gerakan mouse tanpa tombol mouse ke bawah. Aplikasi dapat menentukan status tombol pena yang mengarahkan kursor, misalnya, dengan memanggil GetPointerPenInfo dan memeriksa bendera yang menentukan status tombol.

lParam

Berisi lokasi titik penunjuk.

Catatan

Karena pointer dapat melakukan kontak dengan perangkat melalui area non-sepele, lokasi titik ini mungkin merupakan penyederhanaan area pointer yang lebih kompleks. Jika memungkinkan, aplikasi harus menggunakan informasi area pointer lengkap alih-alih lokasi titik.

Gunakan makro berikut untuk mengambil koordinat layar fisik titik tersebut.

  • GET_X_LPARAM(lParam): koordinat x (titik horizontal).
  • GET_Y_LPARAM(lParam): koordinat y (titik vertikal).

Nilai hasil

Jika aplikasi memproses pesan ini, aplikasi harus mengembalikan nol.

Jika aplikasi tidak memproses pesan ini, aplikasi harus memanggil DefWindowProc.

Keterangan

Setiap pointer memiliki pengidentifikasi pointer unik selama masa pakainya. Masa pakai pointer dimulai ketika pertama kali terdeteksi.

Pesan WM_POINTERENTER dihasilkan jika penunjuk melayang terdeteksi. Pesan WM_POINTERDOWN diikuti oleh pesan WM_POINTERENTER dihasilkan jika pointer non-hovering terdeteksi.

Selama masa pakainya, pointer dapat menghasilkan serangkaian pesan WM_POINTERUPDATE saat mengarahkan kursor atau kontak.

Masa pakai pointer berakhir ketika tidak lagi terdeteksi. Ini menghasilkan pesan WM_POINTERLEAVE.

Saat penunjuk dibatalkan, POINTER_FLAG_CANCELED diatur.

Pesan WM_POINTERLEAVE juga dapat dihasilkan saat penunjuk yang tidak ditangkap bergerak di luar batas jendela.

Untuk mendapatkan posisi horizontal dan vertikal penunjuk, gunakan yang berikut ini:

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

Makro MAKEPOINTS juga dapat digunakan untuk mengonversi parameter lParam ke struktur POINTS.

Fungsi GetKeyState dapat digunakan untuk menentukan status tombol pengubah keyboard yang terkait dengan pesan ini. Misalnya, untuk mendeteksi bahwa tombol ALT ditekan, periksa apakah GetKeyState (VK_MENU) < 0.

Jika aplikasi tidak memproses pesan ini, DefWindowProc dapat menghasilkan satu atau beberapa pesan WM_GESTURE jika urutan input dari ini dan, mungkin, pointer lain dikenali sebagai gerakan. Jika gerakan tidak dikenali, DefWindowProc dapat menghasilkan input mouse.

Jika aplikasi secara selektif menggunakan beberapa input pointer dan meneruskan sisanya ke DefWindowProc, perilaku yang dihasilkan tidak ditentukan.

Gunakan fungsi GetPointerInfo untuk mengambil informasi lebih lanjut yang terkait dengan pesan ini.

Jika aplikasi tidak memproses pesan-pesan ini secepat yang dihasilkan, beberapa gerakan dapat dikoalesced. Riwayat input yang dikoales ke dalam pesan ini dapat diambil menggunakan fungsi GetPointerInfoHistory.

Contoh

Contoh kode berikut menunjukkan cara menggunakan GET_X_LPARAM, GET_Y_LPARAM, IS_POINTER_FIRSTBUTTON_WPARAM, dan IS_POINTER_SECONDBUTTON_WPARAM untuk mengambil informasi yang relevan dari parameter wParam dan lParam dari pesan WM_POINTERUPDATE.

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
}

Contoh kode berikut menunjukkan cara menggunakan GET_POINTERID_WPARAM untuk mengambil id pointer dari parameter wParam dari pesan WM_POINTERUPDATE .

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
}

Contoh kode berikut menunjukkan cara menangani jenis penunjuk yang berbeda.

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;
}

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung
 Windows 8 [hanya aplikasi desktop]
Server minimum yang didukung
 Windows Server 2012 [hanya aplikasi desktop]
Header
Winuser.h (termasuk Windows.h)

Lihat juga

Pesan

Referensi

Bendera Penunjuk

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