AceGUI for Ace 3.x

From WowAce Wiki

Quick Links: AceGUI 3.x Widgets

Some notes on AceGUI-3.0

As of 15 MAY 08 the following files comprise the AceGUI-3.0 package:

• AceGUI-3.0.lua
• AceGUI-3.0.xml
• widgets\AceGUIWidget-BlizOptionsGroup.lua
• widgets\AceGUIWidget-Button.lua
• widgets\AceGUIWidget-CheckBox.lua
• widgets\AceGUIWidget-ColorPicker.lua
• widgets\AceGUIWidget-DropDown.lua
• widgets\AceGUIWidget-DropDownGroup.lua
• widgets\AceGUIWidget-EditBox.lua
• widgets\AceGUIWidget-Frame.lua
• widgets\AceGUIWidget-Heading.lua
• widgets\AceGUIWidget-Icon.lua
• widgets\AceGUIWidget-InlineGroup.lua
• widgets\AceGUIWidget-Keybinding.lua
• widgets\AceGUIWidget-Label.lua
• widgets\AceGUIWidget-MultiLineEditBox.lua
• widgets\AceGUIWidget-ScrollFrame.lua
• widgets\AceGUIWidget-SimpleGroup.lua
• widgets\AceGUIWidget-Slider.lua
• widgets\AceGUIWidget-TabGroup.lua
• widgets\AceGUIWidget-TreeGroup.lua

Before any coding done, the mod developer must ensure that the LibStub library is in the same directory as the AceGUI-3.0 directory.

Usage

From what the author can gather via initial code inspection, the way one instantiates a widget is by utilizing the Create method of the AceGUI library, i.e.:

local frame = LibStub("AceGUI-3.0"):Create("Frame");

This minimal example will show a frame with a good amount of features, such as a title bar, a functioning "close" button to close the window, and the ability to be moved and resized by the user. This shows that by default the widgets in this package already come with a pre-set number of features, which the mod programmer has to be mindful of when he/she starts wondering why certain features are set without being explicitly defined at the library instance level.

As far as function in World of Warcraft, one can type the following directly into the chat bar and see the results for oneself, given the instantiation of the AceGUI-3.0 library via a loaded mod:

/script aceframe = LibStub("AceGUI-3.0"):Create("Frame");

This will indeed pop up a frame which you can reference in future /script console commands. As another exercise, one could do the following to hide the window:

/script aceframe:Hide();

File Descriptions

AceGUI-3.0.lua

Listed below are only some of the methods which this author believes are meant to be accessed by users of AceGUI. The other functions inside the file seem to be for internal use, either by the AceGUI library or some other Ace library this author is not familiar with.

AceGUI:Create(type)

Arguments:

• type (type string) - the type name of a AceGUI-3.0 widget

Return Value: table
Notes: Upon calling, this function will check the WidgetRegistry for the given type of widget. If the widget is defined, the return value of widget will contain a table with methods specific to the widget as they are defined in the Widget's Lua file.

AceGUI:Release(widget)

Arguments:

• widget (type table)

Return Value: none
Notes: This function will release the previously declared widget instance from memory, including all attached child widgets.

AceGUI:RegisterAsContainer(widget)

Arguments:

• widget (type table)

Return Value: none
Notes: This function and AceGUI:RegisterAsWidget(widget) below are used by the Widget Lua files at the end of their constructors to register themselves as being available for instantiation. This function registers the widget as a container that can hold other widgets.

This function appends to widget the following keys:

• children (type table) - an empty table.
• userdata (type table) - an empty table. Comments say this is where widget instance-specific data should be stored
• events (type table) - an empty table.
• base (type table) - set to equal WidgetContainerBase, which is a local table initialized to AceGUI.WidgetContainerBase and contains the following functions:
  • PauseLayout(self)
  • ResumeLayout(self)
  • PerformLayout(self)
  • DoLayout(self)
  • AddChild(self, child)

    As far as this function goes, it can be used to add widget type widgets (eg.: "Label") to container widgets (eg.: "Frame"). (This author does not know for sure if that is indeed the intended usage of the function.)

  • ReleaseChildren(self)
  • SetLayout(self, Layout)

Aside from the above keys this function also sets the default layout to "List", meaning all the internal widgets will be placed one after another along the left edge, top to bottom, regardless of width. (Two small-width widgets will be placed one on top of the other instead of side by side.)

AceGUI:RegisterAsWidget(widget)

Arguments:

• widget (type table)

Return Value: none
Notes: This function and AceGUI:RegisterAsContainer(widget) above are used by the Widget Lua files at the end of their constructors to register themselves as being available for instantiation. This function registers a widget that does not hold any child widgets.

Similar to AceGUI:RegisterAsContainer(widget), this function will append to widget the following keys:

• children (type table) - an empty table.
• userdata (type table) - an empty table.
• base (type table) - set to equal WidgetBase, which is a local table initialized to AceGUI.WidgetBase and contains the following functions:
  • SetParent(self, parent)
  • SetCallback(self, name, func)
  • Fire(self, name, ...)
  • SetWidth(self, width)
  • SetHeight(self, height)

AceGUI:RegisterWidgetType(Name, Constructor, Version)

Arguments:

• Name (type unknown)

  This author believes that Name should be a string, but it is currently not asserted or noted in code comments.

• Constructor (type function)
• Version (type number)

Return Value: none
Notes: This function stores the widget's constructor in a table called WidgetRegistry and notes the version of the widget. All Widget Lua files included with AceGUI-3.0 run this method at the very end of the widget definition.

AceGUI:RegisterLayout(Name, LayoutFunc)

Arguments:

• Name (type unknown)

  This author believes that Name should be a string, but it is currently not asserted or noted in code comments.

• LayoutFunc (type function)

Return Value: none
Notes: This function stores LayoutFunc in a table called LayoutRegistry.

AceGUI:GetLayout(Name)

Arguments:

• Name (type unknown)

  This author believes that Name should be a string, but it is currently not asserted or noted in code comments.

Return Value: type function
Notes: This function retrieves the function associated with the layout given as Name as previously stored via AceGUI:RegisterLayout(Name, LayoutFunc).

AceGUI-3.0.xml

This XML file is included in the main mod's .toc and pulls in the main Lua file for the library, as well as all the Widget Lua files in the widgets\ subdirectory.