Editing WoW:UI XML tutorial (section)

== Scripts ==

To attach behaviour to the UI elements defined in the XML files, you must use Lua. There are two methods of attaching Lua code to UI elements.

* Short codes can go directly in the XML files in the appropriate event handler element (see later).
* Long codes should go in a separate .lua file, and included via a Script element.

To include Lua code via a Script element, you must have one or more <Script> elements at the start of the XML file. For example:

 <Ui ... >
  <Script file="mycode.lua"/>
  <Frame name="MyFrame">
   ...
  </Frame>
 </Ui>

When the XML file is read, the contents of the ''mycode.lua'' file is read and interpreted. The code in that file is then available for the rest of this XML file, ''and'' any XML files that are read ''after'' this one. Functions that are defined in ''mycode.lua'' can be called from event handlers in the XML file.

=== Basic Event Handling concepts ===

''If you are not used to event handled programming, read this section, otherwise you can skip right through it.''

Traditional programming style involves writing a program that has a start and finish. Execution starts at the beginning, and after following through the algorithm in the program, it eventually gets to the end.

Event handled programming is somewhat different. In this case, you create several, independent sections of code, with no clear start or finish. Each of these sections of code are designed to be executed in response to a certain event occurring. Such a section of code is called an ''event handler''. An event handler may get executed once, many times, or maybe even never. This kind of programming style is used whenever you want your code to interact with an external program, and do things in response to whatever that program is doing.

In the case of [[World of Warcraft]], the core game is external to the interface code. Whenever something happens in the game, it asks the interface code to respond to it, by calling one of the event handlers.

=== Handling UI Events ===

To handle UI events, you must include event handler elements in your XML code. You do this by having a Scripts element, inside of which you have one or more Onxxxx event handler elements. For example:

 <Frame name="MyFrame">
  <Scripts>
   <OnShow>
    message("Hello!");
   </OnShow>
  </Scripts>
 </Frame>

This frame has one event handler only, which is executed every time this Frame becomes visible. The contents of the OnShow element can be any valid Lua code. In this example, it's a single statement, which calls the function '''message''', which causes a dialog box to pop up with "Hello" inside it. ('''message''' is a function defined in BasicControls.xml and is available by default.)

Here is a more complete example of how you include Lua code and then reference it from the event handlers.

'''mymod.xml''':

 <Ui ... >
   <Script file="mymod.lua"/>
   <Frame name="MyModMainFrame">
     <Scripts>
       <OnLoad>
         MyMod_ShowMessage();
       </OnLoad>
     </Scripts>
   </Frame>
 </Ui>

'''mymod.lua''':

 function MyMod_ShowMessage()
   message("Hello World!");
 end

When '''MyModMainFrame''' gets loaded (which happens once, at the start of the game, when all the XML files are read in), the OnLoad handler gets executed. In this case, the single Lua statement there simply calls the MyMod_ShowMessage function.

It is recommended that you prefix the names of all of your functions, UI objects and global variables with the name of your AddOn like above; all data is shared between Blizzard's own UI and all your addons, so picking a unique prefix helps avoid clashes with other people's code.

''For the above example to actually work, you must either create an AddOn with the mymod.lua and mymod.xml files, or include them in the FrameXML directory and reference myframe.xml from FrameXML.toc.'' See [[AddOns]] on how to combine these files into an AddOn.

=== Event Handler reference ===

[[Widget Handlers]] is a complete reference of what event handlers can be used by each object type.

* ''Note'': the OnEvent handler is special (see below).

You will notice that the event handlers in the list mostly cover UI related events. The '''OnEvent''' handler is special in that it is a general, collective handler for a large number of other events. It gets called for any of the remaining hundreds of game related events. See [[Events (API)|Events]] for a list of game events and how to register for them and handle them.