VKD_Define_Hot

VKD_Define_Hot_Key

include vkd.inc

mov     al, ScanCode
mov     ah, type
mov     ebx, ShiftState
mov     cl, flag
mov     esi, OFFSET32 HotKeyProc
mov     edx, OFFSET32 refdata
mov     edi, max_delay
VxDCall VKD_Define_Hot_Key
jc      errorhandler

Defines a hot-key-notification callback function. Hot keys are detected by ANDing the shift state mask with the global shift state, then comparing the resulting state with the shift state compare value. If this matches and the key code matches, the callback function is called with the specified reference data in EDX. Uses EAX, ESI, and Flags. Clears the carry flag upon success, sets it upon failure.

Returns the definition handle in EAX if successful.

ScanCode

Scan code of the main key.

type

Type of scan code. Can be one of these values:

Value	Meaning
0	Normal code
1	Extended code (ExtendedKey_B)
0FFh	Either normal or extended (AllowExtended_B)

ShiftState

Shift state. The high word is a mask that is ANDed with the global shift state when checking for this hot key. The low word is the masked-shift-state-compare value.

flag

Operation flag. Can be one of these values:

Value	Meaning
CallOnAll	Calls on press, release, and repeats of hot keys.
CallOnComplete	Calls callback when the hot key state is ended (all shift modifier keys are released), or when a different hot key is entered. For example, assume that both ALT+1 and ALT+2 are hot keys. If the user holds the ALT key down, then presses and releases the 1 key and presses the 2 key, the callback for ALT+1 is called even though the ALT key has not been released.
CallOnPress	Calls callback when key press is detected.
CallOnRelease	Calls callback when key release is detected. Keyboard may still be in hot-key hold state.
CallOnRepeat	Calls callback when repeated press is detected.
CallOnUpDwn	Calls on both press and release of hot keys.
Local_Key	Specifies that the key can be locally enabled or disabled.
Monitor_Key	Automatically reflects the hot key. This value can be used only with the CallOnPress, CallOnRelease, and PriorityNotify values.
PriorityNotify	Specifies that the callback can only be called when interrupts are enabled and the critical section is not owned. This value can be combined with any other value in this list.

HotKeyProc

Address of the callback function. For more information about the callback function, see the following comments.

refdata

Address of the reference data to pass to the callback function.

max_delay

Maximum notification delay in milliseconds if the flag specifies the PriorityNotify value. If this parameter is zero, the callback function is always notified.

The callback function is called when a hot key is detected, and detection meets mask requirements. The callback function receives the following input parameters:

AL    ; scan code of key
AH    ; 0 if key just pressed (Hot_Key_Pressed)
      ; 1 if key just released (Hot_Key_Released)
      ; 2 if key is an auto-repeat press (Hot_Key_Repeated)
      ; 3 hot key state ended (Hot_Key_Completed)

EBX   ; hot key handle
ECX   ; global shift state
EDX   ; points to the reference data
EDI   ; elapsed time for delayed notification in milliseconds

The EDI register normally contains zero, but if the PriorityNotify value is specified this value could be larger.

The high bit of AH is set if the hot key is a priority hot key, and the virtual machine which had the keyboard focus at the time the hot key was recognized was suspended or not executable. In this case, the priority event was scheduled for the system virtual machine rather than the keyboard owner. The Hot_Key_SysVM_Notify value can be used to check this bit.

The callback function can modify EAX, EBX, ECX, EDX, ESI, EDI, and Flags