AceConfig3

From WowAce Wiki
Jump to: navigation, search

Also see ACE-23 for discussion

Config library implementors: see AceConfig3 Implementation Details.

Table format basics

The AceOptions table format is a standardized way of representing the commands available to control an addon. It is understood by several configuration libraries, such as AceConfigCmd, AceConfigDialog, AceConfigDropdown, and others.

An example table, very minimalistic:

myOptionsTable = {
  type="group",
  args={
    enable={
      name="Enable",
      desc="Enables / disables the addon",
      type="toggle",
      set = function(info,val) MyAddon.enabled = val end,
      get = function(info) return MyAddon.enabled end
    },
    moreoptions={
      name="More Options",
      type="group",
      args={
        more options go here
      }
  }
}

Common parameters

  • name (string|function) - display name for the option
  • desc (string|function) - description for the option (or nil for a self-describing name)
  • validate (methodname|function|false) - validate the input/value before setting it. return a string (errormessage) to indicate error. (see Callback Arguments)
  • confirm (methodname|function|boolean) - prompt for confirmation before changing a value
  • true - display "name - desc", or contents of .confirmText
  • function - return a string (prompt to display) or true (as above), or false to skip the confirmation step (see Callback Arguments)
Note that AceConfigCommand does not do confirmation at all.
  • order (number|methodname|function) - relative position of item (default = 100, 0=first, -1=last)
  • disabled (methodname|function|boolean) - disabled but visible
  • hidden (methodname|function|boolean) - hidden (but usable if you can get to it, i.e. via commandline)
  • guiHidden (boolean) - hide this from graphical UIs (dialog, dropdown)
  • dialogHidden (boolean) - hide this from dialog UIs
  • dropdownHidden (boolean) - hide this from dropdown UIs
  • cmdHidden (boolean)- hide this from commandline
  • icon (string|function) - path to icon texture, e.g.
  • iconCoords (table|methodname|function) - arguments to pass to SetTexCoord, e.g. {0.1,0.9,0.1,0.9}.
  • handler (table) - object on which getter/setter functions are called if they are declared as strings rather than function references
  • type (string) - "execute", "input", "group", etc; see below
  • width (string) - "double", "half", "full", in a gui provide a hint for how wide this option needs to be. (optional support in implementations)
    • default is nil (not set)
    • double, half - increase / decrease the size of the option
    • full - make the option the full width of the window
    • TODO: What exactly is "full"? And what is the default? --Mikk 00:30, 29 January 2008 (EST)

Common item types

execute

A execute option will simply run 'func'. In a GUI, this would be a button.

  • func (function|methodname) - function to execute

input

A simple text input, with an optional validate string or function to match the text against.

  • pattern (string) - optional validation pattern. (Use the validate field for more advanced checks!)
  • usage (string) - usage string (displayed if pattern mismatches and in console help messages)
  • get (function|methodname) - getter function
  • set (function|methodname) - setter function
  • multiline (boolean) - if true will be shown as a multiline editbox in dialog implementations

toggle

A simple checkbox

  • get (function|methodname) - getter function
  • set (function|methodname) - setter function
  • tristate (boolean) - Make the toggle a tri-state checkbox. Values are cycled through unchecked (false), checked (true), greyed (nil) - in that order.

range

A option for configuring numeric values in a specific range. In a GUI, a slider.

  • min - min value
  • max - max value
  • step - step value: "smaller than this will break the code" (default=no stepping limit)
  • bigStep - a more generally-useful step size. Support in UIs is optional.
  • get (function|methodname) - getter function
  • set (function|methodname) - setter function
  • isPercent (boolean) - represent e.g. 1.0 as 100%, etc. (default=false)

select

Only one of the values can be selected. In a dropdown menu implementation it would likely be a radio group, in a dialog likely a dropdown combobox.

  • values (table|function) - [key]=value pair table to choose from, key is the value passed to "set", value is the string displayed
  • get (function|methodname) - getter function
  • set (function|methodname) - setter function
  • style - "dropdown", "radio" (optional support in implementations) AceConfigDialog does not implement it. -- Adirelle 10:03, 30 July 2008 (EDT)

multiselect

Basically multiple "toggle" elements condensed into a group of checkboxes, or something else that makes sense in the interface.

  • values (table|function) - [key]=value pair table to choose from, key is the value passed to "set", value is the string displayed
  • get (function|methodname) - will be called for every key in values with the key name as last parameter
  • set (function|methodname) - will be called with keyname, state as parameters
  • tristate (boolean) - Make the checkmarks tri-state. Values are cycled through unchecked (false), checked (true), greyed (nil) - in that order.

color

Opens a color picker form, in GUI possibly a button to open that.

  • get (function|methodname) - getter function
  • set (function|methodname) - setter function
  • hasAlpha (boolean) - indicate if alpha is adjustable (default false)

Getter/setter functions use 4 arguments/returns: r,g,b,a. If hasAlpha is false/nil, alpha will always be set() as 1.0.

keybinding

  • get (function|methodname) - getter function
  • set (function|methodname) - setter function


Special item types

header

  • a heading
  • in commandline and dropdown UIs shows as a heading
  • in a dialog UI it will additionaly provide a break in the layout

description

  • a paragraph of text to appear next to other options in the config
  • name is the text to display
  • image (string|function) - path to image texture, if this is a function it can optionally return the width and height of the image as the 2nd and 3rd value, these will be used instead of imageWidth and imageHeight.
  • imageCoords (table|methodname|function) - arguments to pass to SetTexCoord, e.g. {0.1,0.9,0.1,0.9}.
TODO: What should imageCoords functions return? A table or an argument list? I'd be in favor of an argument list personally for less garbage; the function call would simply be the last param to SetTexCoord so you can use 4 or 8 args. --Mikk 10:57, 13 February 2008 (EST)
Table is easier to use because imageCoords already can be a table, easy to switch between those values. --Nevcairiel 11:00, 13 February 2008 (EST)
  • imageWidth (number) - Width of the displayed image
  • imageHeight (number) - Height of the displayed image

group

The first table in an aceoptions table is implicitly a group. You can have more levels of groups by simply adding another table with type="group" under the first args table.


  • args subtable with more items/groups in it
  • plugins subtable, containing named tables with more args in them, e.g.
plugins["myPlugin"]={
  option1={...}, option2={...}, group1={...} }
plugins["otherPlugin"]={...}
This allows modules and libraries to easily add more content to an addon's options table.


  • childGroups argument, decides how children groups of this group are displayed:
  • "tree" (the default) - as child nodes in a tree control
  • "tab" - as tabs
  • "select" - as a dropdown list
Only dialog-driven UIs are assumed to behave differently for all types.


  • inline (boolean) - show as a bordered box in a dialog UI, or at the parent's level with a separate heading in commandline and dropdown UIs.
  • cmdInline (boolean) - as above, only obeyed by commandline
  • guiInline (boolean) - as above, only obeyed by graphical UIs
  • dropdownInline (boolean) - as above, only obeyed by dropdown UIs
  • dialogInline (boolean) - as above, only obeyed by dialog UIs

Callback handling

  • For each set/get/func/validate/confirm callback attempted, the tree will ALWAYS be traversed toward the root until such a directive is found. Similarly, if callbacks are given as strings, the tree will be traversed to find a "handler" argument.
  • To declare that an inherited value is NOT to be used even though a parent has it, set it to false. This is primarily useful for validate and confirm, but is allowed for all inherited values including "handler".

Callback Arguments

All callback receive a standardized set of arguments:

(info, value[, value2, ...]).


The info table contains:

  • An "options" member pointing at the root of the options table
  • The name of the slash command at position 0, or empty string ("") if not a slash.
  • The name of the first group traversed into at position 1
  • The node name at position n (may be 1 if at the root level)
  • Hint: Use info[#info] to get the leaf node name, info[#info-1] for the parent, and so on!
  • An "arg" member if set in the node.
  • A "handler" member which is the handler object for the current option.
  • A "type" member which is the type of the current option.
  • An "option" member pointing at the current option.
  • "uiType" and "uiName" members, which are the same as the parameters passed when retrieving the options table from AceConfigRegistry-3.0

The callback may not assume ownership of the infotable. The config parser is assumed to reuse it. It may also contain more members, but these are outside the spec and may change at any time -- do not use information in undocumented infotable members.

! Callbacks on the form handler:"methodname" will of course be passed the handler object as the first ("self") argument.

Callback Example

local function mySetterFunc(info, value)
  db[info[#info]]=value   -- we use the db names in our settings for Zzz
  print("The " .. info[#info] .. " was set to: " .. tostring(value) )
end

On the drawing table

control / dialogControl / dropdownControl

A way of registering a custom control with AceGUI and having it be used for editing in GUIs. The base type would still be "type=input", allowing text interfaces or non-AceGUI GUIs to display it. In a non-userfriendly way, certainly, but at least it would be displayed. (And the potential nonuserfriendliness comes from how the custom control choses to represent its data)

  • I think extending this to type = 'select' would allow for some custom controls that would be useful, e.g. texture selector with previews --Nargiddley 04:58, 6 February 2008 (EST)
    • Any reason why this cant be extended to all types? --Yssaril 00:22, 6 April 2008 (EDT)

Examples could include:

  • A draggable item/spell/macro button (for things like Autobar)
The data format would be alternatively: Itemlinks, Spell names, "macro: <macro params, tbd>"
  • A calendar control
The data format could be e.g. 2007-10-27, plenty user friendly.

Widget API requred to be implemented by custom AceGUI widgets when used with AceConfigDialog-3.0 (this part of the spec is not finalised)

  • type = 'input'
    •  :SetDisabled(disabled)
      • diasbled - boolean, whether the control is disabled
    •  :SetLabel(text)
      • text - string, The name of the option to be displayed
    •  :SetText(text)
      • text - string, the contents of the EditBox.
    • Callback OnEnterPressed(text), fired when the text has changed and should be saved.
  • type = 'select'
    •  :SetDisabled(disabled)
      • diasbled - boolean, whether the control is disabled
    •  :SetValue(value)
      • value - string, The value that is currently selected.
    •  :SetList(list)
      • list - table, A { value = text } table of the options to be displayed.
    •  :SetLabel(text)
      • text - string, The name of the option to be displayed
    • Callback OnValueChanged(value), fired when a value is selected, this must be a key from the list table.

Both should also fire OnEnter and OnLeave callbacks for tooltips to work.