AceOptions data table

From WowAce Wiki

The AceOptions data table is a standard used in several places to make your configuration globally accessible:

• The AceOptions slash command handler (/youraddon arg1 arg2 etc)
• The DewDrop "FeedAceOptionsTable" method
• The WaterFall config gui

Contents 1 Misc notes 2 execute 2.1 Fields 2.2 Example 3 range 3.1 Fields 3.2 Example 4 toggle 4.1 Fields 4.2 Example 5 color 5.1 Fields 5.2 Example 6 text 6.1 Fields 6.2 Example 7 group 7.1 Fields 7.1.1 GUI-only fields 7.2 Example 8 header 8.1 Fields

Misc notes

• On the top level of your options, you do not need to declare a 'desc' or 'name' field, it would be taken from your Addon's description and name. If you do declare it, it will not be overridden.

• Ordering: -1 is the very last value, -2 comes before that, -10000 comes before that, and 10000 comes before that.
  

1 is the very first value, 2 comes after that, 10000 comes after that, and -10000 comes after that.
An order of 0 is an error.
Ordering should only happen for GUIs, not for Consoles.
If two orders are equal, then it should be sorted alphabetically.

• Every name field can be replaced with guiName and cmdName,
• Every hidden field can be replaced with guiHidden, cmdHidden, and wfHidden.
• The wfHidden field will hide the option only in a waterfall frame, but will still be visible in the command line and other GUI settings (such as a Dewdrop menu)
• Every desc field can have an additional guiDesc field, where newlines are allowed

• Icons: execute, range, text, group, and header types can have the 'icon' field. This is only visible on GUI options, such as Dewdrop menus. 'icon' has no effect on console menus. 'guiIconOnly = true' can be applied to any field with a icon to force dewdrop to only display the icon.

• If you provide methods for `hidden`, `disabled`, or toggle's `get`, then you can use "~IsGood" instead of function() return not self:IsGood() end

• handler is inherited from groups to subgroups. The top handler is your addon.

execute

The execute type simply calls a function. In a GUI sense, it would be a button that if you push, it does something. This does not take any extra input. For an execute style entry with parameters use "text" with get=false (see below at "text").

Fields

name

string - Name

desc

string - Description of what the field will do

func

string - Method to call based on the current handler.

function - function to call

[disabled]

boolean - whether option is disabled (default: false)

function - function to call to get disabled state.

string - method to call based on the current handle to get the disabled state.

[hidden]

boolean - whether option is hidden. implies disabled. (default: false)

function - function to call to get hidden state.

string - method to call based on the current handle to get the hidden state.

[handler]

table - object on which to call methods (default: inherited from parent group).

[icon]

string - path to icon. (default: nil)

[iconWidth, iconHeight]

number - dimensions of icon. (default: 16)

[order]

number - ordering number to determine position. (default: 100)

[confirm]

boolean - whether to show a confirm dialog, uses the default message if true. (default: false)

string - show the confirm dialog with a custom message.

[passValue]

value - a value which will be passed to the func, disabled and hidden functions as the first argument. Note: this will replace the first argument (instead of using the option key) if it is part of a passing group.

Example

{
    type = 'execute',
    desc = "Change some value",
    func = function()
        value = value   1
    end
}

range

A range is a number value from a defined minimum to a defined maximum. In a GUI, it would be a slider.

The usage string will be "(<min>-<max>)", e.g. "(0-100)"

Fields

name

string - Short name of the field

desc

string - Description of what the field is

[min]

number - Minimum value (default: 0)

[max]

number - Maximum value. Must be greater than min. (default: 1)

[step]

number - Step between values. (default: 0)

[bigStep]

number - A useful, larger step between values. (default: step) - this is mostly so there can be a rough setting (bigStep) and a finer-tuned setting (step).

[isPercent]

boolean - Whether it'll show as a percentage. (default: false)

get

string - Method to call to get the current value.

function - function to call to get the current value.

set

string - Method to call to set the new value.

function - function to call to set the new value.

[error]

string - Format string to occur if a given option is not valid. (default: "%s is not a valid option for %s")

[message]

string - Format string to occur if a new value is set. (default: "%s is now set to [%s]")

[current]

string - Format string to occur to tell the current value. (default: "%s is currently set to [%s]")

[finalSetOnly]

boolean - whether to only call setValue on mouseup when dragging a slider in a gui (default: false)

[disabled]

boolean - whether option is disabled (default: false)

function - function to call to get disabled state.

string - method to call based on the current handle to get the disabled state.

[hidden]

boolean - whether option is hidden. implies disabled. (default: false)

function - function to call to get hidden state.

string - method to call based on the current handle to get the hidden state.

[handler]

table - object on which to call methods (default: inherited from parent group).

[icon]

string - path to icon. (default: nil)

[iconWidth, iconHeight]

number - dimensions of icon. (default: 16)

[order]

number - ordering number to determine position. (default: 100)

[passValue]

value - a value which will be passed to the func, disabled and hidden functions as the first argument. Note: this will replace the first argument (instead of using the option key) if it is part of a passing group.

Example

{
    type = 'range',
    desc = "Change the alpha value"
    get = function()
        return value
    end,
    set = function(v)
        value = v
    end,
    min = 0,
    max = 1, -- since percentage, max is 100%,
    step = 0.05, -- every 5%
    isPercent = true,
}

toggle

A toggle is a boolean value. In a GUI, it would be a checkbox.

Fields

name

string - Short name of the field

desc

string - Description of what the field is

get

string - Method to call to get the current value.

function - function to call to get the current value.

set

string - Method to call to set the new value (will always be the opposite of the current value).

function - function to call to set the new value (will always be the opposite of the current value).

[map]

table - Table with string values for true/false to show the current value. (default: { [false] = "Off", [true] = "On" })

[message]

string - Format string to occur if a new value is set. (default: "%s is now set to [%s]")

[current]

string - Format string to occur to tell the current value. (default: "%s is currently set to [%s]")

[disabled]

boolean - whether option is disabled (default: false)

function - function to call to get disabled state.

string - method to call based on the current handle to get the disabled state.

[hidden]

boolean - whether option is hidden. implies disabled. (default: false)

function - function to call to get hidden state.

string - method to call based on the current handle to get the hidden state.

[isRadio]

boolean - whether option should look like a radio button. has no effect on console commands. (default: false)

[handler]

table - object on which to call methods (default: inherited from parent group).

[order]

number - ordering number to determine position. (default: 100)

[guiNameIsMap]

boolean - If this is true, then the gui name will be the value of [map] instead. (default: false)

[passValue]

value - a value which will be passed to the func, disabled and hidden functions as the first argument. Note: this will replace the first argument (instead of using the option key) if it is part of a passing group.

Example

{
    type = 'toggle',
    desc = "Flick a setting on and off"
    get = function()
        return value
    end,
    set = function(v)
        value = v
    end,
    map = { [false] = "Disabled", [true] = "Enabled" }
}

color

A color is a color value, r, g, b, and optionally a. In a GUI, it would be that shiny color wheel.

Fields

name

string - Short name of the field

desc

string - Description of what the field is

get

string - Method to call to get the current value. (should return r,g,b, and optionally a)

function - function to call to get the current value. (should return r,g,b, and optionally a)

set

string - Method to call to set the new value. (arguments will be r,g,b, and optionally a)

function - function to call to set the new value. (arguments will be r,g,b, and optionally a)

[hasAlpha]

boolean - Whether the alpha (or a) value will be taken into account. (default: false)

[error]

string - Format string to occur if a given option is not valid. (default: "%s is not a valid option for %s")

[message]

string - Format string to occur if a new value is set. (default: "%s is now set to [%s]")

[current]

string - Format string to occur to tell the current value. (default: "%s is currently set to [%s]")

[disabled]

boolean - whether option is disabled (default: false)

function - function to call to get disabled state.

string - method to call based on the current handle to get the disabled state.

[hidden]

boolean - whether option is hidden. implies disabled. (default: false)

function - function to call to get hidden state.

string - method to call based on the current handle to get the hidden state.

[handler]

table - object on which to call methods (default: inherited from parent group).

[order]

number - ordering number to determine position. (default: 100)

[passValue]

value - a value which will be passed to the func, disabled and hidden functions as the first argument. Note: this will replace the first argument (instead of using the option key) if it is part of a passing group.

Example

{
    type = 'color',
    desc = "Change a color"
    get = function()
        return myR, myG, myB, myA
    end,
    set = function(r, g, b, a)
        myR, myG, myB, myA = r, g, b, a
    end,
    hasAlpha = true
}

text

A text value is typically a string value, but with special arguments it can arbitrary. In a GUI sense, this would be an editbox. If validate were a table (described below), it would be either a dropdown box or a bunch of radio buttons.

Note how the get field can also be false.

Fields

name

string - Short name of the field

desc

string - Description of what the field is

get

string - Method to call to get the current value.

function - function to call to get the current value.

false - no get function, acts like an execute that takes parameters.

set

string - Method to call to set the new value.

function - function to call to set the new value.

[input]

boolean - Whether to take in arguments as separate entities and convert to numbers automatically. (e.g. "alpha 50 bravo" converts to "alpha", 50, "bravo")

[validate]

string - Method to call to check for validation. (returning true means valid)

function - function to call to check for validation. (returning true means valid)

table - values in the table to validate against. Can either be number-indexed or string-indexed.

"keybinding" - means to check for a keybinding.

[columns]

number - How many columns the drop down list (if any) should have (waterfall only so far).

[keybindingOnly]

table - table of keybindings which accepts only the given keybindings (e.g. {BUTTON1=true, BUTTON2=true})

[keybindingExcept]

table - table of keybindings which accepts everything except the given keybindings (e.g. {BUTTON1=true, BUTTON2=true})

[multiToggle]

boolean - requires that validate be a table. Instead of functioning as a choice between multiple different values, it will act as each value is independant and can be switched on and off arbitrarily. The set function will include the key and the new value. The get function takes an extra key argument and should return a boolean based on that key.

[validateDesc]

table - when validate is a table, this will describe the values of said table using a { key = "Description" } format.

usage

string - usage string. Good practice to wrap open-ended options in "<" and ">", e.g. "<any string>". Note: if validate is set to a table or "keybinding", this is automatically set for you.

[error]

string - Format string to occur if a given option is not valid. (default: "%s is not a valid option for %s")

[message]

string - Format string to occur if a new value is set. (default: "%s is now set to [%s]")

[current]

string - Format string to occur to tell the current value. (default: "%s is currently set to [%s]")

[disabled]

boolean - whether option is disabled (default: false)

function - function to call to get disabled state.

string - method to call based on the current handle to get the disabled state.

[hidden]

boolean - whether option is hidden. implies disabled. (default: false)

function - function to call to get hidden state.

string - method to call based on the current handle to get the hidden state.

[handler]

table - object on which to call methods (default: inherited from parent group).

[icon]

string - path to icon. (default: nil)

[iconWidth, iconHeight]

number - dimensions of icon. (default: 16)

[order]

number - ordering number to determine position. (default: 100)

[passValue]

value - a value which will be passed to the func, disabled and hidden functions as the first argument. Note: this will replace the first argument (instead of using the option key) if it is part of a passing group.

Example

{
    type = 'text',
    name = "Name",
    desc = "Set your name",
    usage = "<name>",
    get = function()
        return myName
    end,
    set = function(name)
        myName = name
    end,
    validate = function(name)
        return string.find(name, "^%w $")
    end
},
-- another
{
    type = 'text',
    name = "Class",
    desc = "Set your class",
    get = function()
        return myName
    end,
    set = function(name)
        myName = name
    end,
    validate = {"Warrior", "Warlock", "Druid"}
},
-- another, this will work with WARRIOR, etc. on the backend, while showing "Warrior" to the user.
{
    type = 'text',
    name = "Class",
    desc = "Set your class",
    get = function()
        return myName
    end,
    set = function(name)
        myName = name
    end,
    validate = {["WARRIOR"] = "Warrior", ["WARLOCK"] = "Warlock", ["DRUID"] = "Druid"}
},
-- multi-toggle example
{
    type = 'text',
    name = "Class",
    desc = "Classes to help",
    multiToggle = true,
    get = function(key)
        return t[key]
    end,
    set = function(key, value)
        t[key] = value
    end,
    validate = {["WARRIOR"] = "Warrior", ["WARLOCK"] = "Warlock", ["DRUID"] = "Druid"}
},

group

A group value categorizes other options. In a GUI sense, this'd be a dropdown box or a grouping.

Fields

desc

string - Description of what the category is

[pass]

boolean - Whether to be a passing group, which would specify functions for suboptions to use. (default: false)

[get]

string - Method to call to get the current value. (used only if pass is true)

function - function to call to get the current value. (used only if pass is true)

[set]

string - Method to call to set the new value. (used only if pass is true)

function - function to call to set the new value. (used only if pass is true)

[func]

string - Method to call in an execute statement. (used only if pass is true)

function - function to call in an execute statement. (used only if pass is true)

args

table - Table of arguments, which are just more fields. Note: table keys must be either numbers or strings

[disabled]

boolean - whether option is disabled (default: false)

function - function to call to get disabled state.

string - method to call based on the current handle to get the disabled state.

[hidden]

boolean - whether option is hidden. implies disabled. (default: false)

function - function to call to get hidden state.

string - method to call based on the current handle to get the hidden state.

[handler]

table - object on which to call methods (default: inherited from parent group).

[icon]

string - path to icon. (default: nil)

[iconWidth, iconHeight]

number - dimensions of icon. (default: 16)

[order]

number - ordering number to determine position. (default: 100)

[passValue]

value - a value which will be passed to the func, disabled and hidden functions as the first argument. Note: this will replace the first argument (instead of using the option key) if it is part of a passing group.

GUI-only fields

Only use these as indicators or convenience shortcuts. They only take effect in GUIs (such as Dewdrop) and do nothing in console commands.

[onClick]

function - a function that is called when the group item is clicked.

[isChecked]

boolean - whether or not the group name should have a checkmark in front of it.

Example

{
    type = 'group',
    desc = "Magical stuff",
    args = {
        key = {
            type = 'execute',
            desc = "Make magic happen",
            func = function()
                poof()
            end
        }
    }
}
-- passing group now
{
    type = 'group'
    desc = "Other stuff",
    pass = true,
    func = function(key)
        if key == "fire" then
            fire()
        end
    end,
    args = {
        fire = {
            type = 'execute',
            desc = "Fire the cannon!"
        }
    }
}

header

A header (or blank) value, that shows up in GUIs to determine a new grouping of options.

Note: this does not show up in console-based implementations, e.g. AceConsole.

Fields

[name]

string - Name of the header. (default: "")

[disabled]

boolean - whether option is disabled (default: false)

function - function to call to get disabled state.

string - method to call based on the current handle to get the disabled state.

[hidden]

boolean - whether option is hidden. implies disabled. (default: false)

function - function to call to get hidden state.

string - method to call based on the current handle to get the hidden state.

[icon]

string - path to icon. (default: nil)

[iconWidth, iconHeight]

number - dimensions of icon. (default: 16)

[order]

number - ordering number to determine position. (default: 100)

[passValue]

value - a value which will be passed to the func, disabled and hidden functions as the first argument. Note: this will replace the first argument (instead of using the option key) if it is part of a passing group.