AceGUI Tutorial - Simple Dialog

From WowAce Wiki
Jump to: navigation, search

Introduction

This tutorial is part of a series. Ideally you'll be continuing from AceGUI Tutorial - Getting Started and already have the files you need. If this is not the case, you can find the files in the Appendix at the bottom of the page.

This tutorial will introduce you to the very basics of element sizing, and display control, as well as interfacing with your UI from your regular addon.

Setting up the Dialog

Firstly, you need to give your dialog some sizes. Head to the DlgInit definition section of your Tutorial.lua file:

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

We'll be playing with this for the moment, so I'll run over what these values all mean.

  • The name field tallies up to a specifically named element in the XML file. In this case, it is the only element. "GUITutorialFrame".
  • The type field tells AceGUI what methods and variables are available to this object. In this case it is of type ACEGUI_DIALOG, so will have basic size controls, simple events (show/hide), a background, a title, and be able to contain other elements.
  • title is what will be displayed in the dialog's title
  • isSpecial - no idea what this actually does, but leave it at TRUE because, hey - you're special too. (In reality, it does something with UISpecialFrames, but I don't know what they are yet so I'm glossing over this bit)
  • backdrop works with the base AceGUIFrame code to determine what sort of backing the dialog has. Options are "small" "none" and "normal" - leave this at small unless you want to play around a bit.
  • width and height are the dimensions of your base dialog. Set width to 500 and height to 400 (instead of x and y which were just placeholders before). This will give your dialog some size, rather than just being a small zero by zero spot on the screen.
  • Immediately following the dimension variables, is an event function reference. This is where we specify which function we want to call at the OnShow event of this dialog. Leave this at "Build" because we'll be using that in future tutorials. Note: although technically a hook, this isn't quite a hook in the sense of function hooking in the Ace sense, but nevertheless you are still hooking an event to do your own function.

Ok, so now you know what all those parts mean, you should really have only edited width, height, and maybe title as it won't have much effect on the addon.

Showing the Dialog

The next big step, is to get the dialog visible on screen.

The easiest way, and probably the best way, is to set up a chat command for your Ace addon to show your dialog. So lets do that.

About 3 lines down into Tutorial.lua you should see the following code:

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

This is the localised constants construct we set up, which a <a href="/mediawiki/index.php?title=Local&action=edit" class="new" title="Local">local</a> version of is created immediately afterwards. We will be adding a function to the ChatOpt definition, which is then referenced further down in the file at the actual definition of the Ace addon. Chat Options denote the variables which can follow the Chat Command. Ace will interpret these and provide information as you describe to anyone querying your mod.

Make the following alteration:

        ChatOpt = {
            {
                option = "display",
                desc = "display the tutorial dialog.",
                method = "DisplayTutorialDialog",
            },
        },

These variables should be fairly self explanatory, but I'll quickly describe them: option is the word the user must type in order to trigger the specified method. desc is what Ace will display if you were to enter "/tutorial" without any prompts.

Now we've specified that DisplayTutorialDialog will be called if ever the user types "/tutorial display" we should probably define it as a function... otherwise nasty things may happen.


Scroll down the file until you reach the Tutorial.Obj definition and in the same way as Enable and Disable are defined as functions, we want to define DisplayTutorialDialog. So insert this code in between those two function definitions:

    DisplayTutorialDialog = function(self)
        GUITutorialFrame:Show()
    end,

This function definition calls the in-built AceGUI dialog function Show() from the named XML frame you specified earlier "GUITutorialFrame" in the dialog definition.

At this stage, you can save everything and load your addon in World of Warcraft, type "/tutorial display" in the chat window, and you'll see a box appear on your screen! It can be dragged around as you wish, congratulations - this is your first, albeit very basic, UI.

Hiding the Dialog

Having shown the dialog, what if you want to hide it? Simple. The AceGUIDialogTemplate, which your AceGUITutorialFrame (XML) inherited from came complete with a Close button in the lowermost right corner. Just click on that and your dialog will hide itself.

Testing

By entering "/tutorial display" you should be able to consistantly force the tutorial's dialog to show itself. The close button should return it to a hidden state, and you will notice that the dialog remains where you dragged it to last when re-shown. Try editing the width and height in the lua code, then Reloading the GUI, see what a difference to the shape it can make.

Summary

In this tutorial, you have learned how to show and hide a base dialog for an addon, and hopefully picked up some of the options you can change regarding this (width, height, title, backdrop etc).

Over the coming tutorials I will be covering the various elements, and building up a simple user interface as we go.

Appendix

This is the starting point for this tutorial, in case you've broken your

Tutorial.toc

## 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

Tutorial.xml

<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>

Tutorial.lua

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,
})