SimConnect_MapInputEventToClientEvent_EX1
IMPORTANT! There is a known bug with SimConnect_MapInputEventToClientEvent
where the DeviceId could change if a device was unplugged and plugged in again. To preserve backwards compatibility, that function has been deprecated in favour of SimConnect_MapInputEventToClientEvent_EX1
, which does not have this same potential issue. Therefor you should always use this function.The SimConnect_MapInputEventToClientEvent_EX1 function is used to connect input events (such as keystrokes, joystick or mouse movements) with the sending of appropriate event notifications.
Syntax
HRESULT SimConnect_MapInputEventToClientEvent_EX1(
HANDLE hSimConnect,
SIMCONNECT_INPUT_GROUP_ID GroupID,
const char* pszInputDefinition,
SIMCONNECT_CLIENT_EVENT_ID DownEventID,
DWORD DownValue = 0,
SIMCONNECT_CLIENT_EVENT_ID UpEventID =(SIMCONNECT_CLIENT_EVENT_ID)SIMCONNECT_UNUSED,
DWORD UpValue = 0,
BOOL bMaskable = FALSE
);
Parameters
Parameter | Description | Type |
---|---|---|
hSimConnect | Handle to a SimConnect object. | Integer |
GroupID | Specifies the ID of the client defined input group that the input event is to be added to. | Integer |
pszInputDefinition | Pointer to a null-terminated string containing the definition of the input events (keyboard keys, mouse or joystick events, for example). See the Remarks and example below for a range of possibilities. | Integer |
DownEventID | Specifies the ID of the down, and default, event. This is the client defined event that is triggered when the input event occurs. If only an up event is required, set this to SIMCONNECT_UNUSED . |
Integer |
DownValue | Specifies an optional numeric value, which will be returned when the down event occurs. |
Integer (OPTIONAL) |
UpEventID | Specifies the ID of the up event. This is the client defined event that is triggered when the up action occurs. |
Integer (OPTIONAL) |
UpValue | Specifies an optional numeric value, which will be returned when the up event occurs. |
Integer (OPTIONAL) |
bMaskable | If set to true, specifies that the client will mask the event, and no other lower priority clients will receive it. The default is false. |
Bool (OPTIONAL) |
Return Values
The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.
Return value | Description |
---|---|
S_OK | The function succeeded. |
E_FAIL | The function failed. |
VALUE | A numeric value that is returned when one of the optional parameters DownValue or UpValue have been supplied. |
Example
static enum INPUT_ID {
INPUT_1,
};
static enum EVENT_ID {
EVENT_1,
EVENT_2,
EVENT_3
};
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_1, "parking_brakes");
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "a+B", EVENT_1);
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "VK_LCONTROL+A+U", EVENT_1);
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "VK_LSHIFT+VK_LCONTROL+a", EVENT_2);
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "VK_RSHIFT+VK_RCONTROL+a", EVENT_2, 0, EVENT_3);
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "joystick:0:button:0", EVENT_2);
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "joystick:0:button:1", EVENT_3);
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "joystick:0:POV:0", EVENT_3);
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "joystick:0:XAxis", EVENT_3);
hr = SimConnect_SetInputGroupPriority(hSimConnect, INPUT_1, SIMCONNECT_GROUP_PRIORITY_HIGHEST);
Remarks
The maximum number of events that can be added to an input group is 1000. For the keyboard the input definition can include a maximum of two modifiers (VK_LCONTROL, VK_RCONTROL, VK_LSHIFT, VK_RSHIFT, VK_LMENU (Alt Left) and VK_RMENU (Alt Right)) and two keys (case sensitive). For joysticks the input definition is in the form "joystick:n:input[:i]
". Where n
is the joystick number (starting from 0), input
is the input name, and i
is an optional index number that might be required by the input name (joystick:0:button:0
for example). The input name can be one in the following table:
Input Name | Description | Range of values |
---|---|---|
Button | One of the joystick buttons, configured from 0. | Not applicable |
POV | Point of view switch (often called the hat switch). | 0 facing ahead 4500 forward right 9000 right 13500 rear right 18000 rear 22500 rear left 27000 left 31500 forward left |
Slider | The variable position slider on the joystick. | The actual values returned can vary widely on the joystick, though the limits are 32K (pulled back to the limit) to -32K (maximum forward limit). |
XAxis, YAxis or ZAxis | Movement of the joystick in the X, Y, or Z directions. For most joysticks the movement is left or right for the XAxis and forward or backward for the YAxis, with no values for the ZAxis. | The limits in the Y axis are 32K (pulled back) to -32K (pushed forward). The limits in the X axis are -32K (full left) to 32K (full right). Depending on the joystick though, the limits may be significantly less than these values. |
RxAxis, RyAxis, or RzAxis | Rotation of the joystick about the X, Y, or Z axis. For most joysticks there is only rotational movement around the Z axis, with no values for the X or Y axis. | For the Z axis, the limits are -32K (rotated left to the maximum) to 32K (rotated right to the maximum). Again, actual limits depend on the joystick. |
For keyboard hits, usually no further information other than the key has been pressed is necessary for the client to process the event appropriately. For joystick events, other than button events, it is also important to know the extent of the movement (or position of the hat switch, or of the slider). This information is returned with the event in the dwData parameter of a SIMCONNECT_RECV_EVENT structure.
For button, hat switch, or keyboard events, one event is transmitted to the client, or two if an up event is specified, when the input event occurs. If joystick axis, rotation or slider events are requested, then an event is transmitted for these six times per second whether the joystick is actually moved or not, unless the value for these is zero, in which case events are not transmitted until the joystick is moved from this position. Joystick and keyboard events are only transmitted when a flight is loaded, not while the user is navigating the shell of the product.
Valid Input Strings
The list below contains every valid input string that can be used:
"Backspace"
"Tab"
"VK_NUMPAD05"
"VK_Enter"
"VK_0x0E"
"VK_0x0F"
"VK_PAUSE"
"Caps_Lock"
"VK_KANA"
"VK_0x16"
"VK_JUNJA"
"VK_FINAL"
"VK_KANJI"
"VK_0x1A"
"Esc"
"VK_CONVERT"
"VK_NONCONVERT"
"VK_ACCEPT"
"VK_MODECHANGE"
"Space"
"VK_PRIOR"
"VK_NEXT"
"VK_END"
"VK_HOME"
"VK_LEFT"
"VK_UP"
"VK_RIGHT"
"VK_DOWN"
"VK_SELECT"
"VK_PRINT"
"VK_EXECUTE"
"Sys_Req"
"VK_INSERT"
"VK_DELETE"
"VK_HELP"
"0"
"1"
"2"
"3"
"4"
"5"
"6"
"7"
"8"
"9"
"A"
"B"
"C"
"D"
"E"
"F"
"G"
"H"
"I"
"J"
"K"
"L"
"M"
"N"
"O"
"P"
"Q"
"R"
"S"
"T"
"U"
"V"
"W"
"X"
"Y"
"Z"
"VK_LWIN"
"VK_RWIN"
"VK_APPS"
"VK_SLEEP"
"VK_NUMPAD0"
"VK_NUMPAD1"
"VK_NUMPAD2"
"VK_NUMPAD3"
"VK_NUMPAD4"
"VK_NUMPAD5"
"VK_NUMPAD6"
"VK_NUMPAD7"
"VK_NUMPAD8"
"VK_NUMPAD9"
"VK_MULTIPLY"
"VK_ADD"
"VK_SEPARATOR"
"VK_SUBTRACT"
"VK_DECIMAL"
"VK_DIVIDE"
"F1"
"F2"
"F3"
"F4"
"F5"
"F6"
"F7"
"F8"
"F9"
"F10"
"F11"
"F12"
"F13"
"F14"
"F15"
"F16"
"F17"
"F18"
"F19"
"F20"
"F21"
"F22"
"F23"
"F24"
"Pause"
"VK_SCROLL"
"VK_OEM_FJ_JISHO"
"VK_OEM_FJ_MASSHOU"
"VK_OEM_FJ_TOUROKU"
"VK_OEM_FJ_LOYA"
"VK_OEM_FJ_ROYA"
"VK_LSHIFT"
"VK_RSHIFT"
"VK_LCONTROL"
"VK_RCONTROL"
"VK_LMENU"
"VK_RMENU"
"VK_BROWSER_BACK"
"VK_BROWSER_FORWARD"
"VK_BROWSER_REFRESH"
"VK_BROWSER_STOP"
"VK_BROWSER_SEARCH"
"VK_BROWSER_FAVORITES"
"VK_BROWSER_HOME"
"VK_VOLUME_MUTE"
"VK_VOLUME_DOWN"
"VK_VOLUME_UP"
"VK_MEDIA_NEXT_TRACK"
"VK_MEDIA_PREV_TRACK"
"VK_MEDIA_STOP"
"VK_MEDIA_PLAY_PAUSE"
"VK_LAUNCH_MAIL"
"VK_LAUNCH_MEDIA_SELECT"
"VK_LAUNCH_APP1"
"VK_LAUNCH_APP2"
"VK_SEMICOLON"
"VK_PLUS"
"VK_COMMA"
"VK_MINUS"
"VK_PERIOD"
"VK_SLASH"
"VK_TILDE"
"VK_LBRACKET"
"VK_BACKSLASH"
"VK_RBRACKET"
"VK_QUOTE"
"VK_0xDF"
"VK_0xE0"
"VK_OEM_AX"
"VK_OEM_102"
"VK_ICO_HELP"
"VK_ICO_00"
"VK_PROCESSKEY"
"VK_ICO_CLEAR"
"VK_PACKET"
"VK_0xE8"
"VK_OEM_RESET"
"VK_OEM_JUMP"
"VK_OEM_PA1"
"VK_OEM_PA2"
"VK_OEM_PA3"
"VK_OEM_WSCTRL"
"VK_OEM_CUSEL"
"VK_OEM_ATTN"
"VK_OEM_FINISH"
"VK_OEM_COPY"
"VK_OEM_AUTO"
"VK_OEM_ENLW"
"VK_OEM_BACKTAB"
"VK_ATTN"
"VK_CRSEL"
"VK_EXSEL"
"VK_EREOF"
"VK_PLAY"
"VK_ZOOM"
"VK_PA1"
"VK_OEM_CLEAR"
See Also
- SimConnect API Reference
- SimConnect_SetInputGroupPriority
- SimConnect_RemoveInputEvent
- SimConnect_ClearInputGroup
- SimConnect_SetInputGroupState