UI XML tutorial This is a tutorial and reference for using WoW UI XML . " Note : this guide assumes familiarity with XML ; for a quick introduction , see XML basics . " Preface . As a bit of a primer for this guide , here is a short list of XML element types , to give some perspective as you work through the next sections . See : XML types , XML attributes and XML elements , later for a more complete list of WoW UI XML references . " Keep in mind that there is no official Blizzard documentation for any of this . " For description and properties of each element follow link below . Example Types . " These are usually first in the XML file . " " These begin to actually define screen elements , and are later in the XML file . " Introduction . World of Warcraft has a fairly powerful layout engine for creating user interfaces . When combined with Lua for attaching behaviours to UI elements , this creates a flexible system with which the game ' s entire UI is created , as well as any custom AddOns . The XML and the WoW XML UI serve as a fundemental component of this . If you are unfamiliar with XML , consider visiting the XML Basics guide . For more information on creating AddOns , see AddOns , Interface Customization , World of Warcraft API and especially the Widget API which describes the programming aspects of all XML objects . A more detailed reference to all the XML elements WoW UI uses can be found under XML elements . Also note that the XML declaration ( codice _ 1 ) may be omitted from UI . xml files . Also note that as of version 1 . 10 , all types of frames can also be created from Lua with the new CreateFrame ( ) API . The Basics . An XML file is a collection of " elements " ( with a start and end tag ) , of which the User Interface files are no exception . There are two main types of elements that appear in the UI XML files . The first type are those that declare user interface items ( or widgets ) , such as Buttons , Frames , Checkboxes . We will call these widget elements . The second type of element , which always occur inside the first type , define properties and behaviour of the widgets . We will call these property elements . Here is an example : The Button element is of the first type , in other words a widget element . Its appearance in the XML file causes a Button with the name MyAddon _ Button to be created . The elements inside it ( such as Anchors , Anchor ) define its properties , hence are of the second type . The general structure is always the same , you have elements representing widgets , and other elements inside them representing their properties . It can also happen that a widget element is inside another one . For example : This example has two widget elements ( Frame and Button ) , and several property elements ( Anchors , Anchor ) . This creates a Frame , with a Button inside it . Here , MyAddon _ Button is a " child " of MyAddon _ Frame , and MyAddon _ Frame is a " parent " of MyAddon _ Button . Also note how the XML convention of abbreviating an empty element such as < Anchor point = " CENTER " > < / Anchor > as < Anchor point = " CENTER " / > is used . Many of the elements ( widget and property alike ) can have " attributes " , such as the name attribute in the above examples . A complete and valid XML file must contain exactly one element named UI , with some rather long attributes ( best use copy / paste for this ) . Hence a minimal example of a complete UI XML file would be something like : Such a file will create a single Frame , named MyAddon _ Frame . However , that Frame wouldn ' t be visible and wouldn ' t have any content . Validation with XSD . If you use the Blizzard Interface Customization tool to extract the contents of the Interface \ FrameXML folder , you will come across the file UI . xsd which provides a schema definition for automated validation of your customized XML - files . Notice that XSD is an advanced XML feature and requires a special editor as well as a good knowledge of advanced XML - concepts . If you ' ve already worked with XML you might find this very helpful to get started with WoW . There is also an online validator available , which will take any XML you throw at it and check it against Blizzard ' s schema definitions . Unfortunately , it is not much use as a " getting started " reference , but rather it is much more useful to check what is going wrong should you lack access to the heavier tools that support XML editing with XSD support natively . Further , due to the way that the XSD was designed , it can some times throw errors which are not actually a problem . Be sure to check the FAQ for more information . Naming Widgets . Every widget element may have the name attribute . If an element has a name , it causes a global Lua variable to be created with that name . This variable can then be used to call API methods on that widget . ( See Widget API for a list of methods available for the different UI widgets . ) Note that global variables are truly global across the entire UI , meaning that every name must be unique across all XML files . Here is an example . Let ' s say in your XML file you have a section like this : In any Lua code then you can use the variable MyAddon _ Frame to refer to the frame and MyAddon _ Button to refer to the button . For example , to show the frame , call MyAddon _ Frame : Show ( ) . Or to disable the button , call MyAddon _ Button : Disable ( ) . When defining the name of a widget , the special string $ parent may be used . This will take on the name of whatever the parent of that widget is . For example : This results in two global Lua variables : MyAddon _ Frame and MyAddon _ Frame _ Button . Managing Frames . " Note : " A lot of this section applies to all user interface widgets , not just Frames . Properties for layout , sizing and so on are common to all widgets . Layout . Frames have a combination of a size and one or more anchors . For a frame to be laid out , the combination of these needs to define a rectangle on the screen in which the frame is to be laid out . A size is specified using a Size element with either an AbsDimension or RelDimension child element . Anchors allow for relative positioning , and also to allow frames to dynamically reposition their content based on resizing . A group of anchors is expressed via an Anchors element with one or more Anchor children , each of which may have an Offset . Some examples : " TODO : Get screenshots of all of these " This specifies a 100x100 frame anchored so that its top left is at the top left of its parent frame . This specifies a frame that covers a quarter of your UI ( regardless to the selected resolution ) . This specifies a 100x100 frame anchored so that its top left is at the top right of its parent frame . This specifies a 100x100 frame anchored at the top left of the frame SomeOtherFrame , and offset by 10 pixels to the right and 10 pixels down . ( Note that the Y axis increases from the bottom up , so negative Y coordinates indicate downwards movement ) . Note that no Size is specified here ; the size and location of this frame is defined entirely by its relationship to SomeOtherFrame . In particular , it will be inset by 5 pixels from the top left and bottom right of SomeOtherFrame . As SomeOtherFrame changes size , our frame will change size as well . Showing / Hiding . Frames may be shown or hidden by " FrameName " : Hide ( ) and " FrameName " : Show ( ) . Also available are ShowUIPanel ( " FrameName " ) and HideUIPanel ( " FrameName " ) . Layers and Textures . There are five levels of layer s , although in practice you will often only assign objects to three of the five . Of these three , BACKGROUND is in the back , ARTWORK is in the middle and OVERLAY is in front . The only way to be certain of where and how much of your object is visible is to assign it to a specific layer . BACKGROUND - Level 0 . Place the background of your frame here . BORDER - Level 1 . Place the border art of your frame here . ARTWORK - Level 2 . Place the artwork of your frame here . OVERLAY - Level 3 . Place your text , objects , and buttons in this level HIGHLIGHT - Level 4 . Place your text , objects , and buttons in this level " Note : The above are capitalized for a reason . See example : " Using Templates . Templates are used when you want to create a common layout for several frames . In this way you can save on the amount of code needed to recreate each frame , as the frames will automatically take on the properties , children , and attributes from whatever template it inherits . There are several rules that must be following when initially creating the template : As discussed above , there is a special keyword that can be used when naming something inside the template . When you inherit a frame , any object inside the template that is inherited , which has the keyword $ parent , will automatically replace the keyword with the name of the parent which inherited the template . Example : Is the same as doing : Be aware that any inherited attributes , properties , or children can also be overridden . Example : Is the same as doing : Templates can inherit other templates as well . When done in this way , any $ parent keywords used in the template being inherited carry over to the template that inherits it . Example : Is the same as doing : 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 . 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 : 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 : 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 : mymod . lua : 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 . 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 for a list of game events and how to register for them and handle them . Default User Interface . The default user interface that is visible without any installed third - party addons is built into the MPQ files . It can ' t be modified because it is protected by a digital signature , but using the World of Warcraft Interface AddOn Kit ( US , EU ) provided by Blizzard , the files can be extracted to see how the interface works .