FANDOM


(Square One)
m
 
(17 intermediate revisions by 8 users not shown)
Line 1: Line 1:
  +
{{uiaddon}}
 
== Square One ==
 
== Square One ==
 
You have to start someplace, and the traditional place to start is with "Hello, World".
 
You have to start someplace, and the traditional place to start is with "Hello, World".
 
To accomplish this first task you will need the following items:
 
To accomplish this first task you will need the following items:
* World of Warcraft installed
+
* [[World of Warcraft]] (referred to as "WoW") installed
 
* An editor that can work with and save pure text.
 
* An editor that can work with and save pure text.
   
An AddOn lives in a very specific place. To find that place, first go to the World of Warcraft directory (also sometimes called a folder) using
+
An [[AddOn]] lives in a very specific place. To find that place, first go to the WoW directory (also sometimes called a folder) using whatever file management software you have available. On a Windows platform, that would be Windows Explorer (not Internet Explorer). The program is usually installed on the <tt>C:</tt> drive of the computer, under the directory's named "<tt>Program Files</tt>" or "<tt>Program Files (x86)</tt>" (on well supported 64-bit OSes like Windows 7). From pretty much any address bar, simply type "<tt>C:\Program Files\World of Warcraft</tt>" (or "<tt>C:\Program Files (x86)\World of Warcraft</tt>") and press enter.
whatever file management software you have available. On a Windows platform, that would be Windows Explorer (not Internet Explorer).
 
The program is usually installed on the C: drive of the computer, under the directory named "Program Files".
 
From pretty much any address bar, simply type "C:\Program Files\World of Warcraft" and press enter.
 
   
On a Macintosh system, you would use Finder and on Linux there is a similar mechanism.
+
On a Macintosh system, you would use Finder; and on Linux there is a similar mechanism. Whatever you use, you are looking for the installed location for WoW. This is usually at "<tt>/Applications/World of Warcraft/</tt>" on a Macintosh.
Whatever you use, you are looking for the installed location for World of Warcraft. This is usually at "/Applications/World of Warcraft/" on a Macintosh.
 
   
Once you find the World of Warcraft directory, there is another directory called Interface and within that is another called AddOns.
+
Once you find the WoW directory, there is another directory called Interface and within that is another called AddOns. AddOns is the home of all AddOns in WoW. Each AddOn has its own directory under the AddOns directory.
AddOns is the home of all AddOns in WoW. Each AddOn has its own directory under the AddOns directory.
 
   
 
Now go ahead and do these steps:
 
Now go ahead and do these steps:
* Create a directory for your AddOn named "HelloWorld"
+
* Create a directory for your AddOn named "<tt>HelloWorld</tt>"
* Create three files named: HelloWorld.toc, HelloWorld.lua, HelloWorld.xml
+
* Create three files named: <tt>HelloWorld.toc</tt>, <tt>HelloWorld.lua</tt>, <tt>HelloWorld.xml</tt>
Note that the only difference in the names is the suffix. These denote, in order, [[TOC format|Table of Contents]], the [[Lua]] code file, and the [[XML user interface]]
+
Note that the only difference in the names is the suffix. These denote, in order, [[TOC format|Table of Contents]], the [[Lua]] code file, and the [[XML user interface]] visual elements file. The name of your AddOn directory and the name on the <tt>.toc</tt> file must match.
visual elements file. The name of your AddOn directory and the name on the .toc file must match.
 
   
Now to put something into each of these files and this is where the editor that works with text files comes in.
+
Now to put something into each of these files, and this is where the editor that works with text files comes in. The files must be saved as text, not as some document format. Notepad is a pure text editor, but it is very limited. There are many out there, some of which can help with your programming efforts by understanding the syntax of the [[Lua]] language (more on that later). A favorite text editor is [http://www.ultraedit.com UltraEdit] (not free, but cross-platform: Windows, Mac, and Linux).
The files must be saved as text, not as some document format.
 
Notepad is a pure text editor, but it is very limited. There are many out there, some of which can help with your programming efforts by
 
understanding the syntax of the [[Lua]] language (more on that later). My personal favorite text editor is [http://www.ultraedit.com UltraEdit].
 
 
For additional Lua Editors check out the additional [[Lua editors]] page, with which [http://notepad-plus.sourceforge.net/uk/about.php Notepad++] is highly recommended, it comes with all the basic features of Notepad along with more advanced features for progressed programmers including syntax highlighting for LUA.
 
   
  +
For additional Lua Editors check out the additional [[Lua editors]] page, with which [http://notepad-plus-plus.org/ Notepad++] (MS Windows only) is highly recommended; it comes with all the basic features of Notepad along with more advanced features for progressed programmers including syntax highlighting for LUA.
   
 
=== The .toc or Table of Contents ===
 
=== The .toc or Table of Contents ===
This file tells WoW about your AddOn: what files to load and what order to load them in. Later you will want to peruse the [[TOC format]] page
+
This file tells WoW about your AddOn: what files to load and what order to load them in. Later you will want to peruse the [[TOC format]] page for all of the gory details about what you could put into this file. For now we are just going to give you some basic stuff to include.
for all of the gory details about what you could put into this file. For now we are just going to give you some basic stuff to include.
 
   
Using your trusted text file editor, place the following into the HelloWorld.toc file:
+
Using your trusted text file editor, place the following into the <tt>HelloWorld.toc</tt> file and save it:
## Interface: 40000
+
## Interface: 30300
## Title: Hello World!
+
## Title: Hello, World!
 
## Notes: My first AddOn
 
## Notes: My first AddOn
 
HelloWorld.lua
 
HelloWorld.lua
 
HelloWorld.xml
 
HelloWorld.xml
   
See the line with ## Interface: 40000 in it? By the time you try to follow this
+
See the line with ## Interface: 30300 in it? The 30300 is the TOC Version and the value shown is obsolete. You will need to put in the current value. WoW has a function, {{api|GetBuildInfo}}, which contains the current TOC Version and you can extract the number to your chat window by entering:
tutorial, that value will probably have changed and you will need to put in the current value. If you already have some AddOns installed,
+
<code>/run print((select(4, GetBuildInfo())));</code>
you can just look into their .toc file and see what they used. Another way is to visit http://wowcompares.com and look there.
+
in the chat input area. See [[Getting the current interface_number]].
You will want the TOC Build number for the latest Public Server version listed.
+
for other ways to get the TOC Version.
   
What is this number? It is the user interface (UI) version for the AddOn. The "40000" is version 4.00.00 (or 4.0.0). This number tells WoW
+
What is this number? The TOC Version is the user-interface (UI) version for the AddOn. The "30300" is version 3.03.00 (or 3.3.0). This number tells WoW that your AddOn is compatible with Blizzard UI level 3.3.0. If your TOC Version does not match the Blizzard UI number, your AddOn will be considered out of date. This is to minimize problems caused by old UI modifications hosing Blizzard's UI.
that your AddOn is compatible with Blizzard UI level 3.3.0. If your UI number does not match the Blizzard UI number, your AddOn will be
 
considered out of date. This is to minimize problems caused by old UI modifications hosing Blizzard's UI.
 
   
 
Starting from the first line we are saying:
 
Starting from the first line we are saying:
# The compatible UI version for this addon is 40000 (or 4.0.0)
+
# The compatible UI version for this addon is 30300 (or 3.3.0)
# The title of the addon to be displayed in game is "Hello World!"
+
# The title of the addon to be displayed in game is "Hello, World!"
 
# The description of the addon to be displayed in game are the notes
 
# The description of the addon to be displayed in game are the notes
 
# HelloWorld.lua file will be loaded.
 
# HelloWorld.lua file will be loaded.
 
# HelloWorld.xml file will be loaded.
 
# HelloWorld.xml file will be loaded.
 
As of December 18th 2010 the Interface code is 40000
 
   
 
For more details on stuff you can put in here, please visit the [[TOC format]] page.
 
For more details on stuff you can put in here, please visit the [[TOC format]] page.
   
 
=== The .lua or Lua code file ===
 
=== The .lua or Lua code file ===
The .lua files are where the main "what to do" instructions for the AddOn reside. You will see a variety of terms for this such as logic and
+
The .lua files are where the main "what to do" instructions for the add-on reside. You will see a variety of terms for this such as logic and executable code (or simply "code"). Lua logic, or executable code or a script, does its thing in response to something that happens in the game. Things that happen in the game are called Events.
executable code (or simply "code"). Lua logic, or executable code or a script, does its thing in response to something that happens in the game.
 
Things that happen in the game are called Events.
 
   
 
==== Events ====
 
==== Events ====
There are two basic kinds of events. The first kind of event is when something happens in the game. This might be somebody saying something,
+
There are two basic kinds of events. The first is when something happens in the game. This might be somebody saying something, something happening to your character, or another character's stats changing. Nearly everything that happens in the game causes events.
something happening to your character, another character's stats changing, nearly everything that happens in the game causes events.
 
The second kind of event is when you do something to a UI Element (a UI Element is something on the screen and is affectionately called a widget.
 
We'll get to that more in the next section). This second kind of event might be clicking on something in your bags or button bar.
 
There is a technical difference between the two types of events, and we will discuss that as the tutorial progresses.
 
For more detail on the first kind of event see [[Events (API)]] and for the second see [[Widget handlers]].
 
   
This discussion of events is extremely important because absolutely nothing happens in the game except in response to an event.
+
The second kind of event is when you do something to a UI Element (a UI Element is something on the screen and is affectionately called a widget. We'll get to that more in the next section). This second kind of event might be clicking on something in your bags or button bar. There is a technical difference between the two types of events, and we will discuss that as the tutorial progresses. For more detail on the first kind of event see [[Events (API)]] and for the second see [[Widget handlers]].
Further, should you happen to write a piece of code that runs for an extended time (perhaps forever) absoultely nothing new will happen in the game.
 
Your screen will be frozen and nothing will move. That would be classified as "not good".
 
   
So, how do you tell World of Warcraft that you are interested in a particular event? There are two ways: First, you can tell World of Warcraft which
+
These concepts are extremely important because absolutely nothing happens in the game except in response to an event. Furthermore, should you happen to write a piece of code that runs for an extended time (perhaps forever), absolutely nothing new will happen in the game. Your screen will be frozen and nothing will move. That would be classified as "not good".
code to run when a particular event happens. This is called registering your event. Second, you can tell the XML to run a piece of code when a
+
UI Element is manipulated (such as clicking on it or moving your mouse over it).
+
So, how do you tell WoW that you are interested in a particular event? There are two ways: first, you can tell WoW which code to run when a particular event happens. This is called registering your event. Second, you can tell the XML to run a piece of code when a UI Element is manipulated (such as clicking on it or moving your mouse over it). Pieces of code that run in response to events are called ''functions''.
These pieces of code that run in response to events are called functions.
 
   
 
==== Functions ====
 
==== Functions ====
Functions are groupings of code that accomplish a specific purpose. There are numerous pre-defined functions provided by World of Warcraft called
+
Functions are groupings of code that accomplish a specific purpose. There are numerous predefined functions provided by WoW (called API functions), or you can make your own user-defined functions. While there are multiple ways to create functions in Lua, the easiest to understand
API functions and you can make your own user-defined functions. While there are multiple ways to create functions in Lua the easiest to understand
 
 
looks like this:
 
looks like this:
   
Line 67: Line 67:
 
end
 
end
   
The <local> is an optional keyword that limits the visibility of the function to a particular scope. Scope will be covered in more depths shortly.<br />
+
*The <local> is an optional keyword that limits the visibility of the function to a particular scope. Scope will be covered in more depth shortly.
The ''function_name'' is simply a name you make up so you can reference your function from other parts of your AddOn.<br />
+
*The ''function_name'' is simply a name you make up so you can reference your function from other parts of your AddOn.
The <zero or more arguments> are ways to pass information into the function. This is what gives functions their power.<br />
+
*The <zero or more arguments> are ways to pass information into the function. This is what gives functions their power. Each time you call the function, you can supply a different set of arguments and get different results based upon them.
Each time you call the function, you can supply a different set of arguments and get different results based upon them.<br />
+
*The ... code ... is where the work gets done in a function. Here is where you do calculations, comparisons, call other functions, etc. to get the task of the function done.
The ... code ... is where the work gets done in a function. Here is where you do calculations, comparisons, call other functions, etc to get the
+
*The end simply marks the end of the definition of the function.
task of the function done.<br />
 
The end simply marks the end of the definition of the function.
 
   
Note that this only defines or declares the function. The function is not
+
Note that this only defines or declares the function. The function is not actually run until some other piece of code references (or calls) it.
actually run until some other piece of code references (or calls) it.
 
   
For more information on functions, please see the [http://www.lua.org/manual/5.1/ Lua 5.1 Reference Manual] or
+
For more information on functions, see the [http://www.lua.org/manual/5.1/ Lua 5.1 Reference Manual] or [http://www.lua.org/pil/ Programming in Lua (first edition)]. Also see the [[Lua]] page which lists more Lua resources.
[http://www.lua.org/pil/ Programming in Lua (first edition)]. Also see the [[Lua]] page which lists more Lua resources.
 
   
 
==== HelloWorld.lua ====
 
==== HelloWorld.lua ====
Now to continue with our Hello World code example. Please include the following into your HelloWorld.lua file and save it.
+
Now to continue with our Hello, World code example. Place the following into your HelloWorld.lua file and save it:
   
 
function HelloWorld()
 
function HelloWorld()
print("Hello World!");
+
print("Hello, World!");
end
+
end
   
You should understand everything in here by now. This function is named HelloWorld and it has zero arguments. The code part is simply the
+
You should understand everything in here by now. This function is named HelloWorld and it has zero arguments. The code part is simply the 'print("Hello, World!");' portion. And it ends with "end".
'print("Hello World!");' portion. And it ends with end.
 
   
This is a fine piece of code, and by itself is useless unless something calls the function. Onward to UI Elements (aka Widgets).
+
This is a fine piece of code, but by itself is useless unless something calls the function. Onward to UI Elements (aka Widgets).
   
   
 
=== The .xml or XML visual elements file ===
 
=== The .xml or XML visual elements file ===
UI Elements, or Widgets, are all of the tiny bits of graphics that make up the User Interface.
+
UI Elements, or Widgets, are all of the tiny bits of graphics that make up the User Interface. WoW uses XML to layout everything that you see on the screen. Additionally, when things happen (called Events, remember?) to the widgets on the screen, Widget Handlers can be called to perform whatever action you want. We will see shortly how we tell WoW which widgets we are interested in and which Events we want handled by which Widget Handler.
World of Warcraft uses XML to layout everything that you see on the screen. Additionally, when things happen (called Events, remember?) to
 
the widgets on the screen, Widget Handlers can be called to perform whatever action you want. We will see shortly how we tell WoW which
 
widgets we are interested in and which Events we want handled by which Widget Handler.
 
   
 
==== Blizzard XML format declared ====
 
==== Blizzard XML format declared ====
For those of you who don't know, XML stands for eXtensible Markup Language and is a means of tagging content with identifiers.
+
For those of you who don't know, XML stands for eXtensible Markup Language and is a means of tagging content with identifiers. What the identifiers are and how they are organized can be defined in something called a Schema. In our case, we want to create XML documents that WoW will understand, so we will use the Schema provided by Blizzard for the Wow User Interface.
What the identifiers are and how they are organized can be defined in something called a Schema. In our case, we want to create
 
XML documents that WoW will understand, so we will use the Schema provided by Blizzard for the Wow User Interface.
 
   
 
We declare that our document conforms to the Blizzard schema with the following bit of magic:
 
We declare that our document conforms to the Blizzard schema with the following bit of magic:
   
 
<nowiki><Ui xmlns="http://www.blizzard.com/wow/ui/"
 
<nowiki><Ui xmlns="http://www.blizzard.com/wow/ui/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.blizzard.com/wow/ui/
+
xsi:schemaLocation="http://www.blizzard.com/wow/ui/
..\..\FrameXML\UI.xsd"></nowiki>
+
..\..\FrameXML\UI.xsd"></nowiki>
 
 
</Ui>
+
</Ui>
   
The exact meaning of all of the above is beyond the scope of this tutorial. Consider it a magic formula that you always put in every
+
The exact meaning of all of the above is beyond the scope of this tutorial. Consider it a magic formula that you always put in every .xml file you will create for the WoW user interface. For those of you that like to reformat things, the first three lines can be merged into one line (use spaces), but the fourth line (..\..\FrameXML\UI.xsd"> ) needs to be on a line by itself starting in column 1.
.xml file you will create for the WoW user interface. For those of you that like to reformat things, the first three lines can be
 
merged to line line (use spaces), but the fourth line (..\..\FrameXML\UI.xsd"> ) needs to be on a line by itself starting in column 1.
 
   
There are a few general notes that you need to know about concerning XML, particularly as it is used by WoW.
+
There are a few general notes that you need to know about concerning XML, particularly as it is used by WoW. The generalized format of a tag is:
The generalized format of a tag is:
 
   
 
<tagname attribute="attribute value" anotherattribute="anotherattribute value">
 
<tagname attribute="attribute value" anotherattribute="anotherattribute value">
Line 112: Line 112:
 
</tagname>
 
</tagname>
   
A tag must have a tagname, and it may have zero or more attributes along with the attributes' associated values in double quotes.
+
A tag must have a tagname, and it may have zero or more attributes along with the attributes' associated values in double quotes. The tag is everything between the ''''<tagname'''' and the trailing ''''>''''. The tag is closed by an end tag with the same name as tag: ''''</tagname>''''. Tagnames do not have spaces, are case sensitive, start with a capital letter, and additional words are also capitalized. A valid tagname might be 'BackgroundWidgets', while 'backgroundwidgets' would not be valid. Blizzard defines all valid tagnames in their UI.xsd. The [[XML user interface]] page has a good list under [[XML user interface#Widget Elements|Widget Elements]] which will aid you until we get further along.
The tag is everything between the ''''<tagname'''' and the trailing ''''>''''. The tag is closed by an end tag with the same name as
 
tag: ''''</tagname>''''. Tagnames do not have spaces, are case sensitive, start with a capital letter, and additional words are also capitalized.
 
A valid tagname might be 'BackgroundWidgets', while 'backgroundwidgets' would not be valid. Blizzard defines all valid tagnames in their UI.xsd.
 
The [[XML user interface]] page has a good list under [[XML user interface#Widget Elements|Widget Elements]] which will aid you until we get further along.
 
   
Everything between the tag and the end tag is content to the tag. Everything. Even other tags along with their content.
+
Everything between the tag and the end tag is content to the tag. Everything. Even other tags along with their content. In the case where there is no content to a tag, the end of the tag has ''''/>'''' instead of just ''''>'''' and there is no separate end tag. A complete tag with no content looks like:
In the case where there is no content to a tag, the end of the tag has ''''/>'''' instead of just ''''>'''' and there is no separate end tag.
 
A complete tag with no content looks like:
 
   
 
<tagname attribute="attribute value" anotherattribute="anotherattribute value"/>
 
<tagname attribute="attribute value" anotherattribute="anotherattribute value"/>
   
Using the above piece of magic as an example, we can see that it is a tag with the name ''''Ui'''' and it has three attributes
+
Using the below piece of magic as an example, we can see that it is a tag with the name ''''Ui'''' and it has three attributes (the funny fourth line is a part of the prior attribute). Content is represented by the space between the end of the tag (the ''''>'''' on the fourth line) and the ''''</Ui>'''' end tag.
(the funny forth line is a part of the prior attribute).
 
Content is represented by the space between the end of the tag (the ''''>'''' on the fourth line) and the ''''</Ui>'''' end tag.
 
   
 
==== HelloWorld.xml ====
 
==== HelloWorld.xml ====
Now to continue with our Hello World XML example. Please edit your HelloWorld.xml file copy and paste this bit of magic into it:
+
Now to continue with our Hello, World XML example. Place the following into your HelloWorld.xml file and save it:
   
 
<nowiki><Ui xmlns="http://www.blizzard.com/wow/ui/"
 
<nowiki><Ui xmlns="http://www.blizzard.com/wow/ui/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.blizzard.com/wow/ui/
+
xsi:schemaLocation="http://www.blizzard.com/wow/ui/
..\..\FrameXML\UI.xsd"></nowiki>
+
..\..\FrameXML\UI.xsd"></nowiki>
 
 
</Ui>
+
</Ui>
   
Now before we create the frame for our addon, we have to add a simple line of code that tells the World of Warcraft engine where to find our function in our .lua file. Notice this is a tag with no content, which gets a '/>' and no end tag. This is because this tag is solely for the engine.
+
Now before we create the frame for our add-on, we have to add a simple line of code that tells the WoW engine where to find our function in our .lua file. Notice this is a tag with no content, which gets a '/>' and no end tag. This is because this tag is solely for the engine.
   
 
<Script File="HelloWorld.lua"/>
 
<Script File="HelloWorld.lua"/>
   
World of Warcraft connects everything to a frame, even other frames. So, in order to create something that WoW will interact with,
+
WoW connects everything to a frame, even other frames. So, in order to create something that WoW will interact with, we create a frame:
we create a frame:
 
   
 
<Frame name="HelloWorldFrame">
 
<Frame name="HelloWorldFrame">
Line 142: Line 142:
 
The tagname is ''''Frame'''' and we have used the ''''name'''' attribute and given the attribute the value of ''''HelloWorldFrame''''.
 
The tagname is ''''Frame'''' and we have used the ''''name'''' attribute and given the attribute the value of ''''HelloWorldFrame''''.
   
Our frame tag is included as content to the Ui tag and so goes between the start Ui tag and the end Ui tag.
+
Our frame tag is included as content to the Ui tag and so goes between the start Ui tag and the end Ui tag. To help keep track of what is surrounding what, we indent the content with respect to the enclosing tags like this:
To help keep track of what is surrounding what, we indent the content with respect to the enclosing tags like this:
 
   
 
<nowiki><Ui xmlns="http://www.blizzard.com/wow/ui/"
 
<nowiki><Ui xmlns="http://www.blizzard.com/wow/ui/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.blizzard.com/wow/ui/
+
xsi:schemaLocation="http://www.blizzard.com/wow/ui/
..\..\FrameXML\UI.xsd"></nowiki>
+
..\..\FrameXML\UI.xsd"></nowiki>
 
<Script File="HelloWorld.lua"/>
 
<Script File="HelloWorld.lua"/>
 
<Frame name="HelloWorldFrame">
 
<Frame name="HelloWorldFrame">
 
 
 
</Frame>
 
</Frame>
</Ui>
+
</Ui>
   
It is very important that you do not mix up the various end tags and indenting helps keep things straight. Notice that the ''''Frame'''' and ''''Script'''' tag (And for the ''''Frame'''' both the start tag and the end tag) are completely surrounded by the ''''Ui'''' tag.
+
It is very important that you do not mix up the various end tags, and indenting helps keep things straight. Notice that the ''''Frame'''' and ''''Script'''' tag (and for the ''''Frame'''' both the start tag and the end tag) are completely surrounded by the ''''Ui'''' tag.
   
Inside the frame, one of the many things we can define are Scripts. Scripts are nothing more than small pieces of Lua code. Where we place the script determines when it will be invoked. Because Scripts live within a Frame we include the ''''Scripts'''' tag inside the ''''Frame'''' tag. Notice the difference, in the ''''Scripts'''' tag, the 's' sets it apart from the ''''Script'''' tag.
+
Inside the frame, one of the many things we can define are Scripts. Scripts are nothing more than small pieces of Lua code. Where we place the script determines when it will be invoked. Because Scripts live within a Frame, we include the ''''Scripts'''' tag inside the ''''Frame'''' tag. Notice the difference, in the ''''Scripts'''' tag, the 's' sets it apart from the ''''Script'''' tag.
   
 
<Frame name="HelloWorldFrame">
 
<Frame name="HelloWorldFrame">
Line 164: Line 164:
 
</Frame>
 
</Frame>
   
The various widgets have several Events that can occur and if we want to declare a Widget Handler to process the event we include the event name under the Scripts tag of the widget we are interested in. Not every widget has the same set of events. In this example, we are interested in an event named ''''OnLoad''''. The OnLoad event happens when the widget is loaded into the UI. For this example, we want the OnLoad event to run the script named HelloWorld. This script was defined in the HelloWorld.lua as a function.
+
The various widgets have several Events that can occur; and if we want to declare a Widget Handler to process the event, we include the event name under the Scripts tag of the widget we are interested in. Not every widget has the same set of events. In this example, we are interested in an event named ''''OnLoad''''. The OnLoad event happens when the widget is loaded into the UI. For this example, we want the OnLoad event to run the script named HelloWorld. This script was defined in the HelloWorld.lua as a function.
   
 
<Scripts>
 
<Scripts>
Line 177: Line 177:
   
 
<nowiki><Ui xmlns="http://www.blizzard.com/wow/ui/"
 
<nowiki><Ui xmlns="http://www.blizzard.com/wow/ui/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.blizzard.com/wow/ui/
+
xsi:schemaLocation="http://www.blizzard.com/wow/ui/
..\..\FrameXML\UI.xsd"></nowiki>
+
..\..\FrameXML\UI.xsd"></nowiki>
 
<Script File="HelloWorld.lua"/>
 
<Script File="HelloWorld.lua"/>
 
<Frame name="HelloWorldFrame">
 
<Frame name="HelloWorldFrame">
Line 188: Line 188:
 
</Scripts>
 
</Scripts>
 
</Frame>
 
</Frame>
</Ui>
+
</Ui>
   
There is an important item you should note in the above. The '''''HelloWorld();''''' is the only piece which is NOT a tag or an attribute.
+
There is an important item you should note in the above: the '''''HelloWorld();''''' is the only piece which is NOT a tag or an attribute. It is important to note that content in a WoW .xml UI document is always a piece of code if it is not another set of tags and their associated attributes. The only valid place for a piece of code is under the tag for an event.
It is important to note that content in a WoW .xml UI document is always a piece of code if it is not another set of tags and their associated
 
attributes. The only valid place for a piece of code is under the tag for an event.
 
   
Having gotten this far, it is time to run your new AddOn.
+
Having gotten this far, it is time to run your new add-on.
   
 
=== Running your HelloWorld AddOn ===
 
=== Running your HelloWorld AddOn ===
You should have a directory under your AddOns directory named "HelloWorld" and in that directory should be three files named HelloWorld.toc,
+
You should have a directory under your AddOns directory named "HelloWorld" and in that directory should be three files named HelloWorld.toc, HelloWorld.lua, and HelloWorld.xml. The contents of these three files should be EXACTLY as described above.
HelloWorld.lua, and HelloWorld.xml. The contents of these three files should be EXACTLY as noted above.
 
   
Now start World of Warcraft and log into your account, but don't select your character yet.
+
Now start WoW and log into your account, but don't select your character yet. Click the red ''''AddOns'''' button on the lower left of the character-selection screen to see all of the AddOns WoW has detected; there will be one for every folder in your AddOns directory except for the AddOns starting with Blizzard_.
Please click the red ''''AddOns'''' button on the lower left of the character selection screen to see all of the AddOns WoW has detected.
 
There will be one for every folder in your AddOns directory except for the AddOns starting with Blizzard_.
 
   
You should see your new HelloWorld in this list. The name should be yellow, and the checkbox to the left should be checked.
+
You should see your new HelloWorld in this list. The name should be yellow, and the checkbox to the left should be checked.
   
If the name is Red and you see an '''Out of date''' message to the right, you probably didn't change the '''## Interface: 30300'''
+
If the name is red and you see an '''Out of date''' message to the right, you probably didn't change the '''## Interface: 30300''' value as described above under [[#The .toc or Table of Contents|The .toc or Table of Contents]]. Review that section and make the appropriate change. Running your AddOns with the 'Load out of date AddOns' checkbox checked is not recommended. That's asking for trouble as an AddOn that attempts to use old UI features can corrupt a new UI. Nearly every patch that changes the UI level has had problems with old AddOns that have not been updated to conform to the new UI standards.
value as described above under [[#The .toc or Table of Contents|The .toc or Table of Contents]]. Please review that section and make the appropriate change.
 
I do not recommend running your AddOns with the 'Load out of date AddOns' checkbox checked. That's asking for trouble as an AddOn that
 
attempts to use old UI features can corrupt a new UI. Nearly every patch that changes the UI level has had problems with old AddOns that
 
have not been updated to conform to the new UI standards.
 
   
If you don't see the name at all, make sure that you have placed the HelloWorld directory in the AddOns directory which is in the Interface directory
+
If you don't see the name at all, make sure that you have placed the HelloWorld directory in the AddOns directory, which is in the Interface directory under the WoW installation location. On a Windows system, it would be 'C:\Program Files\World of Warcraft\Interface\AddOns\HelloWorld'. The files inside that directory should all start with 'HelloWorld' and have the .toc, .lua, and .xml endings.
under the World of Warcraft installation location. On my system (Windows) it is 'C:\Program Files\World of Warcraft\Interface\AddOns\HelloWorld'.
 
The files inside that directory should all start with 'HelloWorld' and have the .toc, .lua, and .xml endings.
 
   
A note, for windows users; ensure that you have not saved the files as HelloWorld.toc.txt etc, as an option in windows explorer will hide the .txt on the end.
+
A note for Windows users; make sure that you have not saved the files as HelloWorld.toc.txt, etc., as an option in Windows Explorer will hide the .txt on the end.
   
Please note the CaSe of the names. While Windows is insensitive to case for directory and file names, the case is important to other systems (e.g. Mac, Linux)
+
Please note the CaSe of the names. While Windows is insensitive to case for directory and file names, the case is important to other systems (e.g. Mac, Linux). Also, inside the game itself, WoW is sensitive to the case for the names of its variables and filenames. Keep the case the same to avoid problems.
Also, inside the game itself, World of Warcraft is sensitive to the case for the names of its variables and filenames.
 
Keep the case the same to avoid problems.
 
   
Now, you have a yellow HelloWorld! showing up in your AddOn list. Note the ! in the name. The name of the AddOn shown in this list is taken from
+
Now you have a yellow Hello, World! showing up in your AddOn list. Note the ! in the name. The name of the AddOn shown in this list is taken from the '''## Title: Hello, World!''' line in the HelloWorld.toc file. In the future, we will see how to change colors and languages.
the '''## Title: Hello World!''' line in the HelloWorld.toc file. In the future, we will see how to change colors and languages.
 
   
If you move your mouse cursor over the HelloWorld name, you should see a tool-tip pop up with two lines in it. The first line is the same as the
+
If you move your mouse cursor over the Hello, World! name, you should see a tool-tip pop up with two lines in it. The first line is the same as the Title, and the second line is taken from the '''## Notes: My first AddOn''' line in the .toc file. This can also be customized for color and language.
Title, and the second line is taken from the '''## Notes: My first AddOn''' line in the .toc file. This can also be customized for color and language.
 
   
Cancel out of the AddOns display and enter the world with any of your characters.
+
Cancel out of the AddOns display and enter the world with any of your characters. Once your character loads, you should see a message in the default chat window that says "'''Hello, World!'''".
Once your character loads, you should see a message in the default chat window that says '''Hello World!''' .
 
   
 
Success!!
 
Success!!
   
 
== Review ==
 
== Review ==
You have created your first AddOn and have successfully run it. Now let's review a bit about what was accomplished.
+
You have created your first AddOn and have successfully run it. Now let's review a bit about what was accomplished.
   
The 'Hello World!' text is taken from the line in the HelloWorld.lua file that reads 'print("Hello World!");'.
+
The 'Hello, World!' text is taken from the line in the HelloWorld.lua file that reads 'print("Hello, World!");'. Wrapped around that is a function named "print" which is responsible for displaying the text in the default chat window.
Wrapped around that is a function named print which is responsible for displaying the text in the default chat window.
 
   
The print function is inside a function we created called HelloWorld that had no parameters. Our function will do the same thing every time
+
The print function is inside a function we created called "HelloWorld" that had no parameters. Our function will do the same thing every time it is called.
it is called.
 
   
You should then recall that the name of our function was placed in the HelloWorld.xml file as the action to be taken when the ''Onload'' event
+
The name of our function was then placed in the HelloWorld.xml file as the action to be taken when the ''Onload'' event of the ''Scripts'' tag of the Frame we created. We placed the name of our function in this specific place because we wanted our function to be executed (run, called, processed) when our Frame was fully loaded.
of the ''Scripts'' tag of the Frame we created. We placed the name of our function in this specific place because we wanted our function to be
 
executed (run, called, processed) when our Frame was fully loaded.
 
   
World of Warcraft knew that it should create our Frame because we placed the name of the .xml file into the .toc file.
+
WoW knew that it should create our Frame because we placed the name of the .xml file into the .toc file. The .toc file must have the same name as the AddOn's directory and is the first of the files in our AddOn that Blizzard processes.
The .toc file must have the same name as the AddOn's directory and is the first of the files in our AddOn that Blizzard processes.
 
   
Inside the .toc file is where we tell World of Warcraft about our AddOn (the ## statements) and what files that need to be loaded.
+
Inside the .toc file is where we tell WoW about our AddOn (the ## statements) and what files that need to be loaded. Every line that does not start with a ## is a file to be processed by WoW. The order in which the file names appear is important because WoW processes the files in the order listed.
Every line that does not start with a ## is a file to be processed by World of Warcraft.
 
The order that the file names appear is important because World of Warcraft processes the file in order listed.
 
   
Knowing that, we place the .lua file before the .xml file because we want the function HelloWorld declared (or defined) before we try to
+
Knowing this, we place the .lua file before the .xml file because we want the function HelloWorld declared (or defined) before we try to call it in the .xml file.
call it in the .xml file.
 
   
Even though this is a trivial example of an AddOn , important concepts and information have been covered.
+
Even though this is a trivial example of an AddOn, important concepts and information have been covered. Further pages in this tutorial will cover other areas and expand upon topics initially presented here.
Further pages in this tutorial will cover other areas and expand upon topics initially presented here.
 
   
 
== More ==
 
== More ==
* [[AddOn programming tutorial]] - The index page. Also contains references used throughout this tutorial.
+
* [[AddOn programming tutorial]] - The index page. Also contains references used throughout this tutorial.
 
[[Category:Interface customization]]
 
[[Category:Interface customization]]
 
[[Category:UI]]
 
[[Category:UI]]

Latest revision as of 18:54, September 21, 2013

WoW AddOn

Square One Edit

You have to start someplace, and the traditional place to start is with "Hello, World". To accomplish this first task you will need the following items:

  • World of Warcraft (referred to as "WoW") installed
  • An editor that can work with and save pure text.

An AddOn lives in a very specific place. To find that place, first go to the WoW directory (also sometimes called a folder) using whatever file management software you have available. On a Windows platform, that would be Windows Explorer (not Internet Explorer). The program is usually installed on the C: drive of the computer, under the directory's named "Program Files" or "Program Files (x86)" (on well supported 64-bit OSes like Windows 7). From pretty much any address bar, simply type "C:\Program Files\World of Warcraft" (or "C:\Program Files (x86)\World of Warcraft") and press enter.

On a Macintosh system, you would use Finder; and on Linux there is a similar mechanism. Whatever you use, you are looking for the installed location for WoW. This is usually at "/Applications/World of Warcraft/" on a Macintosh.

Once you find the WoW directory, there is another directory called Interface and within that is another called AddOns. AddOns is the home of all AddOns in WoW. Each AddOn has its own directory under the AddOns directory.

Now go ahead and do these steps:

  • Create a directory for your AddOn named "HelloWorld"
  • Create three files named: HelloWorld.toc, HelloWorld.lua, HelloWorld.xml

Note that the only difference in the names is the suffix. These denote, in order, Table of Contents, the Lua code file, and the XML user interface visual elements file. The name of your AddOn directory and the name on the .toc file must match.

Now to put something into each of these files, and this is where the editor that works with text files comes in. The files must be saved as text, not as some document format. Notepad is a pure text editor, but it is very limited. There are many out there, some of which can help with your programming efforts by understanding the syntax of the Lua language (more on that later). A favorite text editor is UltraEdit (not free, but cross-platform: Windows, Mac, and Linux).

For additional Lua Editors check out the additional Lua editors page, with which Notepad++ (MS Windows only) is highly recommended; it comes with all the basic features of Notepad along with more advanced features for progressed programmers including syntax highlighting for LUA.

The .toc or Table of Contents Edit

This file tells WoW about your AddOn: what files to load and what order to load them in. Later you will want to peruse the TOC format page for all of the gory details about what you could put into this file. For now we are just going to give you some basic stuff to include.

Using your trusted text file editor, place the following into the HelloWorld.toc file and save it:

## Interface: 30300
## Title: Hello, World!
## Notes: My first AddOn
HelloWorld.lua
HelloWorld.xml

See the line with ## Interface: 30300 in it? The 30300 is the TOC Version and the value shown is obsolete. You will need to put in the current value. WoW has a function, GetBuildInfo, which contains the current TOC Version and you can extract the number to your chat window by entering:

/run print((select(4, GetBuildInfo())));

in the chat input area. See Getting the current interface_number. for other ways to get the TOC Version.

What is this number? The TOC Version is the user-interface (UI) version for the AddOn. The "30300" is version 3.03.00 (or 3.3.0). This number tells WoW that your AddOn is compatible with Blizzard UI level 3.3.0. If your TOC Version does not match the Blizzard UI number, your AddOn will be considered out of date. This is to minimize problems caused by old UI modifications hosing Blizzard's UI.

Starting from the first line we are saying:

  1. The compatible UI version for this addon is 30300 (or 3.3.0)
  2. The title of the addon to be displayed in game is "Hello, World!"
  3. The description of the addon to be displayed in game are the notes
  4. HelloWorld.lua file will be loaded.
  5. HelloWorld.xml file will be loaded.

For more details on stuff you can put in here, please visit the TOC format page.

The .lua or Lua code file Edit

The .lua files are where the main "what to do" instructions for the add-on reside. You will see a variety of terms for this such as logic and executable code (or simply "code"). Lua logic, or executable code or a script, does its thing in response to something that happens in the game. Things that happen in the game are called Events.

Events Edit

There are two basic kinds of events. The first is when something happens in the game. This might be somebody saying something, something happening to your character, or another character's stats changing. Nearly everything that happens in the game causes events.

The second kind of event is when you do something to a UI Element (a UI Element is something on the screen and is affectionately called a widget. We'll get to that more in the next section). This second kind of event might be clicking on something in your bags or button bar. There is a technical difference between the two types of events, and we will discuss that as the tutorial progresses. For more detail on the first kind of event see Events (API) and for the second see Widget handlers.

These concepts are extremely important because absolutely nothing happens in the game except in response to an event. Furthermore, should you happen to write a piece of code that runs for an extended time (perhaps forever), absolutely nothing new will happen in the game. Your screen will be frozen and nothing will move. That would be classified as "not good".

So, how do you tell WoW that you are interested in a particular event? There are two ways: first, you can tell WoW which code to run when a particular event happens. This is called registering your event. Second, you can tell the XML to run a piece of code when a UI Element is manipulated (such as clicking on it or moving your mouse over it). Pieces of code that run in response to events are called functions.

Functions Edit

Functions are groupings of code that accomplish a specific purpose. There are numerous predefined functions provided by WoW (called API functions), or you can make your own user-defined functions. While there are multiple ways to create functions in Lua, the easiest to understand looks like this:

<local> function function_name(<zero or more arguments>)
   ... code ...
end
  • The <local> is an optional keyword that limits the visibility of the function to a particular scope. Scope will be covered in more depth shortly.
  • The function_name is simply a name you make up so you can reference your function from other parts of your AddOn.
  • The <zero or more arguments> are ways to pass information into the function. This is what gives functions their power. Each time you call the function, you can supply a different set of arguments and get different results based upon them.
  • The ... code ... is where the work gets done in a function. Here is where you do calculations, comparisons, call other functions, etc. to get the task of the function done.
  • The end simply marks the end of the definition of the function.

Note that this only defines or declares the function. The function is not actually run until some other piece of code references (or calls) it.

For more information on functions, see the Lua 5.1 Reference Manual or Programming in Lua (first edition). Also see the Lua page which lists more Lua resources.

HelloWorld.lua Edit

Now to continue with our Hello, World code example. Place the following into your HelloWorld.lua file and save it:

function HelloWorld() 
  print("Hello, World!"); 
end

You should understand everything in here by now. This function is named HelloWorld and it has zero arguments. The code part is simply the 'print("Hello, World!");' portion. And it ends with "end".

This is a fine piece of code, but by itself is useless unless something calls the function. Onward to UI Elements (aka Widgets).


The .xml or XML visual elements file Edit

UI Elements, or Widgets, are all of the tiny bits of graphics that make up the User Interface. WoW uses XML to layout everything that you see on the screen. Additionally, when things happen (called Events, remember?) to the widgets on the screen, Widget Handlers can be called to perform whatever action you want. We will see shortly how we tell WoW which widgets we are interested in and which Events we want handled by which Widget Handler.

Blizzard XML format declared Edit

For those of you who don't know, XML stands for eXtensible Markup Language and is a means of tagging content with identifiers. What the identifiers are and how they are organized can be defined in something called a Schema. In our case, we want to create XML documents that WoW will understand, so we will use the Schema provided by Blizzard for the Wow User Interface.

We declare that our document conforms to the Blizzard schema with the following bit of magic:

<Ui xmlns="http://www.blizzard.com/wow/ui/" 
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                   xsi:schemaLocation="http://www.blizzard.com/wow/ui/ 
                   ..\..\FrameXML\UI.xsd">

</Ui>

The exact meaning of all of the above is beyond the scope of this tutorial. Consider it a magic formula that you always put in every .xml file you will create for the WoW user interface. For those of you that like to reformat things, the first three lines can be merged into one line (use spaces), but the fourth line (..\..\FrameXML\UI.xsd"> ) needs to be on a line by itself starting in column 1.

There are a few general notes that you need to know about concerning XML, particularly as it is used by WoW. The generalized format of a tag is:

<tagname attribute="attribute value" anotherattribute="anotherattribute value">

</tagname>

A tag must have a tagname, and it may have zero or more attributes along with the attributes' associated values in double quotes. The tag is everything between the '<tagname' and the trailing '>'. The tag is closed by an end tag with the same name as tag: '</tagname>'. Tagnames do not have spaces, are case sensitive, start with a capital letter, and additional words are also capitalized. A valid tagname might be 'BackgroundWidgets', while 'backgroundwidgets' would not be valid. Blizzard defines all valid tagnames in their UI.xsd. The XML user interface page has a good list under Widget Elements which will aid you until we get further along.

Everything between the tag and the end tag is content to the tag. Everything. Even other tags along with their content. In the case where there is no content to a tag, the end of the tag has '/>' instead of just '>' and there is no separate end tag. A complete tag with no content looks like:

<tagname attribute="attribute value" anotherattribute="anotherattribute value"/>

Using the below piece of magic as an example, we can see that it is a tag with the name 'Ui' and it has three attributes (the funny fourth line is a part of the prior attribute). Content is represented by the space between the end of the tag (the '>' on the fourth line) and the '</Ui>' end tag.

HelloWorld.xml Edit

Now to continue with our Hello, World XML example. Place the following into your HelloWorld.xml file and save it:

<Ui xmlns="http://www.blizzard.com/wow/ui/" 
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                   xsi:schemaLocation="http://www.blizzard.com/wow/ui/ 
                   ..\..\FrameXML\UI.xsd">

</Ui>

Now before we create the frame for our add-on, we have to add a simple line of code that tells the WoW engine where to find our function in our .lua file. Notice this is a tag with no content, which gets a '/>' and no end tag. This is because this tag is solely for the engine.

 <Script File="HelloWorld.lua"/>

WoW connects everything to a frame, even other frames. So, in order to create something that WoW will interact with, we create a frame:

 <Frame name="HelloWorldFrame">

 </Frame>

The tagname is 'Frame' and we have used the 'name' attribute and given the attribute the value of 'HelloWorldFrame'.

Our frame tag is included as content to the Ui tag and so goes between the start Ui tag and the end Ui tag. To help keep track of what is surrounding what, we indent the content with respect to the enclosing tags like this:

<Ui xmlns="http://www.blizzard.com/wow/ui/" 
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                   xsi:schemaLocation="http://www.blizzard.com/wow/ui/ 
                   ..\..\FrameXML\UI.xsd">
  <Script File="HelloWorld.lua"/>
  <Frame name="HelloWorldFrame">

  </Frame>
</Ui>

It is very important that you do not mix up the various end tags, and indenting helps keep things straight. Notice that the 'Frame' and 'Script' tag (and for the 'Frame' both the start tag and the end tag) are completely surrounded by the 'Ui' tag.

Inside the frame, one of the many things we can define are Scripts. Scripts are nothing more than small pieces of Lua code. Where we place the script determines when it will be invoked. Because Scripts live within a Frame, we include the 'Scripts' tag inside the 'Frame' tag. Notice the difference, in the 'Scripts' tag, the 's' sets it apart from the 'Script' tag.

 <Frame name="HelloWorldFrame">
  <Scripts>

  </Scripts>
 </Frame>

The various widgets have several Events that can occur; and if we want to declare a Widget Handler to process the event, we include the event name under the Scripts tag of the widget we are interested in. Not every widget has the same set of events. In this example, we are interested in an event named 'OnLoad'. The OnLoad event happens when the widget is loaded into the UI. For this example, we want the OnLoad event to run the script named HelloWorld. This script was defined in the HelloWorld.lua as a function.

  <Scripts>
   <OnLoad>
    HelloWorld();
   </OnLoad>
  </Scripts>

Take a look at the Widget handlers page for a list of widgets and the events you can write widget handlers for.

The complete HelloWorld.xml file should look like this:

<Ui xmlns="http://www.blizzard.com/wow/ui/" 
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                   xsi:schemaLocation="http://www.blizzard.com/wow/ui/ 
                   ..\..\FrameXML\UI.xsd">
  <Script File="HelloWorld.lua"/>
  <Frame name="HelloWorldFrame">
   <Scripts>
    <OnLoad>
     HelloWorld();
    </OnLoad>
   </Scripts>
  </Frame>
</Ui>

There is an important item you should note in the above: the HelloWorld(); is the only piece which is NOT a tag or an attribute. It is important to note that content in a WoW .xml UI document is always a piece of code if it is not another set of tags and their associated attributes. The only valid place for a piece of code is under the tag for an event.

Having gotten this far, it is time to run your new add-on.

Running your HelloWorld AddOn Edit

You should have a directory under your AddOns directory named "HelloWorld" and in that directory should be three files named HelloWorld.toc, HelloWorld.lua, and HelloWorld.xml. The contents of these three files should be EXACTLY as described above.

Now start WoW and log into your account, but don't select your character yet. Click the red 'AddOns' button on the lower left of the character-selection screen to see all of the AddOns WoW has detected; there will be one for every folder in your AddOns directory except for the AddOns starting with Blizzard_.

You should see your new HelloWorld in this list. The name should be yellow, and the checkbox to the left should be checked.

If the name is red and you see an Out of date message to the right, you probably didn't change the ## Interface: 30300 value as described above under The .toc or Table of Contents. Review that section and make the appropriate change. Running your AddOns with the 'Load out of date AddOns' checkbox checked is not recommended. That's asking for trouble as an AddOn that attempts to use old UI features can corrupt a new UI. Nearly every patch that changes the UI level has had problems with old AddOns that have not been updated to conform to the new UI standards.

If you don't see the name at all, make sure that you have placed the HelloWorld directory in the AddOns directory, which is in the Interface directory under the WoW installation location. On a Windows system, it would be 'C:\Program Files\World of Warcraft\Interface\AddOns\HelloWorld'. The files inside that directory should all start with 'HelloWorld' and have the .toc, .lua, and .xml endings.

A note for Windows users; make sure that you have not saved the files as HelloWorld.toc.txt, etc., as an option in Windows Explorer will hide the .txt on the end.

Please note the CaSe of the names. While Windows is insensitive to case for directory and file names, the case is important to other systems (e.g. Mac, Linux). Also, inside the game itself, WoW is sensitive to the case for the names of its variables and filenames. Keep the case the same to avoid problems.

Now you have a yellow Hello, World! showing up in your AddOn list. Note the ! in the name. The name of the AddOn shown in this list is taken from the ## Title: Hello, World! line in the HelloWorld.toc file. In the future, we will see how to change colors and languages.

If you move your mouse cursor over the Hello, World! name, you should see a tool-tip pop up with two lines in it. The first line is the same as the Title, and the second line is taken from the ## Notes: My first AddOn line in the .toc file. This can also be customized for color and language.

Cancel out of the AddOns display and enter the world with any of your characters. Once your character loads, you should see a message in the default chat window that says "Hello, World!".

Success!!

Review Edit

You have created your first AddOn and have successfully run it. Now let's review a bit about what was accomplished.

The 'Hello, World!' text is taken from the line in the HelloWorld.lua file that reads 'print("Hello, World!");'. Wrapped around that is a function named "print" which is responsible for displaying the text in the default chat window.

The print function is inside a function we created called "HelloWorld" that had no parameters. Our function will do the same thing every time it is called.

The name of our function was then placed in the HelloWorld.xml file as the action to be taken when the Onload event of the Scripts tag of the Frame we created. We placed the name of our function in this specific place because we wanted our function to be executed (run, called, processed) when our Frame was fully loaded.

WoW knew that it should create our Frame because we placed the name of the .xml file into the .toc file. The .toc file must have the same name as the AddOn's directory and is the first of the files in our AddOn that Blizzard processes.

Inside the .toc file is where we tell WoW about our AddOn (the ## statements) and what files that need to be loaded. Every line that does not start with a ## is a file to be processed by WoW. The order in which the file names appear is important because WoW processes the files in the order listed.

Knowing this, we place the .lua file before the .xml file because we want the function HelloWorld declared (or defined) before we try to call it in the .xml file.

Even though this is a trivial example of an AddOn, important concepts and information have been covered. Further pages in this tutorial will cover other areas and expand upon topics initially presented here.

More Edit

Community content is available under CC-BY-SA unless otherwise noted.