Fungsi RegisterHotKey (winuser.h)

Artikel
07/16/2024

Mendefinisikan kunci panas di seluruh sistem.

Sintaksis

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, pesan WM_HOTKEY 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 Komentar 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	Arti
MOD_ALT 0x0001	Salah satu kunci ALT harus ditahan.
MOD_CONTROL 0x0002	Salah satu kunci CTRL harus ditahan.
MOD_NOREPEAT 0x4000	Mengubah perilaku hotkey 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 harus ditahan. Kunci ini diberi label dengan logo Windows. Pintasan keyboard yang melibatkan tombol WINDOWS dicadangkan untuk digunakan oleh sistem operasi.

[in] vk

Jenis: UINT

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

Mengembalikan nilai

Jenis: BOOL

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

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

Fungsi ini gagal jika Anda mencoba mengaitkan kunci panas dengan jendela yang dibuat oleh utas lain.

Biasanya, RegisterHotKey juga gagal jika penekanan tombol yang ditentukan untuk kunci panas telah didaftarkan untuk kunci panas lain. Namun, beberapa hotkey default yang sudah ada sebelumnya yang didaftarkan oleh OS (seperti PrintScreen, yang meluncurkan alat Snipping) dapat ditimpa oleh pendaftaran kunci panas lain ketika salah satu jendela aplikasi berada di latar depan.

Komentar

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 hot key tidak dikaitkan dengan jendela, maka pesan WM_HOTKEY diposting ke utas yang terkait dengan hot key.

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

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.

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

Contoh

Contoh berikut menunjukkan cara menggunakan fungsi RegisterHotKey dengan bendera MOD_NOREPEAT.

Dalam contoh ini, hotkey '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

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

Lihat juga

GlobalAddAtom

Input Keyboard

Daftarkan hotkey untuk aplikasi saat ini (CSRegisterHotkey)

Daftarkan hotkey untuk aplikasi saat ini (CppRegisterHotkey)

UnregisterHotKey

WM_HOTKEY

Bagikan melalui