WoW:User interface customization guide (source)
Revision as of 07:19, 8 February 2009
, 8 February 2009Corrected spelling/grammar
m (Removed archaic note about Cosmos slash command) |
m (Corrected spelling/grammar) |
||
| Line 5: | Line 5: | ||
|info=*For one, you no longer need to modify FrameXML in order to add code to WoW (yes, that's how badly out of date it is).}} | |info=*For one, you no longer need to modify FrameXML in order to add code to WoW (yes, that's how badly out of date it is).}} | ||
This '''user interface customization guide''' is based | This '''user interface customization guide''' is based upon slouken's post on the official Beta UI forums ''(a long time ago in a galaxy far, far away)''. | ||
== World of Warcraft | == World of Warcraft user interface customization guide == | ||
The interface of ''World of Warcraft'' is built from XML files, which describe the look and layout, and lua files, which contain scripting functionality. This document is a short introduction into modifying these files to customize your interface. Customizing the interface is a very technical endeavor, and you should not attempt it unless you have a good working knowledge of XML and Lua. | The interface of ''World of Warcraft'' is built from XML files, which describe the look and layout, and lua files, which contain scripting functionality. This document is a short introduction into modifying these files to customize your interface. Customizing the interface is a very technical endeavor, and you should not attempt it unless you have a good working knowledge of XML and Lua. | ||
| Line 20: | Line 20: | ||
A quick reminder: when developing addons you will often encounter bugs that you just can't figure out. If you're like most of us, you will quickly begin to think that it's Blizzard's fault. Before reporting a bug in the game UI, disable all addons and verify that the bug is present in the unmodified game. Maybe it is Blizzard's bug, but there's an even better chance that the bug is yours or another addon you're running during your development. | A quick reminder: when developing addons you will often encounter bugs that you just can't figure out. If you're like most of us, you will quickly begin to think that it's Blizzard's fault. Before reporting a bug in the game UI, disable all addons and verify that the bug is present in the unmodified game. Maybe it is Blizzard's bug, but there's an even better chance that the bug is yours or another addon you're running during your development. | ||
== XML | == XML layout == | ||
The files containing the layout and scripts for the game user interface can be found in Blizzard Interface Data\FrameXML. | The files containing the layout and scripts for the game user interface can be found in Blizzard Interface Data\FrameXML. | ||
The FrameXML.toc file is a plain text file and contains a list of | The FrameXML.toc file is a plain text file and contains a list of Lua and XML files to load at login. The files are loaded in the order they're listed and any load errors are written to FrameXML.log in the game's Log folder. | ||
In your own addons you will also have a .toc file which performs the same function for your own code. You will list your Lua and XML files in it and they will be loaded during login. Errors which occur while loading your addon will also be written to the FrameXML.log file. | In your own addons you will also have a .toc file which performs the same function for your own code. You will list your Lua and XML files in it and they will be loaded during login. Errors which occur while loading your addon will also be written to the FrameXML.log file. | ||
| Line 31: | Line 31: | ||
The XML files strictly adhere to the XML standard and if your text editor supports XML syntax checking, the file UI.xsd in the FrameXML folder contains the schema used by the WoW interface. | The XML files strictly adhere to the XML standard and if your text editor supports XML syntax checking, the file UI.xsd in the FrameXML folder contains the schema used by the WoW interface. | ||
Lots more details here: [[XML User Interface]] | Lots more details here: [[XML User Interface]]. | ||
== Lua | == Lua scripting == | ||
All of the functionality in the interface is provided through Lua scripting. It is also possible to create any layout that is possible with the XML markup in pure Lua scripting. | All of the functionality in the interface is provided through Lua scripting. It is also possible to create any layout that is possible with the XML markup in pure Lua scripting. | ||
The manual for Lua 5.1.4 (http://www.lua.org) is available online at http://www.lua.org/manual/5.1 | The manual for Lua 5.1.4 (http://www.lua.org) is available online at http://www.lua.org/manual/5.1. | ||
For more concise help, topic-specific Lua tutorials can be found at: http://lua-users.org/wiki/TutorialDirectory | For more concise help, topic-specific Lua tutorials can be found at: http://lua-users.org/wiki/TutorialDirectory. | ||
The best way to become familiar with the way Lua is used to script the interface is to look at the scripts in the XML files, denoted by the <script> tag, and to browse the lua files. The lua files typically contain functions which are used by the corresponding XML files. | The best way to become familiar with the way Lua is used to script the interface is to look at the scripts in the XML files, denoted by the <script> tag, and to browse the lua files. The lua files typically contain functions which are used by the corresponding XML files. | ||
| Line 46: | Line 46: | ||
For example: | For example: | ||
/run print(GetLocale()); | /run print(GetLocale()); | ||
This will print your client locale into the default chat window | This will print your client locale into the default chat window ("enUS" for English clients, "deDE" for German clients, etc). | ||
== Getting | == Getting started == | ||
A good place to start getting familiar with the interface is the file BasicControls.xml. | A good place to start getting familiar with the interface is the file BasicControls.xml. | ||
| Line 59: | Line 59: | ||
At the end of the file we define an actual frame called "ScriptErrors" which inherits the dialog box we defined previously. This is the frame which is shown in the message function at the top of the file. | At the end of the file we define an actual frame called "ScriptErrors" which inherits the dialog box we defined previously. This is the frame which is shown in the message function at the top of the file. | ||
== How | == How does it work? == | ||
The very first frame that is created is the WorldFrame. This frame is required, and is where the game world renders. The next frame that is created is the UIParent frame. This frame manages all the rest of the user interface, and allows it to be hidden separately from the world. This is how we get screenshots without the interface visible. :) | The very first frame that is created is the WorldFrame. This frame is required, and is where the game world renders. The next frame that is created is the UIParent frame. This frame manages all the rest of the user interface, and allows it to be hidden separately from the world. This is how we get screenshots without the interface visible. :) | ||
Whenever a frame, texture or font string is defined in XML, its initial attributes are defined and it is added to the lua name space as an object of the appropriate type. Each type of object has member functions that modify that object. This is how we show the error dialog frame from script. | Whenever a frame, texture or font string is defined in XML, its initial attributes are defined and it is added to the lua name space as an object of the appropriate type. Each type of object has member functions that modify that object. This is how we show the error dialog frame from script. | ||
Each frame has a set of script handlers which are called under certain conditions. For example, UIParent has OnLoad, which is called immediately after the frame is loaded, OnEvent, which we | Each frame has a set of script handlers which are called under certain conditions. For example, UIParent has OnLoad, which is called immediately after the frame is loaded, OnEvent, which we will get to later, OnUpdate, which is called every time the world is updated, and OnShow, which is called whenever the frame is shown. | ||
The OnEvent handler is special. This is the handler that allows the game to communicate with the interface. ''World of Warcraft'' is designed so that it needs to know very little about the interface. Instead of calling directly into the interface, whenever something interesting happens, it generates an event. Each frame registers for events that it is interested in, and when those events happen, the OnEvent handler is called for that frame. | The OnEvent handler is special. This is the handler that allows the game to communicate with the interface. ''World of Warcraft'' is designed so that it needs to know very little about the interface. Instead of calling directly into the interface, whenever something interesting happens, it generates an event. Each frame registers for events that it is interested in, and when those events happen, the OnEvent handler is called for that frame. | ||
| Line 70: | Line 70: | ||
Having the UI respond to events wouldn't be very useful if the interface couldn't affect the game in return. The game provides a wide array of functions to query information and change game state. Examples of using these functions are throughout the provided lua files. | Having the UI respond to events wouldn't be very useful if the interface couldn't affect the game in return. The game provides a wide array of functions to query information and change game state. Examples of using these functions are throughout the provided lua files. | ||
== Tips and | == Tips and tricks == | ||
''World of Warcraft'' supports dynamically '''reloading the user interface'''. At any time, you can modify the XML and Lua files and then reload them by either typing: | ''World of Warcraft'' supports dynamically '''reloading the user interface'''. At any time, you can modify the XML and Lua files and then reload them by either typing: | ||
| Line 89: | Line 89: | ||
== Conclusion == | == Conclusion == | ||
The interface files are provided for your enjoyment, and are not supported in any way. That said, we hope that ''World of Warcraft'' provides a robust and flexible system for custom interfaces. | The interface files are provided for your enjoyment, and are not supported in any way. That said, we hope that ''World of Warcraft'' provides a robust and flexible system for custom interfaces. | ||
See also: | See also: | ||