XPLMDefs API
This file is contains the cross-platform and basic definitions for the X-Plane SDK.
The preprocessor macros APL, LIN and IBM must be defined to specify the compilation target; define APL to 1 to compile on Mac, IBM to 1 to compile on Windows and LIN to 1 to compile on Linux. Only one compilation target may be used at a time. You must specify these macro definitions before including XPLMDefs.h or any other XPLM headers. You can do this using the -D command line option or a preprocessor header.
DLL Definitions
These definitions control the importing and exporting of functions within the DLL.
You can prefix your five required callbacks with the PLUGIN_API macro to declare them as exported C functions. The XPLM_API macro identifies functions that are provided to you via the plugin SDK. (Link against XPLM.lib to use these functions.)
GLOBAL DEFINITIONS
These definitions are used in all parts of the SDK.
XPLMPluginID
typedef int XPLMPluginID;
Each plug-in is identified by a unique integer ID. This ID can be used to disable or enable a plug-in, or discover what plug-in is ‘running’ at the time. A plug-in ID is unique within the currently running instance of X-Plane unless plug-ins are reloaded. Plug-ins may receive a different unique ID each time they are loaded. This includes the unloading and reloading of plugins that are part of the user’s aircraft.
For persistent identification of plug-ins, use XPLMFindPluginBySignature in XPLMUtiltiies.h .
-1 indicates no plug-in.
XPLMKeyFlags
These bitfields define modifier keys in a platform independent way. When a key is pressed, a series of messages are sent to your plugin. The down flag is set in the first of these messages, and the up flag in the last. While the key is held down, messages are sent with neither flag set to indicate that the key is being held down as a repeated character.
The control flag is mapped to the control flag on Macintosh and PC. Generally X-Plane uses the control key and not the command key on Macintosh, providing a consistent interface across platforms that does not necessarily match the Macintosh user interface guidelines. There is not yet a way for plugins to access the Macintosh control keys without using #ifdefed code.
Name | Value | Description |
---|---|---|
xplm_ShiftFlag | "1" | The shift key is down |
xplm_OptionAltFlag | "2" | The option or alt key is down |
xplm_ControlFlag | "4" | The control key is down |
xplm_DownFlag | "8" | The key is being pressed down |
xplm_UpFlag | "16" | The key is being released |
ASCII CONTROL KEY CODES
These definitions define how various control keys are mapped to ASCII key codes. Not all key presses generate an ASCII value, so plugin code should be prepared to see null characters come from the keyboard…this usually represents a key stroke that has no equivalent ASCII, like a page-down press. Use virtual key codes to find these key strokes.
ASCII key codes take into account modifier keys; shift keys will affect capitals and punctuation; control key combinations may have no vaild ASCII and produce NULL. To detect control-key combinations, use virtual key codes, not ASCII keys.
XPLM_KEY_RETURN
#define XPLM_KEY_RETURN 13
XPLM_KEY_ESCAPE
#define XPLM_KEY_ESCAPE 27
XPLM_KEY_TAB
#define XPLM_KEY_TAB 9
XPLM_KEY_DELETE
#define XPLM_KEY_DELETE 8
XPLM_KEY_LEFT
#define XPLM_KEY_LEFT 28
XPLM_KEY_RIGHT
#define XPLM_KEY_RIGHT 29
XPLM_KEY_UP
#define XPLM_KEY_UP 30
XPLM_KEY_DOWN
#define XPLM_KEY_DOWN 31
XPLM_KEY_0
#define XPLM_KEY_0 48
XPLM_KEY_1
#define XPLM_KEY_1 49
XPLM_KEY_2
#define XPLM_KEY_2 50
XPLM_KEY_3
#define XPLM_KEY_3 51
XPLM_KEY_4
#define XPLM_KEY_4 52
XPLM_KEY_5
#define XPLM_KEY_5 53
XPLM_KEY_6
#define XPLM_KEY_6 54
XPLM_KEY_7
#define XPLM_KEY_7 55
XPLM_KEY_8
#define XPLM_KEY_8 56
XPLM_KEY_9
#define XPLM_KEY_9 57
XPLM_KEY_DECIMAL
#define XPLM_KEY_DECIMAL 46
VIRTUAL KEY CODES
These are cross-platform defines for every distinct keyboard press on the computer. Every physical key on the keyboard has a virtual key code. So the “two” key on the top row of the main keyboard has a different code from the “two” key on the numeric key pad. But the ‘w’ and ‘W’ character are indistinguishable by virtual key code because they are the same physical key (one with and one without the shift key).
Use virtual key codes to detect keystrokes that do not have ASCII equivalents, allow the user to map the numeric keypad separately from the main keyboard, and detect control key and other modifier-key combinations that generate ASCII control key sequences (many of which are not available directly via character keys in the SDK).
To assign virtual key codes we started with the Microsoft set but made some additions and changes. A few differences:
- Modifier keys are not available as virtual key codes. You cannot get distinct modifier press and release messages. Please do not try to use modifier keys as regular keys; doing so will almost certainly interfere with users' abilities to use the native X-Plane key bindings.
- Some keys that do not exist on both Mac and PC keyboards are removed.
- Do not assume that the values of these keystrokes are interchangeable with MS v-keys.
XPLM_VK_BACK
#define XPLM_VK_BACK 0x08
XPLM_VK_TAB
#define XPLM_VK_TAB 0x09
XPLM_VK_CLEAR
#define XPLM_VK_CLEAR 0x0C
XPLM_VK_RETURN
#define XPLM_VK_RETURN 0x0D
XPLM_VK_ESCAPE
#define XPLM_VK_ESCAPE 0x1B
XPLM_VK_SPACE
#define XPLM_VK_SPACE 0x20
XPLM_VK_PRIOR
#define XPLM_VK_PRIOR 0x21
XPLM_VK_NEXT
#define XPLM_VK_NEXT 0x22
XPLM_VK_END
#define XPLM_VK_END 0x23
XPLM_VK_HOME
#define XPLM_VK_HOME 0x24
XPLM_VK_LEFT
#define XPLM_VK_LEFT 0x25
XPLM_VK_UP
#define XPLM_VK_UP 0x26
XPLM_VK_RIGHT
#define XPLM_VK_RIGHT 0x27
XPLM_VK_DOWN
#define XPLM_VK_DOWN 0x28
XPLM_VK_SELECT
#define XPLM_VK_SELECT 0x29
XPLM_VK_PRINT
#define XPLM_VK_PRINT 0x2A
XPLM_VK_EXECUTE
#define XPLM_VK_EXECUTE 0x2B
XPLM_VK_SNAPSHOT
#define XPLM_VK_SNAPSHOT 0x2C
XPLM_VK_INSERT
#define XPLM_VK_INSERT 0x2D
XPLM_VK_DELETE
#define XPLM_VK_DELETE 0x2E
XPLM_VK_HELP
#define XPLM_VK_HELP 0x2F
XPLM_VK_0
#define XPLM_VK_0 0x30
XPLM_VK_0 thru XPLM_VK_9 are the same as ASCII ‘0’ thru ‘9’ (0x30 - 0x39)
XPLM_VK_A
#define XPLM_VK_A 0x41
XPLM_VK_A thru XPLM_VK_Z are the same as ASCII ‘A’ thru ‘Z’ (0x41 - 0x5A)
XPLM_VK_NUMPAD0
#define XPLM_VK_NUMPAD0 0x60
XPLM_VK_NUMPAD1
#define XPLM_VK_NUMPAD1 0x61
XPLM_VK_NUMPAD2
#define XPLM_VK_NUMPAD2 0x62
XPLM_VK_NUMPAD3
#define XPLM_VK_NUMPAD3 0x63
XPLM_VK_NUMPAD4
#define XPLM_VK_NUMPAD4 0x64
XPLM_VK_NUMPAD5
#define XPLM_VK_NUMPAD5 0x65
XPLM_VK_NUMPAD6
#define XPLM_VK_NUMPAD6 0x66
XPLM_VK_NUMPAD7
#define XPLM_VK_NUMPAD7 0x67
XPLM_VK_NUMPAD8
#define XPLM_VK_NUMPAD8 0x68
XPLM_VK_NUMPAD9
#define XPLM_VK_NUMPAD9 0x69
XPLM_VK_MULTIPLY
#define XPLM_VK_MULTIPLY 0x6A
XPLM_VK_ADD
#define XPLM_VK_ADD 0x6B
XPLM_VK_SEPARATOR
#define XPLM_VK_SEPARATOR 0x6C
XPLM_VK_SUBTRACT
#define XPLM_VK_SUBTRACT 0x6D
XPLM_VK_DECIMAL
#define XPLM_VK_DECIMAL 0x6E
XPLM_VK_DIVIDE
#define XPLM_VK_DIVIDE 0x6F
XPLM_VK_F1
#define XPLM_VK_F1 0x70
XPLM_VK_F2
#define XPLM_VK_F2 0x71
XPLM_VK_F3
#define XPLM_VK_F3 0x72
XPLM_VK_F4
#define XPLM_VK_F4 0x73
XPLM_VK_F5
#define XPLM_VK_F5 0x74
XPLM_VK_F6
#define XPLM_VK_F6 0x75
XPLM_VK_F7
#define XPLM_VK_F7 0x76
XPLM_VK_F8
#define XPLM_VK_F8 0x77
XPLM_VK_F9
#define XPLM_VK_F9 0x78
XPLM_VK_F10
#define XPLM_VK_F10 0x79
XPLM_VK_F11
#define XPLM_VK_F11 0x7A
XPLM_VK_F12
#define XPLM_VK_F12 0x7B
XPLM_VK_F13
#define XPLM_VK_F13 0x7C
XPLM_VK_F14
#define XPLM_VK_F14 0x7D
XPLM_VK_F15
#define XPLM_VK_F15 0x7E
XPLM_VK_F16
#define XPLM_VK_F16 0x7F
XPLM_VK_F17
#define XPLM_VK_F17 0x80
XPLM_VK_F18
#define XPLM_VK_F18 0x81
XPLM_VK_F19
#define XPLM_VK_F19 0x82
XPLM_VK_F20
#define XPLM_VK_F20 0x83
XPLM_VK_F21
#define XPLM_VK_F21 0x84
XPLM_VK_F22
#define XPLM_VK_F22 0x85
XPLM_VK_F23
#define XPLM_VK_F23 0x86
XPLM_VK_F24
#define XPLM_VK_F24 0x87
XPLM_VK_EQUAL
#define XPLM_VK_EQUAL 0xB0
The following definitions are extended and are not based on the Microsoft key set.
XPLM_VK_MINUS
#define XPLM_VK_MINUS 0xB1
XPLM_VK_RBRACE
#define XPLM_VK_RBRACE 0xB2
XPLM_VK_LBRACE
#define XPLM_VK_LBRACE 0xB3
XPLM_VK_QUOTE
#define XPLM_VK_QUOTE 0xB4
XPLM_VK_SEMICOLON
#define XPLM_VK_SEMICOLON 0xB5
XPLM_VK_BACKSLASH
#define XPLM_VK_BACKSLASH 0xB6
XPLM_VK_COMMA
#define XPLM_VK_COMMA 0xB7
XPLM_VK_SLASH
#define XPLM_VK_SLASH 0xB8
XPLM_VK_PERIOD
#define XPLM_VK_PERIOD 0xB9
XPLM_VK_BACKQUOTE
#define XPLM_VK_BACKQUOTE 0xBA
XPLM_VK_ENTER
#define XPLM_VK_ENTER 0xBB
XPLM_VK_NUMPAD_ENT
#define XPLM_VK_NUMPAD_ENT 0xBC
XPLM_VK_NUMPAD_EQ
#define XPLM_VK_NUMPAD_EQ 0xBD
XPLMFixedString150_t
A container for a fixed-size string buffer of 150 characters.
typedef struct {
// The size of the struct.
char buffer[150];
} XPLMFixedString150_t;
XPLMCursorStatus
XPLMCursorStatus describes how you would like X-Plane to manage the cursor. See XPLMHandleCursor_f for more info.
Name | Value | Description |
---|---|---|
xplm_CursorDefault | "0" | X-Plane manages the cursor normally, plugin does not affect the cusrsor. |
xplm_CursorHidden | "1" | X-Plane hides the cursor. |
xplm_CursorArrow | "2" | X-Plane shows the cursor as the default arrow. |
xplm_CursorCustom | "3" | X-Plane shows the cursor but lets you select an OS cursor. |
XPLMMouseStatus
When the mouse is clicked, your mouse click routine is called repeatedly. It is first called with the
mouse down message. It is then called zero or more times with the mouse-drag message, and finally it
is called once with the mouse up message. All of these messages will be directed to the same window;
you are guaranteed to not receive a drag or mouse-up event without first receiving the corresponding mouse-down.
Name | Value | Description |
---|---|---|
xplm_MouseDown | "1" | |
xplm_MouseDrag | "2" | |
xplm_MouseUp | "3" |