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