WoW:API SetBindingItem: Difference between revisions

From AddOn Studio
Jump to navigation Jump to search
m (New page: {{wowapi}} <center>'''SetBindingItem'''</center> Binds a key or button press to a usable item. Unbinds the key or button if the ''command'' argument is nil. There does not appear to be ...)
 
m (Move page script moved page API SetBindingItem to API SetBindingItem without leaving a redirect)
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
{{wowapi}}
{{wowapi}} {{protectedcombatapi|2.0|Snippets executed by [[SecureHandlers]] may alter [override] bindings in-combat.}}
<center>'''SetBindingItem'''</center>
Sets a binding to use a specified item.
ok = SetBindingItem("key", "item");


Binds a key or button press to a usable item.  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".
; item : String - Item name (or item string) you want the binding to use. For example: "Hearthstone", "item:6948"


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.
== Details ==
* This function is functionally equivalent to the following statement.
ok = {{api|SetBinding}}("key", "ITEM " .. item);
* 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.
* You must use {{api|SetBinding}} to unbind a key.


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.
==See Also==
 
* {{api|SetBinding}}
SetBindingItem doesn't appears to work if your character is in combat. (2.0.1)
 
----
;''Arguments''
 
:(String key, String itemName)
 
:;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.''
:;itemName: (string) The name of a usable item to use when the key is pressed (e.g. "Hearthstone", "Scroll of Intellect").  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.
 
----
;''Returns''
 
:;success : 1 if the binding succeeded.  nil if it failed or the key was unbound.
 
----
;''Note:''
:This is equivalent to [[API SetBinding|SetBinding]](key, "ITEM " .. itemName)

Latest revision as of 04:47, 15 August 2023

← WoW API < SetBindingItem

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.

Sets a binding to use a specified item. 

ok = SetBindingItem("key", "item");

Arguments[edit]

key
String - Any binding string accepted by World of Warcraft. For example: "ALT-CTRL-F", "SHIFT-T", "W", "BUTTON4".
item
String - Item name (or item string) you want the binding to use. For example: "Hearthstone", "item:6948"

Returns[edit]

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

Details[edit]

  • This function is functionally equivalent to the following statement.
ok = SetBinding("key", "ITEM " .. item);
  • 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.
  • You must use SetBinding to unbind a key.

See Also[edit]

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