Table of Contents

Class GlobalKeyboardHook

Namespace
VisioForge.Core.UI.WinForms.Dialogs
Assembly
VisioForge.Core.dll

Provides system-wide keyboard hook functionality using Windows Low-Level Keyboard Hook API. Enables monitoring of global keyboard events across all applications with optional key filtering. This class implements a low-level keyboard hook that captures keyboard events before they reach the target application.

public class GlobalKeyboardHook : IDisposable

Inheritance

Implements

Inherited Members

Remarks

This class uses Windows API SetWindowsHookEx with WH_KEYBOARD_LL to install a low-level keyboard hook. The hook procedure receives keyboard events system-wide and can optionally filter specific keys. Proper disposal is critical to ensure the hook is removed when no longer needed.

Constructors

GlobalKeyboardHook(Keys[])

Initializes a new instance of the VisioForge.Core.UI.WinForms.Dialogs.GlobalKeyboardHook class. Sets up the low-level keyboard hook and loads the required User32 library.

public GlobalKeyboardHook(Keys[] registeredKeys = null)

Parameters

registeredKeys Keys[]

Array of keys that should trigger the KeyboardPressed event. Pass null to capture all keyboard events system-wide.

Remarks

This constructor performs the following operations:

  1. Loads User32.dll library for Windows API access
  2. Installs a low-level keyboard hook using SetWindowsHookEx
  3. Stores the hook procedure delegate to prevent garbage collection The hook remains active until the object is disposed.

Exceptions

Win32Exception

Thrown when User32.dll cannot be loaded or the keyboard hook cannot be installed.

Fields

LlkhfAltdown

The LLKHF altdown.

public const int LlkhfAltdown = 32

Field Value

int

WH_KEYBOARD_LL

The wh keyboard ll.

public const int WH_KEYBOARD_LL = 13

Field Value

int

Properties

RegisteredKeys

Gets the array of keys that are registered for event notification. When null, all keyboard events are captured. When specified, only events for these keys trigger the KeyboardPressed event.

public Keys[] RegisteredKeys { get; }

Property Value

Keys[]

Methods

Dispose(bool)

Releases unmanaged and - optionally - managed resources.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

true to release both managed and unmanaged resources; false to release only unmanaged resources.

Dispose()

Disposes this instance.

public void Dispose()

~GlobalKeyboardHook()

Finalizes an instance of the VisioForge.Core.UI.WinForms.Dialogs.GlobalKeyboardHook class.

protected ~GlobalKeyboardHook()

LowLevelKeyboardProc(int, nint, nint)

Low-level keyboard hook procedure that processes keyboard events from the Windows hook system. This method is called by Windows for each keyboard event when the hook is active.

public nint LowLevelKeyboardProc(int nCode, nint wParam, nint lParam)

Parameters

nCode int

Hook code that determines how to process the message. If less than zero, the hook procedure must pass the message to CallNextHookEx without further processing.

wParam nint

Identifier of the keyboard message (WM_KEYDOWN, WM_KEYUP, WM_SYSKEYDOWN, WM_SYSKEYUP).

lParam nint

Pointer to a KBDLLHOOKSTRUCT structure containing keyboard input information.

Returns

nint

If the event should be suppressed, returns 1. Otherwise, returns the result of CallNextHookEx to allow the event to continue through the hook chain.

Remarks

This method:

  1. Extracts keyboard event data from the lParam structure
  2. Checks if the key matches the registered keys filter
  3. Determines modifier key states (Ctrl, Shift)
  4. Raises the KeyboardPressed event if criteria are met
  5. Suppresses the event if the event handler sets Handled = true

KeyboardPressed

Occurs when a registered keyboard key is pressed or released. This event is triggered for key events that match the registered keys filter, or for all keys if no filter is specified in the constructor.

public event EventHandler<GlobalKeyboardHookEventArgs> KeyboardPressed

Event Type

EventHandler<GlobalKeyboardHookEventArgs>

Remarks

The event provides detailed information about the key event including:

  • Key code and state (pressed/released)
  • Hardware scan code and timing information
  • Modifier key states (Ctrl, Shift)
  • Ability to suppress the key event by setting Handled = true