WoW:Using bindings.xml to create key bindings for your addon

Reference e
AddOns WoW API Widget API XML UI Event API WoW Lua Macro API CVars Battle.net HOWTOs Snippets UI tech Categories

→ UI AddOn

← WoW AddOn

See: Bindings file

Example:

bindings.xml

<Bindings>
  <Binding name="DOSTUFF" description="Default description" header="MYDOSTUFF">
    DoSomething();
  </Binding>
  <Binding name="DOOTHERSTUFF" description="Other default description" runOnUp="true">
    if ( keystate == "down" ) then
      DoSomethingElse();
    else
      DoSomethingYetDifferent();
    end
  </Binding>
  <Binding name="DOMORESTUFF" description="Yet another default description">
    DoOneThing();
  </Binding>
</Bindings>

dostuff.lua

-- Binding Variables
BINDING_HEADER_MYDOSTUFF = "The header";
BINDING_NAME_DOSTUFF = "a name";
BINDING_NAME_DOOTHERSTUFF = "another name";
BINDING_NAME_DOMORESTUFF = "yet another name";

As of 2.0, "dummy" bindings (bindings containing only a comment) can be used with names that match the Bindings.xml syntax for saving spell, item, macro and click bindings. Because these terms have spaces in them, you will need to use global name-string references to set the names that appear by them.

Bindings.xml

<Bindings>
  <Binding name="SPELL Corruption">
    -- Corruption
  </Binding>
  <Binding name="ITEM Heavy Netherweave Bandage">
    -- HNB
  </Binding>
  <Binding name="MACRO RawrBomb!">
    -- blitz
  </Binding>
  <Binding name="CLICK TargetFrame:RightButton">
    -- menu!
  </Binding>
</Bindings>

The above code is equivalent to the below code, except with the above, the user chooses the bindings and with the below, the coder chooses the bindings.

SetBindingSpell(key, "Corruption")
SetBindingItem(key, "Heavy Netherweave Bandage")
SetBindingMacro(key, "RawrBomb!")
SetBindingClick(key, "TargetFrame", "RightButton")

yourAddon.lua

_G["BINDING_NAME_SPELL Corruption"] = "Dot 'em up!"
setglobal("BINDING_NAME_CLICK TargetFrame:RightButton", "Open your target menu")

Notes

• The Binding attribute runOnUp="true" is needed to use the keystate variable; unneeded otherwise.

• A binding with no keystate will fire on key down.

• WoW starts a new header when it finds a header="MYDOSTUFF" in a binding definition.
  You can not "hook into" a previous header using this way because the variables die after the Bindings.xml file has been processed.

• WoW tries to look for a Lua variable BINDING_HEADER_MYDOSTUFF if you use header="MYDOSTUFF".
  If it can not find that, your binding will end up with the previous header.

• If you use name="DOSTUFF" then WoW tries to look for a Lua variable
  named BINDING_NAME_DOSTUFF. If that is not found, it uses description.
  If description is not present, it uses the name.
  This last case will look ugly.

• As of 2.1, the code blocks cannot be empty or the keybindings interface will ignore the binding. A comment is enough, i.e. "-- dummy".

• This is, so far, the only way to get bindings to be listed on the default key bindings UI.

The juggling about with Lua variable names is to make it possible to localize your addon. See HOWTO: Localize an AddOn for standard localization practices.