Fungsi RegisterHotKey (winuser.h)

Artikel
08/27/2023

Mendefinisikan kunci panas di seluruh sistem.

Sintaks

BOOL RegisterHotKey(
  [in, optional] HWND hWnd,
  [in]           int  id,
  [in]           UINT fsModifiers,
  [in]           UINT vk
);

Parameter

[in, optional] hWnd

Jenis: HWND

Handel ke jendela yang akan menerima pesan WM_HOTKEY yang dihasilkan oleh kunci panas. Jika parameter ini NULL, WM_HOTKEY pesan diposting ke antrean pesan utas panggilan dan harus diproses dalam perulangan pesan.

[in] id

Jenis: int

Pengidentifikasi kunci panas. Jika parameter hWnd ADALAH NULL, maka kunci panas dikaitkan dengan utas saat ini daripada dengan jendela tertentu. Jika hot key sudah ada dengan parameter hWnd dan id yang sama, lihat Keterangan untuk tindakan yang diambil.

[in] fsModifiers

Jenis: UINT

Tombol yang harus ditekan dalam kombinasi dengan kunci yang ditentukan oleh parameter vk untuk menghasilkan pesan WM_HOTKEY . Parameter fsModifiers dapat menjadi kombinasi dari nilai berikut.

Nilai	Makna
MOD_ALT 0x0001	Salah satu kunci ALT harus ditahan.
MOD_CONTROL 0x0002	Salah satu tombol CTRL harus ditahan.
MOD_NOREPEAT 0x4000	Mengubah perilaku tombol pintas sehingga pengulangan otomatis keyboard tidak menghasilkan beberapa pemberitahuan hotkey. Windows Vista: Bendera ini tidak didukung.
MOD_SHIFT 0x0004	Salah satu tombol SHIFT harus ditahan.
MOD_WIN 0x0008	Salah satu kunci WINDOWS ditahan. Kunci ini diberi label dengan logo Windows. Pintasan keyboard yang melibatkan tombol WINDOWS disediakan untuk digunakan oleh sistem operasi.

[in] vk

Jenis: UINT

Kode kunci virtual dari kunci panas. Lihat Kode Kunci Virtual.

Nilai kembali

Jenis: BOOL

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Ketika tombol ditekan, sistem mencari kecocokan terhadap semua tombol panas. Setelah menemukan kecocokan, sistem memposting pesan WM_HOTKEY ke antrean pesan jendela tempat kunci panas dikaitkan. Jika kunci panas tidak terkait dengan jendela, maka pesan WM_HOTKEY diposting ke utas yang terkait dengan kunci panas.

Fungsi ini tidak dapat mengaitkan kunci panas dengan jendela yang dibuat oleh utas lain.

RegisterHotKey gagal jika penekanan tombol yang ditentukan untuk hot key telah didaftarkan oleh hot key lain.

Jika hot key sudah ada dengan parameter hWnd dan id yang sama, kunci tersebut dipertahankan bersama dengan hot key baru. Aplikasi harus secara eksplisit memanggil UnregisterHotKey untuk membatalkan pendaftaran kunci panas lama.

Windows Server 2003: Jika hot key sudah ada dengan parameter hWnd dan id yang sama, itu digantikan oleh hot key baru.

Kunci F12 dicadangkan untuk digunakan oleh debugger setiap saat, sehingga tidak boleh didaftarkan sebagai kunci panas. Bahkan ketika Anda tidak men-debug aplikasi, F12 dicadangkan jika debugger mode kernel atau debugger just-in-time adalah residen.

Aplikasi harus menentukan nilai id dalam rentang 0x0000 melalui 0xBFFF. DLL bersama harus menentukan nilai dalam rentang 0xC000 melalui 0xFFFF (rentang yang dikembalikan oleh fungsi GlobalAddAtom ). Untuk menghindari konflik dengan pengidentifikasi hot-key yang ditentukan oleh DLL bersama lainnya, DLL harus menggunakan fungsi GlobalAddAtom untuk mendapatkan pengidentifikasi hot-key.

Contoh

Contoh berikut menunjukkan cara menggunakan fungsi RegisterHotKey dengan bendera MOD_NOREPEAT . Dalam contoh ini, tombol pintas 'ALT+b' terdaftar untuk utas utama. Ketika hotkey ditekan, utas akan menerima pesan WM_HOTKEY , yang akan diambil dalam panggilan GetMessage . Karena contoh ini menggunakan MOD_ALT dengan nilai MOD_NOREPEAT untuk fsModifiers, utas hanya akan menerima pesan WM_HOTKEY lain ketika tombol 'b' dirilis dan kemudian ditekan lagi saat tombol 'ALT' sedang ditekan.


#include "stdafx.h"

int _cdecl _tmain (
    int argc, 
    TCHAR *argv[])
{           
    if (RegisterHotKey(
        NULL,
        1,
        MOD_ALT | MOD_NOREPEAT,
        0x42))  //0x42 is 'b'
    {
        _tprintf(_T("Hotkey 'ALT+b' registered, using MOD_NOREPEAT flag\n"));
    }
 
    MSG msg = {0};
    while (GetMessage(&msg, NULL, 0, 0) != 0)
    {
        if (msg.message == WM_HOTKEY)
        {
            _tprintf(_T("WM_HOTKEY received\n"));            
        }
    } 
 
    return 0;
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	winuser.h (termasuk Windows.h)
Pustaka	User32.lib
DLL	User32.dll