Hot Keys

To use:

import xp

Keystrokes that can be managed by others. These are lower-level than window keyboard handlers.

If you have a sniffer and a hot key, the sniffer is called first (even if it is an “after” sniffer) and if it consumes the key, the hot key will not be called.

registerHotKey(vKey, flags, description="", hotKey, refCon=None)
Parameters

  • vKey (int) – one of Virtual Key Codes

  • flags (int) – bitwise OR of XPLMKeyFlags

  • description (str) – text descript of your key, viewable by getHotKeyInfo().

  • hotKey (Callable) – Function called on keypress.

  • refCon (Any) – Reference constant passed to your hotKey function

Returns

XPLMHotKeyID capsule

Register a hotkey.

vKey (Virtual Key Codes) is the hot key to be pressed to activate (this may be changed later by your plugin, or some other plugin, using setHotKeyCombination()).

flags are bitwise OR’d values for Shift / Ctrl to be pressed with the hot key. Note you need to include xp.DownFlag or xp.UpFlag. (XPLMKeyFlags)

Include a description for the hot key, so others (using getHotKeyInfo()) can understand the intent of your hot key.

Your hotKey callback receives only the refCon.

Registration returns a hotKeyID, which is what you’ll use with unregisterHotKey().

During execution, the actual key associated with your hot key may change, but you are insulated from this.

Official SDK XPLMRegisterHotKey

>>> def MyHotKey(refCon):
...     xp.speakString("You pressed the Hot Key")
...
>>> hotKeyID = xp.registerHotKey(xp.VK_Z, xp.DownFlag, "Speak Hotkey Example", MyHotKey)
>>>
>>> xp.unregisterHotKey(hotKeyID)
unregisterHotKey(hotKeyID)
Parameters

hotKeyID (XPLMHotKeyID) – value received from registerHotKey().

Returns

None

Unregister a hotkey. Raises RuntimeError if hotkey is not registered/found.

Only your own hotkeys can be unregistered (even though you can get hotKeyIDs of other Hot Keys using getNthHotKey().)

Official SDK XPLMUnregisterHotKey

countHotKeys()
Returns

integer

Return number of hotkeys defined in the whole sim – not just those you defined. When a hot key is unregistered, it will reduce the count.

Official SDK XPLMUnregisterHotKey

getNthHotKey(index)
Parameters

index (int) – 0-based index

Returns

XPLMHotKeyID capsule of nth hotkey in the whole sim.

Returns HotKeyID of Nth hotkey (0-based indexing).

>>> xp.countHotKeys()
1
>>> hotKeyID = xp.getNthHotKey(0)

Official SDK XPLMGetNthHotKey

getHotKeyInfo(hotKeyID)
Parameters

hotKeyID (XPLMHotKeyID) – HotKey to look up.

Returns

HotKeyInfo instance, or ValueError if not found.

Return information about the hotkey as a HotKeyInfo object with attributes:

description: str
virtualKey: int (Virtual Key Codes)
flags: int (XPLMKeyFlags)
plugin: int (XPLMPluginID)
>>> info = xp.getHotKeyInfo(xp.getNthHotKey(0))
>>> info.description
"Speak Hotkey Example"
>>> info.virtualKey
90
>>> info.flags
0
>>> info.plugin
3

Official SDK XPLMGetHotKeyInfo

Note

All python-based hotkeys report the XPPython3 plugin ID: there is a convoluted way (from python) to determine which python plugin created a hotkey, but non-python plugins will always see all python hot keys as originating with the XPPython3 plugin.

setHotKeyCombination(hotKeyID, vKey, flags)
Parameters

  • hotKeyID (XPLMHotKeyID) – hot key to change

  • vKey (int) –

  • flags (inf) – new key and flags to replace original definition from registerHotKey()

Remap a hot key’s keystroke.

hotKeyID can be either one returned from registerHotKey(), or found using getNthHotKey().

Set vKey and flags as you would with registerHotKey().

You may remap another plugin’s keystrokes. For example, to change the first hot key to the same key, but requiring a Shift:

>>> hotKeyID = xp.getNthHotKey(0)
>>> info = xp.getHotKeyInfo(hotKeyID)
>>> xp.setHotKeyCombination(hotKeyID, info.virtualKey, flags=info.flags | xp.ShiftFlag)

Official SDK XPLMGetHotKeyInfo