CheckBox

A checkbox or radio button control with an optional label, description, and image. Supports a tri-state mode.

Create with AceGUI:Create("CheckBox"). It inherits the Common Widget API.

Widget type: CheckBox

Methods

SetValue

method#

widget:SetValue(value?)

Sets the checked state and updates the check texture. In tri-state mode, a nil value shows a desaturated check to represent the "unknown/mixed" state; false hides the check; any truthy value shows the normal check.

Parameters

Parameter	Type	Default	Description
value (optional)	boolean		true (checked), false (unchecked), or nil (only meaningful in tri-state mode).

GetValue

method#

widget:GetValue()

Returns the current checked state.

Returns

Type	Description
boolean	The current checked state (true, false, or nil for the tri-state unknown value).

ToggleChecked

method#

widget:ToggleChecked()

Cycles the value. In normal mode it flips between true/false. In tri-state mode it cycles in the order true → nil → false → true.

SetTriState

method#

widget:SetTriState(enabled)

Enables or disables tri-state behavior, then re-applies the current value so the display updates.

Parameters

Parameter	Type	Default	Description
enabled	boolean		true to allow the third (nil) state.

SetType

method#

widget:SetType(type?)

Switches the visual style between a checkbox and a radio button.

Parameters

Parameter	Type	Default	Description
type (optional)	string		"radio" for radio-button textures (16px), or anything else / nil for the default checkbox textures (24px).

SetLabel

method#

widget:SetLabel(label?)

Sets the text shown next to the box.

Parameters

Parameter	Type	Default	Description
label (optional)	string		The label string.

SetDescription

method#

widget:SetDescription(desc?)

Sets an optional supplementary description line beneath the label. Passing a value creates the description font string (if needed) and grows the widget height to fit it; passing nil/"" removes it and resets the height to 24.

Parameters

Parameter	Type	Default	Description
desc (optional)	string		The description text, or nil/"" to remove it.

SetImage

method#

widget:SetImage(path?, ...)

Sets an optional icon texture shown before the label and realigns the label accordingly.

Parameters

Parameter	Type	Default	Description
path (optional)	string | number		Texture path or file ID. nil clears the image.
...	number		Optional tex-coords. Pass 4 values (for SetTexCoord(left, right, top, bottom)) or 8 values for the full corner form; otherwise the full texture (0, 1, 0, 1) is used.

SetDisabled

method#

widget:SetDisabled(disabled)

Enables or disables the control. When disabled the label/description are greyed and the check is desaturated. When enabled, the check is desaturated only in tri-state mode with a nil value.

Parameters

Parameter	Type	Default	Description
disabled	boolean		true to disable, false to enable.

OnWidthSet

method#

widget:OnWidthSet(width)

Internal layout hook called when the width changes; re-wraps the description text and recomputes the height. Not normally called directly.

Parameters

Parameter	Type	Default	Description
width	number		The new width.

Defaults

On acquire the control resets to: checkbox type (not radio), value false, tri-state off, width 200, no image, not disabled, and no description.

Callbacks

OnValueChanged

callback#

OnValueChanged(checked?)

Fired when the user clicks the box (mouse up) and the value is toggled. A check-on/check-off sound is played first. Subscribe with widget:SetCallback.

Parameters

Parameter	Type	Default	Description
checked (optional)	boolean		The new value (true, false, or nil in tri-state).

OnEnter

callback#

OnEnter()

Fired when the mouse enters the control. Subscribe with widget:SetCallback.

OnLeave

callback#

OnLeave()

Fired when the mouse leaves the control. Subscribe with widget:SetCallback.

Example

local cb = AceGUI:Create("CheckBox")
cb:SetLabel("Enable feature")
cb:SetDescription("Turns the feature on or off for this character.")
cb:SetValue(db.enabled)
cb:SetCallback("OnValueChanged", function(widget, event, checked)
    db.enabled = checked
end)