AceGUI Tutorial - Getting Started

From WowAce Wiki
Jump to: navigation, search


Do not use AceGUI, it is old, unmaintained and rotten.


Introduction

These tutorials are intended to step you through the process of adding a GUI to your addon using AceGUI. They will assume you understand the basics of creating an Ace compatible addon... if you don't know how to do this you may still be able to muddle through as code snippets are provided, but please refer to tutorials in Ace for the ultimate basics in Ace use.

If those tutorials don't exist yet - sorry! We need to find someone to write them!

This tutorial will step you through the installation of Ace and AceGUI to the stage where you can use them to write your own addons.


Required Files

You will need:

  • Ace
  • AceGUI
  • Generic Text Editor
  • World of Warcraft

Installation

Ace and AceGUI will need to be installed as addons inside World of Warcraft.

Typically, this will result in the following directory structure:

World of Warcraft
World of Warcraft\Interface
World of Warcraft\Interface\Addons
World of Warcraft\Interface\Addons\Ace
World of Warcraft\Interface\Addons\AceGUI

Inside the Ace directory will be all the files relating to Ace, and inside the AceGUI folder will be all the files relating to AceGUI and a subdirectory containing all of the GUI elements. Next, you will want to ensure that both Ace and AceGUI are loaded when you start World of Warcraft (check the Addons button in the bottom left on the character selection screen) Having done that, you should be ready to start.

Addon Beginnings

At the very beginning, every Ace addon will look very similar. At this stage, all that is necessary is for the addon to register itself with Ace. So, starting at the beginning.... create a directory in 'Addons' for your mod. In this tutorial, we'll call the addon "Tutorial", so every time you see that (e.g. in the code) you should replace it with the name of your addon.

World of Warcraft\Interface\Addons\Tutorial

Next, create 3 blank files inside that directory as follows:

World of Warcraft\Interface\Addons\Tutorial\Tutorial.toc
World of Warcraft\Interface\Addons\Tutorial\Tutorial.xml
World of Warcraft\Interface\Addons\Tutorial\Tutorial.lua

.toc File

The first of these, the .toc file, is used by World of Warcraft to identify which files are needed for your addon, and to set up any dependancies and so forth. Edit the file and enter the following:


## Interface: 1800
## Title: Tutorial
## Version: 0.1.1800
## Author: Matryx (put your name here)
## Notes: This addon doesn't really do anything
## Description: This addon doesn't really do anything.
## Dependencies: Ace, AceGUI
## SavedVariables: TutorialDB
Tutorial.lua
Tutorial.xml

Ok, the first line relates to the current version of World of Warcraft... this basically means "the last version which this addon has been tested with". As you update your addons to new releases of World of Warcraft, you should update this figure accordingly.

Next, the title of the addon. Fairly self explanatory, but try to name your addon something unique and meaningful. This way, when users scroll down their addons list they'll be able to easily identify it. This should ideally be the same as the directory name.

After this comes the version number of your addon. Used to tell different releases apart, it's a normal practice to slowly increase this figure as you add new features.

Author information is next, just a quick name or a name/server combo will suffice.

Any notes regarding the addon, quickly followed by the general description of the addon's job are the next two lines. I usually have these pretty similar unless the Note needs to be something specific (e.g. Will not work if you are colourblind etc.)

Dependencies get listed next... in here will always go Ace and AceGUI if you are writing an AceGUI based mod.

Any variables which need to be saved between sessions go next, then finally a listing of the other files to be loaded for this addon... where all the juicy stuff happens.

.XML file

The .xml file is where you define the structure for your UI. This is then interpreted by AceGUI to create an instance of the UI object, providing a stable set of methods and interfaces for controlling it.

For the moment, this file just needs to exist, so create it with the following:

<Ui xmlns="<a href="http://www.blizzard.com/wow/ui/" class="external free" title="http://www.blizzard.com/wow/ui/" rel="nofollow">http://www.blizzard.com/wow/ui/</a>"
   xmlns:xsi="<a href="http://www.w3.org/2001/XMLSchema-instance" class="external free" title="http://www.w3.org/2001/XMLSchema-instance" rel="nofollow">http://www.w3.org/2001/XMLSchema-instance</a>"
   xsi:schemaLocation="<a href="http://www.blizzard.com/wow/ui/FrameXML/UI.xsd" class="external free" title="http://www.blizzard.com/wow/ui/FrameXML/UI.xsd" rel="nofollow">http://www.blizzard.com/wow/ui/FrameXML/UI.xsd</a>">
  <Frame name="GUITutorialFrame" inherits="AceGUIDialogTemplate" hidden="true" parent="UIParent">
  </Frame>
</Ui>

This is standard XML notation defining where the rules for following the XML schema are located. The schema will dictate what is and isn't allowed inside the XML document, but you needent worry about learning that just yet unless you are an XML nutcase.

The "frame" section is the start of your UI, though it's currently set to invisible and has no dimensions to speak of.


.lua file

Ah, the .lua file. This is where all the juicy stuff in your mod usually happens (with the exception of when you specify the base structure of an UI in the XML file).

Currently, we just need a base file, so create it as follows:

Tutorial = {}

if not ace:LoadTranslation("Tutorial") then
    Tutorial.Const = {
        ChatCmd = { "/tutorial" },
        ChatOpt = {},
        Defaults = {},
    }
end

local const = Tutorial.Const

Tutorial.DlgInit    = { 
    name                = "GUITutorialFrame", 
    type                = ACEGUI_DIALOG, 
    title               = "Addon", 
    isSpecial           = TRUE, 
    backdrop            = "small", 
    width               = x, 
    height              = y, 
    OnShow              = "Build", 
    elements            = { 
    }, 
}

Tutorial.Dialog = AceGUI:new({
    Build = function(self)
    end,
})

Tutorial.Obj = AceAddon:new({
    name          = "Tutorial",
    description   = "TutorialDESCRIPTION",
    version       = "0.1",
    releaseDate   = "12-12-2005",
    aceCompatible = 102,
    author        = "Matryx",
    email         = "author@somewhere.com",
    website       = "http://",
    category      = "others",
    optionsFrame  = "TutorialOptionsFrame",
    db            = AceDatabase:new("TutorialDB"),
    defaults      = const.Defaults,
    cmd           = AceChatCmd:new(const.ChatCmd, const.ChatOpt),

    Initialize = function(self)
    end,

    Enable = function(self)
        Tutorial.Dialog:Initialize(self, Tutorial.DlgInit)
    end,

    Disable = function(self)
    end,

})

Tutorial.Obj:RegisterForLoad()

ace:RegisterFunctions(Tutorial.Obj, {
    version = 1.0,

    Msg   = function(self, ...)
       self.cmd:msg(unpack(arg))
    end,
    Get   = function(self, var)
       return self.db:get(self.profilePath, var)
    end,
    Set   = function(self, var, val)
       self.db:set(self.profilePath, var, val)
    end,
    Reset = function(self, i)
       if i == "" then self:Msg(ACEG_RESETINFO,
                                self.cmd._cmdList[1])
       else self:Msg(ACEG_DORESET)
          self.db:reset(self.profilePath,
                        self.defaults)
       end
    end,
})

If I can just skim over what all these sections mean, if you need more detail on creating an Ace addon, please refer to the tutorials under the Ace Documentation section.

Firstly, it defines the addon in the global namespace, then it places a 'const' extension of that object within code which would alternatively load a localised form of the constants (if available). It then defines a base structure for the UI creation (currently just a blank frame) and then instantiates an instance of the UI object. Immediately after this is creates an instance of the addon itself, complete with function definitions, tells Ace that this is a module which needs to be loaded, and finally sets some common functions for saving to / loading from the internal addon database and resetting the addon to it's default state.

Testing

At this stage, you should be able to go into World of Warcraft and see (either on load or through /ace list) that your addon has sucessfully loaded and registered itself with Ace. It doesn't do anything at the moment, but the fact that it exists and Ace knows that it exists is good progress.

Summary

These steps can be used as a base skeleton for any GUI based mod you may have in mind. Just a .toc file, a .xml file and a .lua are all that are required to set the stage for any mod.

With these as our base files, you are ready to move onto the first real stage of the tutorial.


>> AceGUI Tutorial - Simple Dialog