WoW:API SetBinding: Difference between revisions

From AddOn Studio
Jump to navigation Jump to search
m (Added a note that SetBinding does not work in combat as of 2.0.1.)
m (Move page script moved page API SetBinding to API SetBinding without leaving a redirect)
 
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<center>'''SetBinding'''</center>
{{wowapi}} {{protectedcombatapi|2.0|Snippets executed by [[SecureHandlers]] may alter [override] bindings in-combat.}}
Alters the action performed by a binding.
ok = SetBinding("key"[, "command"[, mode]]);


Binds a key or button press to a command.  Unbinds the key or button if the ''command'' argument is nil.
== Arguments ==
; key : String - Any binding string accepted by World of Warcraft. For example: "ALT-CTRL-F", "SHIFT-T", "W", "BUTTON4".
; command : String/nil - Any name attribute value of a Bindings.xml-defined binding, or an action command string. For example:
:* "SITORSTAND" : a Bindings.xml-defined binding to toggle between sitting and standing
:* "CLICK PlayerFrame:LeftButton" : Fire a left-click on the PlayerFrame.
:* "SPELL Bloodrage" : Cast Bloodrage.
:* "ITEM Hearthstone" : Use {{item|Hearthstone}}
:* "MACRO Foo" : Run a macro called "Foo"
:* "MACRO 1" : Run a macro with index 1.
; mode : Number - 1 if the binding should be saved to the currently loaded binding set (default), or 2 if to the alternative.


There does not appear to be a limit to the number of keys you can bind to a command.  The GUI key binding window will only show you the first two.  But if you set 5 different keys to the same command, they will all work.
== Returns ==
; ok : Flag - 1 if the binding has been changed successfully, nil otherwise.


A single key can only be bound to one command. Binding a key to a command that is already bound to another command will result in un-binding the key from the previous command.
== Example ==
 
  -- Remove all bindings from the right mouse button.
If the function succeeds, the keys are usable immediately in game and will appear in the GUI key bindings window. However, they are not written to disk unless [[API SaveBindings|SaveBindings()]] is called.  [[API SaveBindings|SaveBindings()]] is not called as part of the normal Logout procedure, so you either have to call it manually or open the GUI key binding window and click Okay.
  SetBinding("BUTTON2");
 
  -- Restore the default binding for the right mouse button.
SetBinding no longer appears to work if your character is in combat. (2.0.1)
 
----
;''Arguments''
 
:(String key, String command)
 
:;key : (string) Key name of the key to bind (e.g. W, CTRL-F, BUTTON2).  ''As of 1.6 there is now error checking on this value so random strings for key names won't work anymore.''
:;command : (string) Command name to execute when the key is pressed (e.g. MOVEFORWARD, TOGGLECHARACTER0).  This argument is optional.  If not included, the function will un-bind the key argument.  Also, using an invalid command will also un-bind the key specified.
 
----
;''Example''
 
  -- Set the default behavior for the right mouse button
  SetBinding("BUTTON2","TURNORACTION");
  SetBinding("BUTTON2","TURNORACTION");
-- Set the W key to move forward
SetBinding("W", "MOVEFORWARD");
-- Unset the key combination Ctrl+F
SetBinding("CTRL-F");
----
;''Returns''


:;success : 1 if the binding succeeded. nil if it failed or the key was unbound.
== Details ==
* There are two binding sets: per-account and per-character bindings; of which one may be presently loaded ({{api|LoadBindings}}). You may look up which one is currently loaded using {{api|GetCurrentBindingSet}}().
* A single binding can only be bound to a single command at a time, although multiple bindings may be bound to the same command. The Key Bindings UI will only show the first two bindings, but there is no limit to the number of keys that can be used for the same command.
* The Key Bindings UI will update immediately should this function succeed. However, bindings are not saved without an explicit {{api|SaveBindings}}() call. Unless saved, bindings will reset on next log-in / bindings load.
* A list of default FrameXML bindings.xml-defined actions is available: [[BindingID]].
* The Addon API doesn't know what the default binding is for any single action. You can set them all to their defaults by calling <code>{{api|LoadBindings}}(DEFAULT_BINDINGS)</code>; this is an all-or-nothing action.


----
==See Also==
{{Template:WoW API}}
* [[API SetBindingSpell]]
* [[API SetBindingItem]]
* [[API SetBindingMacro]]
* [[API SetBindingClick]]

Latest revision as of 04:47, 15 August 2023

← WoW API < SetBinding

Icon-addon-48x48.png This function is protected, and cannot be called from insecure code while in in combat.
  • It has been protected since patch 2.0.
  • Snippets executed by SecureHandlers may alter [override] bindings in-combat.

Alters the action performed by a binding. 

ok = SetBinding("key"[, "command"[, mode]]);

Arguments[edit]

key
String - Any binding string accepted by World of Warcraft. For example: "ALT-CTRL-F", "SHIFT-T", "W", "BUTTON4".
command
String/nil - Any name attribute value of a Bindings.xml-defined binding, or an action command string. For example:
  • "SITORSTAND" : a Bindings.xml-defined binding to toggle between sitting and standing
  • "CLICK PlayerFrame:LeftButton" : Fire a left-click on the PlayerFrame.
  • "SPELL Bloodrage" : Cast Bloodrage.
  • "ITEM Hearthstone" : Use Template:Item
  • "MACRO Foo" : Run a macro called "Foo"
  • "MACRO 1" : Run a macro with index 1.
mode
Number - 1 if the binding should be saved to the currently loaded binding set (default), or 2 if to the alternative.

Returns[edit]

ok
Flag - 1 if the binding has been changed successfully, nil otherwise.

Example[edit]

-- Remove all bindings from the right mouse button.
SetBinding("BUTTON2");
-- Restore the default binding for the right mouse button.
SetBinding("BUTTON2","TURNORACTION");

Details[edit]

  • There are two binding sets: per-account and per-character bindings; of which one may be presently loaded (LoadBindings). You may look up which one is currently loaded using GetCurrentBindingSet().
  • A single binding can only be bound to a single command at a time, although multiple bindings may be bound to the same command. The Key Bindings UI will only show the first two bindings, but there is no limit to the number of keys that can be used for the same command.
  • The Key Bindings UI will update immediately should this function succeed. However, bindings are not saved without an explicit SaveBindings() call. Unless saved, bindings will reset on next log-in / bindings load.
  • A list of default FrameXML bindings.xml-defined actions is available: BindingID.
  • The Addon API doesn't know what the default binding is for any single action. You can set them all to their defaults by calling LoadBindings(DEFAULT_BINDINGS); this is an all-or-nothing action.

See Also[edit]

Retrieved from "https://addonstudio.org/mw/index.php?title=WoW:API_SetBinding&oldid=19778"