Changes: UI beginner's guide

Revision as of 00:34, 25 July 2011

Returns information about a saved equipment set:

name, icon, setID, isEquipped, totalItems, equippedItems, inventoryItems, missingItems, ignoredSlots = GetEquipmentSetInfo(index)
icon, setID, isEquipped, numItems, equippedItems, availableItems, missingItems, ignoredSlots = GetEquipmentSetInfoByName("name")

Arguments

GetEquipmentSetInfo -- index: Number: an ascending index going from 1 to GetNumEquipmentSets().
GetEquipmentSetInfoByName -- name: String: equipment set name.

Returns

The functions returns nothing if the queried index or set name does not exist. If the index/name is valid, the following values are returned:

name: String: Equipment set name.
icon: String: Icon texture file name (relative to Interface/Icons) selected for this set.
setID: Number: Unknown.
isEquipped: Boolean: True if all non-ignored slots in this set are equipped.
numItems: Number: Number of items included in the set
equippedItems: Number: Number of items in this set currently equipped
availableItems: Number: Number of items in this set currently in the player's bags/bank, if bank is available
missingItems: Number: Number of items in this set that are not currently available to the player.
ignoredSlots: Number: Number of inventory slots ignored by this set

Example

local name, icon = GetEquipmentSetInfo(1);
if not name then
 print("You have no equipment sets");
else
 print("First equipment set: \124TInterface\\Icons\\" .. icon .. ":16\124t " .. name);
end

@@ Line 1: / Line 1: @@
+{{wowapi}}
-''This page explains the basic ideas behind and differences between terms like Macros, Scripts and AddOns to those who are beginners to using or making such things. It has not been updated for WoW 2.0 so many of the examples herein are no longer valid''
+Returns information about a saved equipment set:
+ name, icon, setID, isEquipped, totalItems, equippedItems, inventoryItems, missingItems, ignoredSlots = GetEquipmentSetInfo(index)
+ icon, setID, isEquipped, numItems, equippedItems, availableItems, missingItems, ignoredSlots = GetEquipmentSetInfoByName("name")
+==Arguments==
-== Slash Commands ==
+;GetEquipmentSetInfo -- index : Number: an ascending index going from 1 to [[API_GetNumEquipmentSets|GetNumEquipmentSets]]().
-To understand how everything else works, you need to know what a [[Slash Command]] is. WoW allows you to give simple commands to the game in the form of a slash (/) followed by the name of the command. You can give these commands directly by typing them into the chat box. An example would be the "/follow" command. If you target a friendly and type "/follow" (without the quotes), you start following them. You can get a list of some of the slash commands by typing "/help".
+;GetEquipmentSetInfoByName -- name: String: equipment set name.
+==Returns==
-There are several types of slash commands. Some are designed to perform game actions (e.g. /follow, /assist, /cast), others are chat related commands (e.g. /yell, /chatlist) or give you information (/who). You also have emotes (/laugh, /bow).
+The functions returns nothing if the queried index or set name does not exist. If the index/name is valid, the following values are returned:
+; name : String: Equipment set name.
+; icon : String: Icon texture file name (relative to Interface/Icons) selected for this set.
+; setID : Number: Unknown.
+; isEquipped : Boolean: True if all non-ignored slots in this set are equipped.
+; numItems : Number: Number of items included in the set
+; equippedItems : Number: Number of items in this set currently equipped
+; availableItems: Number: Number of items in this set currently in the player's bags/bank, if bank is available
+; missingItems: Number: Number of items in this set that are not currently available to the player.
+; ignoredSlots: Number: Number of inventory slots ignored by this set
+==Example==
-Finally, there is one very special slash command "/script", explained later.
+ local name, icon = GetEquipmentSetInfo(1);
+ if not name then
-== Macros ==
+  print("You have no equipment sets");
-{{Macronav}}
+ else
+  print("First equipment set: \124TInterface\\Icons\\" .. icon .. ":16\124t " .. name);
-The purpose of a [[Macro]] is to allow you to create some very simple custom actions or tasks, based on the existing game actions. A macro is just a sequence of slash commands, which are executed in order when you execute the macro. To create a new macro, either type "/macro" (without the quotes), or click on the speech bubble next to the chat box and select macro. You can then give a macro a name, an icon and type in a few lines of slash commands. The macro is created in the form of an action that you can drag onto your hotbar. You can activate the macro by clicking on the resulting button on the hotbar.
-An example macro would be:
- /cast Fireball(Rank 1)
- /say "I am frying it!"
-This macro merely casts a fireball, and then has your character tell everyone nearby that you're casting it.
-Macros have some severe limitations, and are only intended for very very simple tasks. The most important limitation is that it is difficult to cast more than one spell at a time using a macro (although it '''is''' possible, using [[API SpellStopCasting]]). This limitation exists so that macros can't automate too much for you. You can have as many other commands within the 255 character limit as you like.
-See also [http://forums.worldofwarcraft.com/board.html?forumId=11114&sid=1 The Blizzard World of Warcraft UI & Macros Forum] and [[HOWTO: Make a Macro]]
-== Scripts ==
-"Scripts" are computer programs written in a "scripting language".  Scripting languages are usually dynamic languages, and scripts do not require compilation in order to be executed (they are "interpreted").  Scripts and scripting languages are typically used to solve small to medium sized problems, and to create "throw away code" to quickly solve a problem at hand.  In principle however, scripts can solve the same kind of problems as lower level programming languages such as C++, albeit they might run slower.
-World of Warcraft has a powerful scripting language called [[Lua]] embedded.  This means that the WoW client can directly interpret and execute Lua programs.
-Lua scripts are used in the following places:
-* /script [command] : If you type the slash command "/script" in the chat box, you can follow it with one or more valid Lua language statements (i.e. a script), separated by semi-colons ( ; ).
-* Macros: you can enter scripts as part of macros, by putting one or more "/script" commands in your macro.
-* Addons: these extend the WoW client with new slash commands and often user interface elements.  This additional functionality is provided through Lua scripts (containing the actual addon logic).  User interface extensions are defined in XML files.
-So what can a script do? There are many resources on Lua scripts. See our page on [[Lua]] to find out more about the language. Browse the rest of the [[Interface Customization]] page for additional resources. The most important point however is that scripts are able to perform many more game actions than slash commands. This is done via a set of functions (called API or Application Programming Interface) that WoW makes available for use in scripts. There is a quite extensive list of all the API functions available for use in scripts at [[World of Warcraft API]].
-After all that explanation, here is an example of a script:
- if (IsPartyLeader()) then
-   ChatFrame1:AddMessage("I am the leader of my party!")
  end
+{{API Trail EquipmentManager}}
-This script is very simple. When you execute this script, if you are the party leader, then you get a message saying you are the party leader. To use this script, you would have to do so via the "/script" command. e.g.:
- /script if (IsPartyLeader()) then ChatFrame1:AddMessage("I am the leader of my party!"); end
-You can type this directly into the chat box, or make that line part of a macro, so that it's reusable.
-In summary: a script in WoW is a short program written in the Lua language, able to interact with the game and perform game actions. You use a script by including it as part of something else, e.g. by putting it in a macro via the /script command, or by putting it in an addon.
-== AddOns ==
-Blizzard has made the decision that the user interface of World of Warcraft is fully customizable, modifiable and extendable. This is completely legal, and is encouraged by Blizzard. A User Interface Modification (UI Mod for short) and AddOn is exactly the same thing, the difference is merely in their names. Usually "Mods" tend to refer to smaller things that only modify existing funcionality of the user interface, whereas AddOns tend to add extra functionality. From here on, we will simply use "AddOn".
-=== From a User's point of view ===
-From a user's point of view, what you need to know is that AddOns come in the form of one or more text files, ending in the ".toc", ".xml" and ".lua" extensions. These files are supposed to go into a folder called Interface in your World of Warcraft folder, or into one of its sub-folders. Usually AddOns are distributed as zip files by their authors, and you "install" them by simply unzipping them in your World of Warcraft\Interface folder.
-''Warning'': Be very very careful with AddOns that come as executable ".exe" files. Always triple-check before you use these to make sure that they really do what they say they do, as executable files can do anything whatsoever to your computer. AddOns are supposed to be written in text format in .xml and .lua files, so that anyone can check that there is nothing malicious about them. You have no such check available with executable files. Also, since AddOns only operate within WoW, they can't harm your computer, whereas executable files can.
-Having said that, some authors ''do'' distribute their AddOns as executable files. These executables most of the time don't do more than just unzip the AddOn's files and place them in your WoW folder in the appropriate places. Occasionally the executables are used to automatically download updated versions of the AddOn, or to upload data collected by the AddOn (for example item statistics to be put on a web-site, etc.).
-'''Uninstalling''': You can always uninstall any AddOn and reset the WoW UI to its clean default state by merely deleting or renaming the Interface, WTF, and Cache folders in your WoW folder, then restarting WoW.
-=== From a Developer's point of view ===
-AddOns mainly consist of two types of files:
-* [[Lua]] files, which contain the brunt of the logic
-* [[XML User Interface|XML]] files, which define how your dialogs, buttons, etc look. These elements are commonly referred to as "Widgets".
-You list these files in a [[The TOC Format|TOC]] (Table Of Contents) file together with some additional parameters.
-If you've been programming before, you may be used to having your program start, and keep running, until you don't want it to run any more. Not so in WoW. AddOns are ''event driven'', i.e. everything that happens does so in response to an event, e.g. the user clicking one of your buttons, the client receiving a chat message, someone hitting the character, etc. Those events are delivered to widgets, and to grab hold of them, you need to embed little snippets of Lua code in the right places that calls functions in the .lua files. &nbsp; It ''is'' possible to implement a whole addon in just the .xml files, but it gets clunky, and you need to HTML-encode &lt; and &gt; characters and so forth.
-Good places here on WoWWiki to look for more information:
-* [[Interface Customization]]
-* [[World of Warcraft API]]
-* [[XML User Interface]]
-* [[AddOns]] - a guide on how to create an addon from scratch
-* [[:Category:HOWTOs]]
-* [[XML Basic]] - needs help of pro addon developers to fill up reference
-External guides:
-* [http://wow.mmhell.com/articles/interface_modification/beginners_guide.html mmhell.com - A Beginner's Guide to Interface Modification - OUT OF DATE] (Marian 'Fyrn' R, Aug. 2004)
-* [http://wow.mmhell.com/articles/interface_modification/writing_your_first_addon.html mmhell.com - Your first AddOn - OUT OF DATE]
-=== Cosmos, Gypsy, CT_Mod and other AddOn packages ===
-If you look around the forums a bit, you will see names like [[Titan Panel]], [[Cosmos]], [[Gypsy]] and [[CT Mod]] popping up. These are major AddOn packages that contain a large number of UI AddOns. Their authors (often working in teams) are respectable members of the WoW community who have worked hard to create useful (and sometimes not-so-useful) AddOns for your gaming pleasure, and have bundled them together into one easy-to-use package.
-Feel free to use any and all of these packages. They are legal, Blizzard allows and encourages their use, although you won't get technical support from Blizzard if something is wrong with them. There are many of these around, download and try a few of them and see if you like them. Usually the authors make these packages highly configurable so that you can adjust them to your needs.
-Note: a lot of these major AddOn packages conflict with each other, so you won't be able to use them together.
-=== Standalone, pure AddOns, what is so good about them? ===
-You will sometimes see AddOn authors being proud of their AddOn being "standalone", or "pure addon". In the past, often AddOns modified existing UI functionality by changing something in the existing, core UI files provided by Blizzard. This has led to conflicts as different AddOns all tried to modify the same file. A "pure addon" is one that does not modify any existing files, and merely adds its own files. This is a very good thing, because you can have any number of such AddOns happily coexisting side-by-side. For this reason in WoW patch 1.10, Blizzard has completely disabled the ability to change the core UI files themselves. Therefore, all modifications to the UI can now only be done via pure AddOns. (Note that this doesn't mean that existing functionality of the UI can't be modified, it just means that it has to be done via an AddOn without modifying Blizzard's files themselves).
-Also, a lot of AddOns depend on other AddOns for their operation. For example, most AddOns in the Cosmos package wouldn't work by themselves, and need the whole Cosmos package to be present to work. A "standalone" AddOn is one that is capable of working by itself, with nothing more than just that one AddOn being present. Again, this is a good thing, because it allows you to pick and choose just those exact AddOns that you want, without having anything you don't want.  Many addons are aware of the major addon frameworks though and can interact with them if they're present.
-Having said that, from the point of view of an AddOn's author, you will find that often a lot of AddOns do very similar sort of things. It is much more easy and quick for an AddOn author to create a new AddOn if they can rely on existing functionality in other AddOns or some common core "libraries". That's why there are AddOns out there that depend on things such as the [[Sea]] function library, which in itself is just an AddOn. If you find an AddOn that requires some other core AddOn, don't be afraid of it. Just make sure you also download the core AddOn.
-== See also ==
-* The [[UI FAQ]]
-* The [[AddOns]] primer
-* [[:Category:AddOns]]
-* [[Interface Customization]]
-* [http://www.wowomg.com WOWOMG!]
-[[Category:Interface customization]]
-[[Category:FAQs]]
-[[Category:UI]]