AddOn Studio

WoW:Creating a slash command: Difference between revisions

WoW Talk

WoW:Creating a slash command (source)

Revision as of 18:29, 24 July 2017

1,096 bytes added ,  24 July 2017
m
no edit summary
mNo edit summary
Line 1: Line 1:
{{UIHowTo}}
{{UIHowTo}}
'''Slash commands''' allow the player to interact with addons by typing commands into the chat window. This tutorial describes the necessary steps to add the ability to handle slash commands to your addon.
'''Slash commands''' allow the player to type commands into the chat window to interact with add-ons. This tutorial describes the necessary steps to add slash commands to your addon.


Summary: assign a handler function to <code>SlashCmdList[''key'']</code>, and create <code>SLASH_''key''1</code>, ..., <code>SLASH_''key''n</code> global constants containing the desired command names, where ''key'' is some unique command-specific string.
A fast example:


==Background==
SLASH_TEST1 = "/test1"
SLASH_TEST2 = "/addontest1"
SlashCmdList["TEST"] = function(msg)
    print("Hello World!")
end
 
This assigns a handler function to 'SlashCmdList["TEST"]', and creates 'SLASH_TEST1' and 'SLASH_TEST2' global variables, with the actual slash commands of '/test1' and '/addontest1'. WoW processes the 'SlashCmdList' and uses the key of "TEST" to find the global variable 'SLASH_TEST1', so those names must match and not conflict with another add-on or WoW UI slash key name.
 
WoW will then use the SlashCmdList 'TEST' key to find consecutive 'SLASH_TESTx' globals by iterating 'SLASH_TEST1', 'SLASH_TEST2', an so on until the next numbered global is not found. So the appended numbers must be consecutive and not have a gap. All of the 'SLASH_TESTx' slash commands will now execute the same handler.   
 
When a user types a command starting with "/test1" or "/addontest1", WoW will run the Lua function assigned to SlashCmdList["TEST"], passing the command string without "/test1 " to the function as 'msg'.
 
== Background ==
Slash command handlers are typically invoked by Blizzard's FrameXML code handling the player's chat input; therefore, an addon offering a slash command must register the command by placing certain values in a location where the chat input handling code looks for them.
Slash command handlers are typically invoked by Blizzard's FrameXML code handling the player's chat input; therefore, an addon offering a slash command must register the command by placing certain values in a location where the chat input handling code looks for them.


Line 26: Line 38:


== Parsing Arguments ==
== Parsing Arguments ==
If the user types '''/yourcmd someargs''' into chat, the function handling '''/yourcmd''' is passed "someargs" as the first argument (the second being the edit box widget into which the slash command was typed). Your handler function can then choose to act on that argument string. For simple slash commands, comparisons to pre-determined strings may be sufficient: suppose we wanted to modify the "Hello, World!" example above to display a different string if the command was passed an argument (say '''/hiw bye'''):
If the user types '/yourcmd someargs' into chat, the function handling '/yourcmd' is passed 'someargs' as the first argument we have been naming 'msg', with the second argument as the chat edit box widget. Your handler function can then choose to act on that argument string. For simple slash commands, comparisons to pre-determined strings may be sufficient. Suppose we wanted to modify the "Hello, World!" example above to display a different string if the command was passed an argument, say "/hiw bye".


SLASH_HELLOWORLD1, SLASH_HELLOWORLD2 = '/hiw', '/hellow';
  local function MyAddonCommands(msg, editbox)
  local function handler(msg, editbox)
  if msg == 'bye' then
  if msg == 'bye' then
    print('Goodbye, World!')
  print('Goodbye, World!');
  else
  else
    print("Hello, World!")
  print("Hello, World!");
  end
  end
  end
  end
  SlashCmdList["HELLOWORLD"] = handler; -- Also a valid assignment strategy
SLASH_HELLOWORLD1, SLASH_HELLOWORLD2 = '/hiw', '/hellow'
  SlashCmdList["HELLOWORLD"] = MyAddonCommands  -- add /hiw and /hellow to command list


More complex slash commands may wish to use [[Pattern matching]] to parse the arguments string:
Here is a more complex slash command example that is able to process arguments for commands that uses Lua [[Pattern matching]] to parse the arguments string:
  local function handler(msg, editbox)
 
  local command, rest = msg:match("^(%S*)%s*(.-)$");
  local function MyAddonCommands(msg, editbox)
  -- Any leading non-whitespace is captured into command;
  -- pattern matching that skips leading whitespace and whitespace between cmd and args
  -- the rest (minus leading whitespace) is captured into rest.
  -- any whitespace at end of args is retained
  if command == "add" and rest ~= "" then
  local _, _, cmd, args = string.find(msg, "%s?(%w+)%s?(.*)")
  -- Handle adding of the contents of rest... to something.
   
  elseif command == "remove" and rest ~= "" then
  if cmd == "add" and args ~= "" then
  -- Handle removing of the contents of rest... to something.   
    print("adding " .. args)
  else
    -- Handle adding of the contents of rest... to something.
  -- If not handled above, display some sort of help message
  elseif cmd == "remove" and args ~= "" then
  print("Syntax: /yourcmd (add|remove) someIdentifier");
    print("removing " .. args)
  end
    -- Handle removing of the contents of rest... to something.   
  else
    -- If not handled above, display some sort of help message
    print("Syntax: /hellow (add|remove) someIdentifier");
  end
  end
  end
SLASH_HELLOWORLD1, SLASH_HELLOWORLD2 = '/hiw', '/hellow'
SlashCmdList["HELLOWORLD"] = MyAddonCommands  -- add /hiw and /hellow to command list


== Notes ==
== Notes ==
Line 57: Line 79:
** If the unique command identifier (the key in SlashCmdList) conflicts between multiple addons, the addon that executes the assignment last will own the slash command.
** If the unique command identifier (the key in SlashCmdList) conflicts between multiple addons, the addon that executes the assignment last will own the slash command.
* Command identifiers are generally all caps, with underscores if necessary. These can also contain lowercase characters.
* Command identifiers are generally all caps, with underscores if necessary. These can also contain lowercase characters.
** The actual '''SLASH_''&lt;CommandId&gt;''''&lt;Number&gt;''''' values should be localizable if you plan on your addon being translated, but the command ID will remain the same.
** The actual 'SLASH_&lt;CommandId&gt;&lt;Number&gt;' values should be localizable if you plan on your addon being translated, but the command ID will remain the same.
* Be prudent about how many aliases you make for your command, and try and pick something that's unlikely to collide with someone else's (including Blizzard's!)
* Be prudent about how many aliases you make for your command, and try and pick something that's unlikely to collide with someone else's (including Blizzard's!)
* There's a second parameter passed to the slash command handler functions that is rarely used. It is the chat frame edit box frame that the slash command originated from.
* There's a second parameter passed to the slash command handler functions that is rarely used. It is the chat frame edit box frame that the slash command originated from.
Line 67: Line 89:
  end
  end
* If you want to set your slash command handler function to a method of an object, you will need to encapsulate the call to it inside a dummy function.
* If you want to set your slash command handler function to a method of an object, you will need to encapsulate the call to it inside a dummy function.
  function SomeObject:SlashHandler(message, editbox)
  function SomeObject:SlashHandler(message, editbox)
   -- do stuff
   -- do stuff
Retrieved from "https://addonstudio.org/wiki/Special:MobileDiff/6269"