Common Widget API

Every AceGUI-3.0 widget inherits a common set of methods from WidgetBase. Containers inherit an additional set from WidgetContainerBase (which itself extends WidgetBase).

The per-widget pages in this section document only the methods and callbacks specific to that widget; the methods below are available on every widget and are not repeated there.

Widget Methods

Available on every widget and container.

SetWidth

method#

widget:SetWidth(width)

Set the widget's width in pixels. Fires the widget's internal OnWidthSet hook if it defines one.

Parameters

Parameter	Type	Default	Description
width	number		The width in pixels.

SetHeight

method#

widget:SetHeight(height)

Set the widget's height in pixels. Fires the widget's internal OnHeightSet hook if it defines one.

Parameters

Parameter	Type	Default	Description
height	number		The height in pixels.

SetRelativeWidth

method#

widget:SetRelativeWidth(width)

Set the width as a fraction of the parent container's width. width must be greater than 0 and at most 1 (e.g. 0.5 for half width). Errors on an invalid value.

Parameters

Parameter	Type	Default	Description
width	number		Fraction of the parent's width; must be greater than 0 and at most 1.

SetFullWidth

method#

widget:SetFullWidth(isFull)

When isFull is truthy, the widget fills the full width of its container row. Pass a falsy value to clear it.

Parameters

Parameter	Type	Default	Description
isFull	boolean		Truthy to fill the full row width; falsy to clear.

IsFullWidth

method#

widget:IsFullWidth()

Returns true if the widget is set to full width.

Returns

Type	Description
boolean	true if the widget is set to full width.

SetFullHeight

method#

widget:SetFullHeight(isFull)

When isFull is truthy, the widget fills the full available height. Pass a falsy value to clear it.

Parameters

Parameter	Type	Default	Description
isFull	boolean		Truthy to fill the full available height; falsy to clear.

IsFullHeight

method#

widget:IsFullHeight()

Returns true if the widget is set to full height.

Returns

Type	Description
boolean	true if the widget is set to full height.

SetPoint

method#

widget:SetPoint(...)

Passes through to the underlying frame's SetPoint. Manual anchoring is generally unnecessary; let the container's layout position the widget.

Parameters

Parameter	Type	Default	Description
...	any		Anchoring arguments forwarded to the frame's SetPoint.

ClearAllPoints

method#

widget:ClearAllPoints()

Passes through to the underlying frame's ClearAllPoints.

GetPoint

method#

widget:GetPoint(...)

Passes through to the underlying frame's GetPoint.

Parameters

Parameter	Type	Default	Description
...	any		Arguments forwarded to the frame's GetPoint.

GetNumPoints

method#

widget:GetNumPoints()

Passes through to the underlying frame's GetNumPoints.

Returns

Type	Description
number	The number of anchor points on the underlying frame.

SetCallback

method#

widget:SetCallback(name, func)

Register a callback handler for one of the widget's events. func is called with the widget as its first argument and the callback name as its second, followed by any event-specific arguments. Passing a non-function is ignored.

Parameters

Parameter	Type	Default	Description
name	string		The callback/event name (e.g. "OnClick").
func	function		Handler; called as (widget, event, ...). Non-functions are ignored.

Example

button:SetCallback("OnClick", function(widget, event) print("clicked") end)

Fire

method#

widget:Fire(name, ...)

Fire a registered callback by name, passing along any extra arguments. The handler is invoked with the widget and the event name prepended to the arguments. If the handler ran successfully, its return value is returned. Used internally by widgets; you normally consume callbacks via SetCallback rather than calling Fire yourself.

Parameters

Parameter	Type	Default	Description
name	string		The callback/event name to fire.
...	any		Extra arguments passed along to the handler.

Returns

Type	Description
any	The handler's return value, if it ran successfully.

SetUserData

method#

widget:SetUserData(key, value)

Store arbitrary data on the widget under key. Useful for associating application state with a widget instance.

Parameters

Parameter	Type	Default	Description
key	any		The key under which to store the value.
value	any		The value to store.

GetUserData

method#

widget:GetUserData(key)

Retrieve a value previously stored with SetUserData.

Parameters

Parameter	Type	Default	Description
key	any		The key to look up.

Returns

Type	Description
any	The previously stored value, or nil.

GetUserDataTable

method#

widget:GetUserDataTable()

Returns the widget's full user-data table.

Returns

Type	Description
table	The widget's full user-data table.

SetParent

method#

widget:SetParent(parent)

Reparents the widget to another widget's content frame. Containers call this for you in AddChild.

Parameters

Parameter	Type	Default	Description
parent	table		The widget whose content frame becomes the new parent.

IsVisible

method#

widget:IsVisible()

Returns the underlying frame's visibility (via IsVisible).

Returns

Type	Description
boolean	The underlying frame's visibility.

IsShown

method#

widget:IsShown()

Returns the underlying frame's shown state (via IsShown).

Returns

Type	Description
boolean	The underlying frame's shown state.

Release

method#

widget:Release()

Releases the widget back to the widget pool (shortcut for AceGUI:Release(widget)).

IsReleasing

method#

widget:IsReleasing()

Returns true if the widget is currently being released.

Returns

Type	Description
boolean	true if the widget is currently being released.

Container Methods

Available on every container widget in addition to the widget methods above.

AddChild

method#

container:AddChild(child, beforeWidget?)

Add a child widget to the container and lay it out. If beforeWidget is supplied, the child is inserted before that existing sibling instead of appended.

Parameters

Parameter	Type	Default	Description
child	table		The child widget to add.
beforeWidget (optional)	table		An existing sibling to insert the child before.

AddChildren

method#

container:AddChildren(...)

Add multiple child widgets at once, then perform a single layout pass.

Parameters

Parameter	Type	Default	Description
...	table		One or more child widgets to add.

ReleaseChildren

method#

container:ReleaseChildren()

Release all child widgets back to the pool and clear the container's child list. Commonly called before redrawing a group's contents.

SetLayout

method#

container:SetLayout(layout)

Set the layout function used to arrange children, by registered name: "List", "Flow", "Fill" or "Table".

Parameters

Parameter	Type	Default	Description
layout	string		The registered layout name: "List", "Flow", "Fill" or "Table".

DoLayout

method#

container:DoLayout()

Lay out the container's children. Called automatically by AddChild/AddChildren; call it manually after changing children outside those methods.

PerformLayout

method#

container:PerformLayout()

Runs the layout function immediately (unless layout is paused). DoLayout is the usual entry point.

PauseLayout

method#

container:PauseLayout()

Suspend automatic layout. Useful when adding many children in a loop to avoid a layout pass per child.

ResumeLayout

method#

container:ResumeLayout()

Resume automatic layout after PauseLayout. Follow with DoLayout to apply.

Example

container:PauseLayout()
for _, item in ipairs(items) do
    local w = AceGUI:Create("Label")
    w:SetText(item)
    container:AddChild(w)
end
container:ResumeLayout()
container:DoLayout()

SetAutoAdjustHeight

method#

container:SetAutoAdjustHeight(adjust)

When adjust is truthy (the default), the container automatically resizes its height to fit its content. Pass false to keep a fixed height.

Parameters

Parameter	Type	Default	Description
adjust	boolean		Truthy (the default) to auto-resize height to fit content; false to keep a fixed height.

Internal hooks

These are optional members a widget implementation may define; AceGUI calls them for you. Addon authors don't call or register them (consume widgets through their public methods); they matter when you build a custom widget. OnAcquire and OnRelease are driven by the widget pool; OnWidthSet / OnHeightSet by sizing; and LayoutFinished by the layout pass.

OnAcquire

callback#

widget:OnAcquire()

Called by AceGUI:Create when the widget is handed out (whether freshly created or reused from the pool) to reset it to its default state (size, text, value, …). This is why a recycled widget never carries over data from its previous user.

OnRelease

callback#

widget:OnRelease()

Called by AceGUI:Release before the widget returns to the pool. Clears the widget's data and hides it.

OnWidthSet

callback#

widget:OnWidthSet(width)

Called by SetWidth after the frame is resized, if the widget defines it. A widget implementation uses this to re-lay-out its contents for the new width. Use this rather than the frame's own OnSizeChanged; AceGUI already manages that.

Parameters

Parameter	Type	Default	Description
width	number		The new width in pixels.

OnHeightSet

callback#

widget:OnHeightSet(height)

Called by SetHeight after the frame is resized, if the widget defines it. A widget implementation uses this to re-lay-out its contents for the new height. Use this rather than the frame's own OnSizeChanged; AceGUI already manages that.

Parameters

Parameter	Type	Default	Description
height	number		The new height in pixels.

LayoutFinished

callback#

widget:LayoutFinished(width, height)

Called on a container after a layout pass finishes. A container implementation uses this to size itself to its content; auto-growing groups add their content height here.

Parameters

Parameter	Type	Default	Description
width	number		Width of the area used by the laid-out controls, or nil if the layout used the existing size.
height	number		Height of the area used by the laid-out controls, or nil if the layout used the existing size.