HotKeyManager, ver. 1.6.0

[Properties] [Methods] [Events] [Static Methods]
[Hints] [Known Bugs] [Comments]

HotKeyManager is a component that allows you to add system-wide hotkeys to your application.

A hotkey in Windows is a key combination which invokes a specific action. You can often use Ctrl+S from an application to save a file. However, a system-wide hotkey allows your app. to invoke a custom action from anywhere. Your app. doesn't have to be in the foreground or even visible.

Properties

No properties.

Methods

AddHotKey	function AddHotKey(HotKey: Cardinal): Word; Registers a hotkey with a specific key combination. NOTE: A return value of 0 means the specified key combination is already in use.	Returns an index or 0 if error
ChangeHotKey	function ChangeHotKey(Index: Word; NewHotKey: Cardinal): Word; Changes a hotkey to a new key combination. Provide the index received from AddHotKey as parameter. NOTE: This method returns a new index. The old index is no longer valid.	Returns an index or 0 if error
RemoveHotKey	function RemoveHotKey(HotKey: Cardinal): Boolean; Unregisters a hotkey by its key combination.	Returns true or false
RemoveHotKeyByIndex	function RemoveHotKeyByIndex(Index: Word): Boolean; Unregisters a hotkey by the index previously received from AddHotKey or ChangeHotKey.	Returns true or false
ClearHotKeys	procedure ClearHotKeys; Unregisters all registered hotkeys.

Events

OnHotKeyPressed

type TOnHotKeyPressed = procedure(HotKey: Cardinal; Index: Word) of object;
Fired when then user presses one of the registered hotkeys. The event method provides the key combination that was pressed and the index the hotkey is registered under (the index is previously received from AddHotKey or ChangeHotKey).

Static Methods

HotKeyAvailable	function HotKeyAvailable(HotKey: Cardinal): Boolean; Tests if the specified key combination is available for registration by your app. (or any other app.).	Returns true or false
GetHotKey	function GetHotKey(Modifiers, Key: Word): Cardinal; Returns the key combination resulting from the specified modifiers (a combination of Shift, Ctrl, Alt, Win, or none of them) and the key (A, for instance). USAGE: The modifiers can be a combination of MOD_SHIFT, MOD_ALT, MOD_CONTROL, and MOD_WIN. The key is a virtual keycode. For alphanumeric chars you can get their virtual keycode by using the Ord method on the capitalized char - eg. Ord('G') corresponds to the virtual keycode for the letter 'G'. For any other chars, you should use the appropriate ASCII code or VK_xxx constant (found in windows.pas). Alternatively, use the TextToHotKey method. EXAMPLE 1: `hk := GetHotKey(MOD_CONTROL + MOD_SHIFT, Ord('G'));` EXAMPLE 2: `hk := GetHotKey(MOD_ALT + MOD_SHIFT, VK_HOME);`	Returns 0 if error
SeparateHotKey	procedure SeparateHotKey(HotKey: Cardinal; var Modifiers, Key: Word); Splits a key combination into a key (A, for instance) and its modifiers (shift, ctrl, alt, win).
HotKeyToText	function HotKeyToText(HotKey: Cardinal; Localized: Boolean): String; Returns the specified key combination in a string. USAGE: If Localized is true the result is a string in the user's currently active language, otherwise the result is in US English. Unless you have a good reason you should always present key combinations in the local language (Localized=True), as this is less confusing for the user (who otherwise may have difficulties identifying the correct keys). If the active language is US English there is no difference between the localized and the non-localized result.	Returns an empty string if error
TextToHotKey	function TextToHotKey(Text: String; Localized: Boolean): Cardinal; Returns a key combination from the specified string. USAGE: If Localized is true it means Text is in the user's currently active language, otherwise Text is in US English. You must use '+' as separator. You can use extra spaces if you like. The method is case insensitive. The order of the modifiers doesn't matter. EXAMPLE 1: `hk := TextToHotKey('Ctrl+Alt+Num 3', True);` EXAMPLE 2: `hk := TextToHotKey('alt + ctrl + num 3', True); // The same`	Returns 0 if error

Hints

What is a good key combination?
Avoid simple key combinations that are likely to be used by applications. For instance, if you define the hotkey 'Ctrl+S' it means that applications that normally use Ctrl+S will NOT be notified the user pressed that key combination.

How do I test if a key combination contains the Ctrl modifier (like in Ctrl+Alt+X)?
You can use SeparateHotKey, then test the returned Modifier variable, like so:

  SeparateHotKey(HotKey, Modifiers, Key);        // Return HotKey var in Modifiers and Key
  CtrlFound  := (Modifiers and MOD_CONTROL) <> 0;
  AltFound   := (Modifiers and MOD_ALT) <> 0;
  ShiftFound := (Modifiers and MOD_SHIFT) <> 0;
  WinFound   := (Modifiers and MOD_WIN) <> 0;    // Special Windows modifier key

Can I use the Win modifier key (found on Windows-certified keyboards)?
Yes, although the modifier should be considered reserved for Windows itself. Be aware that the THotKey control which comes with Delphi does not support the Win modifier key. Use either the GetHotKey or the TextToHotKey method (see examples above).
Can I use non-standard keys, like the e-mail application key on my extended keyboard?
Not as far as I know.
Can I use HotKeyManager in a DLL?
Yes, the component registers the hotkeys using indexes that are system-wide unique, ensuring no conflicts with other system-wide hotkeys.
Tell me more about hotkeys?
See API documentation on RegisterHotKey, UnregisterHotKey, and WM_HOTKEY.

Known Bugs

It's not really a bug, just the way Windows works: Some key combinations can be registered, but can't be invoked. You should avoid Num Lock, Caps Lock, Scroll Lock, Pause, and Print Screen - especially in combination with the Ctrl modifier.

Comments

HotKeyManager is freeware. Feel free to use and improve it, but please include all original files if you redistribute the zip-file. If you have any comments or corrections I would very much like to hear them.

Get the latest version from http://www3.brinkster.com/troels/delphi.asp.

Troels Jakobsen
delphiuser@get2net.dk