-
Notifications
You must be signed in to change notification settings - Fork 150
Keybinding
CBA Keybinding allows users to change the keybindings for custom addons and missions from a unified location. It also allows modders to easily include GUI-based configurable keybindings in their addons or missions without developing their own user interface and key handling routines. CBA Keybinding uses CBA's highly reliable internal key-handling routines to ensure that these keybinds persist across mission reloads, editor sessions, and other actions which can cause custom keybinds to disappear.
!cba_keybinding_gui.png!
CBA Keybinding is easy to use. First, load Arma 3 with CBA and the mods you intend to use.
Then, to access the configuration page for CBA-defined mod keybindings:
- Select Configure -> Controls from the Main Menu.
- Click the Configure Addons button in the lower right of the dialog.
- Select the name of the addon you'd like to configure from the drop-down menu.
- Double click any action to change the key assigned to it.
CBA Keybinding is easy to use for addon and mission makers, too. Simply create a function that performs some action on a keypress, and then associate that function name with a keybinding by calling CBA_fnc_addKeybind (usually in your init.sqf or XEH_clientInit.sqf). There is no need to remove your keybinding; it will not appear when your mod or mission is unloaded, and keybinds which are not defined in future versions of your mod or mission will also disappear.
Function: CBA_fnc_addKeybind
Description:
Adds or updates the keybind handler for a specified mod action, and associates
a function with that keybind being pressed.
Parameters:
_modName Name of the registering mod [String]
_actionId Id of the key action. [String]
_displayName Pretty name, or an array of strings for the pretty name and a tool tip [String]
_downCode Code for down event, empty string for no code. [Code]
_upCode Code for up event, empty string for no code. [Code]
Optional:
_defaultKeybind The keybinding data in the format [DIK, [shift, ctrl, alt]] [Array]
_holdKey Will the key fire every frame while down [Bool]
_holdDelay How long after keydown will the key event fire, in seconds. [Float]
_overwrite Overwrite any previously stored default keybind [Bool]
Returns:
Returns the current keybind for the action [Array]
Suppose that you want show your user a hint message every time a key is pressed. First, write the function that will show your hint.
mymod_fnc_showGameHint = {
hint format ["You can breathe air right now: %1", isAbleToBreathe player];
};
Now you need associate the function name with a keybind. The keybind you specify here will be the default, and calling this function later will not overwrite user changes. A keybind is an array in the format:
[[DIK code](https://community.bistudio.com/wiki/DIK_KeyCodes), [Shift?, Ctrl?, Alt?]]
If you add the line
#include "\a3\editor_f\Data\Scripts\dikCodes.h"
to your script, you can use names for the keys rather than numbers.
Example: Shift-M would be [DIK_M, [true, false, false]]
Finally, to bind your function to a key, call CBA_fnc_addKeybind:
["My Awesome Mod","show_breathing_key", "Show Breathing", {_this call mymod_fnc_showGameHint}, {}, [DIK_B, [true, true, false]]] call CBA_fnc_addKeybind;
Do this in your init.sqf or XEH client-only event handler to ensure that it is registered when your mission/mod is initialized.
You might want to open a CBA FlexiMenu using a configurable keybind.
First, create the parameter array you would normally pass to CBA_ui_fnc_fleximenu_add, but leave the keycode array empty:
["player", [], -100, "_this call my_fleximenu"];
Finally, add your keybinding using the function CBA_fnc_addKeybindToFleximenu:
Function: CBA_fnc_addKeybindToFleximenu
Description:
Adds or updates the keybind handler for a defined Fleximenu and creates that Fleximenu.
Parameters:
_modName Name of the registering mod [String]
_actionName Name of the action to register [String]
_displayName Pretty name, or an array of strings for the pretty name and a tool tip [String]
_fleximenuDef Parameter array for CBA_fnc_flexiMenu_Add, but with the keybind set to [] [Array]
Optional:
_defaultKeybind Default keybind [DIK code, [shift?, ctrl?, alt?]] [Array]
_holdKey Will the key fire every frame while down [Bool] (Default: true)
_holdDelay How long after keydown will the key event fire, in seconds. [Float] (Default: 0)
_overwrite Overwrite existing keybind data? [Bool] (Default: False)
Returns:
Returns the current keybind for the Fleximenu [Array]
Example:
["My Awesome Mod", "open_menu_key", "Open Menu", ["player", [], -100, "_this call my_fleximenu"], [DIK_P,[true,true,true]]] call CBA_fnc_addKeybindToFleximenu;
Calling this will create and register the Fleximenu, so you do not need to separately call CBA_ui_fnc_fleximenu_add.
Function: CBA_fnc_getKeybind
Description:
Checks if a particular mod has already registered a keybind handler for the
specified action.
Parameters:
_modName Name of the registering mod [String]
_actionName Name of the action to get [String]
Returns:
Keyboard entry.
Examples:
_index = ["your_mod", "openMenu"] call cba_fnc_getKeybind;
if (_index >= 0) then {
_handler = cba_keybind_handlers select _index;
};
For certain actions, you might want to execute a function on both keydown and keyup events. (For example, lasing a target.)
// Register different events for both keydown and keyup of the same action
["Your Mod", "your_mod__double_action_key", "Your Double Action", {_this call your_mod_fnc_keyDown}, {_this call your_mod_fnc_keyUp}, [DIK_P, [false, false, false]]] call cba_fnc_addKeybind;
If you make an incorrectly formatted call while testing, you could corrupt the keybinding registry (although many checks are in place to prevent this). If that happens, run
profileNamespace setVariable ["cba_keybinding_registry", []]; saveProfileNamespace;
in your debug console.
Please submit any bugs to the CBA bug tracker.