pesan WM_POINTERDOWN

Artikel
06/03/2023

Diposting saat penunjuk melakukan kontak melalui area klien jendela. Pesan input ini menargetkan jendela tempat pointer melakukan kontak, dan pointer secara implisit ditangkap ke jendela sehingga jendela terus menerima input untuk pointer sampai putus kontak.

Jendela menerima pesan ini melalui fungsi WindowProc-nya.

! [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_POINTERDOWN                   0x0246

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

! [Penting]
Ketika jendela kehilangan pengambilan pointer dan menerima pemberitahuan WM_POINTERCAPTURECHANGED , biasanya tidak akan menerima pemberitahuan lebih lanjut. Untuk alasan ini, penting bagi Anda untuk tidak membuat asumsi berdasarkan pemberitahuan WM_POINTERDOWN WM_POINTERUP/ atau WM_POINTERENTER/WM_POINTERLEAVE yang dipasangkan secara merata.

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, penunjuk 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);

Untuk mengonversi parameter lParam ke struktur POINTS), gunakan makro MAKEPOINTS.

Untuk mengambil informasi lebih lanjut yang terkait dengan pesan, gunakan fungsi GetPointerInfo.

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

Perhatikan bahwa 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.

Ketika jendela kehilangan pengambilan pointer dan menerima pemberitahuan WM_POINTERCAPTURECHANGED , jendela biasanya tidak akan menerima pemberitahuan lebih lanjut. Oleh karena itu, penting bahwa jendela tidak membuat asumsi status penunjuknya, terlepas dari apakah menerima pemberitahuan DOWN / UP atau ENTER / LEAVE yang dipasangkan secara merata.

Contoh

Contoh kode berikut menunjukkan cara menggunakan IS_POINTER_FIRSTBUTTON_WPARAM, GET_X_LPARAM, GET_Y_LPARAM, dan IS_POINTER_SECONDBUTTON_WPARAMuntuk mengambil informasi yang relevan yang terkait dengan pesan WM_POINTERDOWN.

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

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

Contoh kode berikut menunjukkan cara menggunakan GET_POINTERID_WPARAM untuk mengambil id pointer dari pesan WM_POINTERDOWN .

POINTER_INFO pointerInfo;
UINT32       pointerId = GET_POINTERID_WPARAM(wParam);

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

Contoh kode berikut menunjukkan cara menangani jenis pointer yang berbeda seperti sentuhan, pena, atau perangkat penunjuk default.

POINTER_TOUCH_INFO   touchInfo;
POINTER_PEN_INFO     penInfo;
POINTER_INFO         pointerInfo;
UINT32               pointerId = GET_POINTERID_WPARAM(wParam);
POINTER_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 = HandleGenericPointerMessage(&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

Bagikan melalui