LGUI2:Input Bindings
LavishGUI 2 implements an input bindings system with support for various types of input controls including axis (thumbsticks, triggers, etc) and directional pad (D-pad) controls. Input bindings designed in JSON format.
An Input Binding binds an input control combination to an Event Handler. When all input controls are moved into the required position for the Input Binding to activate, the Event Handler fires with an "activated" boolean value, and then again when controls are no longer in the required position with the "activated" value set to false. LavishGUI 2 has several options for identifying Input Controls, and multiple ways to configure Event Handlers.
- Here is an example Input Bindings list that can be loaded into LavishGUI 2
[
{
"name":"I did it!",
"controls":"VK_LBUTTON",
"modifiers":"alt",
"eventHandler":["method","MyBindingController","IDidIt"]
}
]
The above example will execute the LavishScript method MyBindingController:IDidIt when pressing or releasing Alt+Mouse1. Event Handlers may also opt to directly embed LavishScript code (as done with LavishGUI), but we recommend providing a controller object as best practice.
Defining an Input Binding
Each Input Binding is defined by a JSON object, enclosed by {}.
Each binding must have at least a "name", "controls", and "eventHandler", and can optionally have "modifiers". Please note that these are case sensitive, so "Name" is incorrect, while "name" is correct.
name
The name of the Input Binding may be displayed to the user, for example to re-configure the required controls. It should therefore make some sort of sense to the user, and should usually be related to the intention of the Event Handler -- what is it going to do?
controls
"controls" may be provided as a string, or in more complicated cases may be provided as an array of strings and/or objects.
As a string
When providing controls as a string, one or more buttons (and only button controls) may be specified and separated by +. For example, "A+B" would require both A and B be pressed at the same time.
Control Names
LGUI 2 can interpret control names provided as part of a string in a few different ways:
- A Virtual-key code number, in base 10, will be recognized as the appropriate keyboard button. Noting that 1 through 0 are actual key names, this only applies to virtual-key code numbers 10-255, and therefore the mouse buttons (with their code numbers under 10) are also excluded.
- A Virtual-key code name such as VK_LBUTTON or VK_A will be recognized as the appropriate mouse or keyboard button
- Mouse1 through Mouse5 will be recognized as the appropriate mouse button
- Any other value is assumed to be the control name itself, with no assumption about which input device the control comes from (examples: A, B, C, D, G15-G1, etc)
It is acceptable to mix any combination of these, for example VK_LBUTTON+A is the same as VK_LBUTTON+VK_A or VK_LBUTTON+65 -- 65 being the code number for 'A'.
Objects in an array
More complicated control requirements, such as the use of axis/trigger or directional pad controls, can each be defined with an object. The values provided in the object will later determine if a control being moved matches the given parameters.
| Input Control matching | |
|---|---|
| All values optional, although at least one value must be provided. | |
| controlName | The name of the Input Control, according to Inner Space, such as "A" or "B" |
| controlVKeyName | The Virtual-key code name for the control, such as "VK_LBUTTON" or "VK_A" |
| controlID | The input device's ID number for the control, such as 1 or 2 |
| controlType | One of the following values: "button" "mousebutton" "dpad" "axis" "mousewheel" "cursor" "note" |
| controlChannel | For MIDI controls, the MIDI Channel |
| deviceName | "Keyboard" or "Mouse", or Inner Space's name for an alternative Input Device, such as "G15 Keyboard (22-input)" or "XBOX 360 For Windows (Controller) (16-input)" |
| deviceProductID | The device manufacturer's Product ID number for the device. Provide as a JSON string in base 16, or as a JSON number in base 10. For example from "045E-028E XBOX 360 For Windows (Controller) (16-input)" the base 16 Product ID is 028E, which is the number 654. This would be provided like "deviceProductID":654 or "deviceProductID":"028E" |
| deviceManufacturerID | The device manufacturer's USB ID number. Provide as a JSON string in base 16, or as a JSON number in base 10. For example from "045E-028E XBOX 360 For Windows (Controller) (16-input)" the base 16 Manufacturer ID is 045E, which is the number 1118. This would be provided like "deviceManufacturerID":1118 or "deviceManufacturerID":"045E" |
| deviceType | One of the following values: "keyboard" "mouse" "midi" "other" |
| devicePort | For MIDI devices, the name of the MIDI "port" as specified by Inner Space |
| minValue | A number usually between 0.0 and 1.0 representing the minimum position of the control in order to activate the binding. |
| maxValue | A number usually between 0.0 and 1.0 representing the maximum position of the control in order to activate the binding. By default, this is inclusive. |
| value | A number usually between 0.0 and 1.0 representing both the minimum and maximum position of the control in order to activate the binding. (For example, a button may use 1.0 to mean the button is pressed, or 0.0 to mean the button is not pressed) |
| minX | A minimum X value, used only for "Cursor" |
| maxX | A maximum X value, used only for "Cursor" |
| minY | A minimum Y value, used only for "Cursor" |
| maxY | A minimum Y value, used only for "Cursor" |
| valuesRelative | Specifies whether the X and Y values provided are relative. By default, absolute cursor position is used. |
| maxValuesExclusive | Specifies whether the maximum value (or in the case of "Cursor", the maximum X and Y values) is exclusive. By default, the maximum value is inclusive and thus may match the minimum. |
Control Types and their values
- button and mousebutton: 1.0 for pressed, or 0.0 for not pressed
- axis: Values 0.0 to 1.0
- note: Values 0.0 to 1.0
- dpad: -1.0 at rest. 0.0-359.99 for direction, being degrees clockwise from up=0.0, so right=90.0, down=180.0, left=270.0
- mousewheel: Mouse wheel ticks are 120.0, with up being negative. -120.0 is up one tick, -240.0 is up two ticks. 240.0 is down two ticks.
- cursor: The cursor has both an X and Y value. In absolute positioning mode, the top left corner of the client area of the host window (Inner Space Uplink, the game, etc) is 0,0, with X increasing to the right and Y increasing downward. The values are tied to the host window's 3D resolution. In relative positioning mode (used if valuesRelative is specified as true), the difference from the previous position is used; for example, if the cursor moved from 100,100 to 125,75, the relative X,Y values are 25,-25.
modifiers
"modifiers" specifies the set of Alt, Ctrl, Shift, and Win keys that must be pressed with the list of controls for the input binding to activate. This can be specified as one string with plus-separated modifier names, as an array of modifier names, or a JSON object with boolean properties for each required modifier.
As a string
When listing modifiers this way, one or more modifiers may be specified, and separated by +. For example, "alt+ctrl" would require both alt and ctrl be pressed at the same time.
Modifier names
| Modifier names | |
|---|---|
| alt | Either Alt |
| ctrl | Either Ctrl |
| shift | Either Shift |
| win | Either Win |
| lalt | Left Alt |
| lctrl | Left Ctrl |
| lshift | Left Shift |
| lwin | Left Win |
| ralt | Right Alt |
| rctrl | Right Ctrl |
| rshift | Right Shift |
| rwin | Right Win |
As an array of strings
When provided as an array of strings, the same modifier names are used but are separated in the array rather than separated by a plus. For example, ["alt","ctrl"] would require both alt and ctrl be pressed at the same time.
As an object
When provided as an object (which have case sensitive), camelCase is used to specify modifier names that begin with l or r -- so lalt becomes lAlt, lshift becomes lShift, and so on. Otherwise, use any modifier name from the above table and specify a boolean value (true or false), such as {"alt":true,"ctrl":true} to require both alt and ctrl be pressed at the same time.
eventHandler
The Event Handler specifies what should happen when the input binding is activated or deactivated. It is specified as either an array or an object. Although this page provides an example, please refer to the main Event Handler page for details!
Loading Input Bindings into LavishGUI 2
The LGUI2 object includes a LoadBindingsFile method, which will load a bindings file containing an array of JSON objects and apply the bindings to the LavishGUI 2 root.
LGUI2:LoadBindingsFile[somefile.json]
LavishGUI 2 is currently in active development. There will be additional ways to load input bindings in future updates. Feel free to put in requests!
LavishGUI 2 Topics
