Key bindings

From ESOUI Wiki

Key bindings allow an add-on to intercept and handle certain keypresses.

Bindings are defined in an XML file, and are organized into layers, categories, and actions. A "layer" is a set of bindings that the game (and add-ons' Lua code) can turn on and off using functions like PushActionLayerByName. A "category" is a semantic grouping for bindings; categories are used to organize bindings into subheadings in the game's Controls menu, but otherwise do nothing. An "action" is an actual behavior that can be bound to a key.

Here's a basic example of a bindings file:

<Bindings>
   <Layer name="SI_MY_ADDON_LAYER">
      <Category name="SI_MAIN_FUNCTIONS">
         <Action name="TURN_RIGHT">
            <Down>TurnRightStart()</Down>
            <Up>TurnRightStop()</Up>
         </Action>
      </Category>
   </Layer>
</Bindings>

Layers and categories use the same names internally and on the UI; the game will pass the names through GetString to display them. Actions will have the string SI_BINDING_NAME_ prepended to their names, and the results will be passed through GetString for display (i.e. our example above would be GetString(SI_BINDING_NAME_TURN_RIGHT) which needs to be defined in your addon as string constant
https://wiki.esoui.com/How_to_add_localization_support#Creating_strings ).

Layers

An action layer is a group of keybinds that can be enabled or disabled all at once. Multiple layers can be active, forming a stack, where the layers "on top" will take precedence over the layers "below" them.

Attributes

name

A name for the layer. You can specify the name of an existing layer defined in another file if you wish to add new bindings to it.

Categories

Attributes

name

A name for the category.

Actions

Attributes

name

An identifier for the action. This must be unique across all keybinds to avoid causing UI errors and broken behavior.

hideAction

If this attribute is set to true, then the binding won't actually be displayed in the Controls menu.

rebindable

If this attribute is set to false, then the game will not allow the user to rebind the control.

inheritsBindFrom

This attribute can be used to specify the name of any other action. This action will use the same key as that other action (unless the inheriting action is rebound by the player).

Children

Down

Lua code to be executed when the key is first pressed down. When this code is running, the local keybind variable is set to the action's name attribute.

Up

Lua code to be executed when the key is released. When this code is running, the local keybind variable is set to the action's name attribute.

Notes

• Zenimax has a few action layers that only exist to prevent the game from acting on certain keypresses. For example, the SceneChangeInterceptLayer layer is used to prevent the player from forcibly closing the dialogue menu when they're under arrest by a guard. The layer contains multiple actions that inherit default controls, are not rebindable, and are not shown in the UI; these actions return true when their keys are pressed down, and this is used to prevent the player from taking any action that might change the current scene.
  • If you wish to conditionally block a key, you must explicitly return false in any Up/Down code fragments you define in order to allow other action layers to handle the keypress.