LibRockConfig-1.0

From WowAce Wiki

LibRockConfig-1.0 table documentation

Miscellaneous notes

• 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.
  • If two orders are equal, then they should be sorted alphabetically.
• If you provide method names, you can use "~IsGood" instead of function() return not self:IsGood() end.
• If any function or method returns "@dict", "@list", or "@set", followed by a tuple, it will automatically turn the tuple into the proper table type (a dict, list, or set), which will later be automatically recycled.

Fields for all types

name Note: this should be a few words describing the option in "Sentence case", not in "Title Case".

string - name of the option

function - function which returns the name

desc Note: this should be a full sentence in "Sentence case".

string - description of the option

function - function which returns the description

[handler]

nil - inherit from the parent option's handler if possible, otherwise inherit from the object which registered it.

table - object on which to call methods

[disabled]

nil or false - enabled (default)

true - the option is disabled.

function - function which returns a boolean, stating whether the option is disabled.

string - method name which returns a boolean, stating whether the option is disabled.

[hidden]

nil or false - shown (default)

true - the option is hidden.

function - function which returns a boolean, stating whether the option is hidden.

string - method name which returns a boolean, stating whether the option is hidden.

[order]

nil - order of 100. (default)

number - the order of the option

function - function which returns a number.

string - method name which returns a number.

[icon]

nil - no icon. (default)

string - path to the icon.

function - function which returns the path to the icon.

[iconSize]

nil - 100%. (default)

number - size of the icon as a percentage, e.g. 0.5 is 50%, 2 is 200%.

string - method name which returns the size of the icon.

function - function which returns the size of the icon.

[passValue]

nil - don't pass any values

value - pass the given value to any functions/methods belonging to the current option.

[passValue2]

nil - don't pass any more values (only pass the passValue field)

value - pass the given value to any functions/methods belonging to the current option.

[passValueN] Note: Where N is a number from 2-inf.

nil - don't pass any more values (only pass the previous passValue fields)

value - pass the given value to any functions/methods belonging to the current option.

execute

The execute type acts as a button, there is no state, but merely an action that will occur when it is triggered.

Fields

func

function - function that will be called.

string - method name that will be called.

buttonText Note: this should only be one word or so, e.g. "Click", "Okay", or "Remove". If more than one word, it should be in "Sentence case", not "Title Case".

string - name of the text on the button

function - function which returns the text on the button

[confirmText] Note: this should be a small phrase, specific if possible.

nil - no confirmation.

string - Add a confirmation message with a checkbox, showing one's desire.

function - function that should return the confirmation message.

Example

{
	type = 'execute',
	name = "My button",
	desc = "Click the button to get a pony!",
	buttonText = "Pony",
	func = function()
		message("You got a pony!")
	end,
	confirm = "Are you sure you want a pony?",
}

number

The number type allows you to select a number between a specific range.

Fields

get

number - the number the value will always be. (not recommended, use a function)

function - function that will return a number.

string - method name that will return a number.

set

function - function that will set the value of a number. This works in tandem with get, which should return said number.

string - method name that will set the value of a number.

[isPercent]

nil or false - not a percentage (default)

true - the value is a percentage. If a value is a percentage, it will show to the user as 100x larger with a percent sign.

function - function that will return whether the value is a percentage.

string - method name that will return whether the value is a percentage.

[min]

nil - 0 (default)

number - the minimum value.

function - function which returns the minimum value.

string - method name which returns the minimum value.

[max]

nil - 1 (default)

number - the maximum value.

function - function which returns the maximum value.

string - method name which returns the maximum value.

[step]

nil - (max - min)/100 (default)

number - the smallest stepsize between values. e.g. from [0, 1] with a step of 0.01 cannot ever have a value of 0.005, it would round up to 0.01.

function - function which returns the step size.

string - method name which returns the step size.

[bigStep]

nil - same as step (default)

number - the stepsize when dragging the slider, for a less specific measurement.

function - function which returns the larger step size.

string - method name which returns the larger step size.

[stepBasis]

nil - same as min (default)

number - the basis for the step movement, so that the base number does not have to be dependent on the minimum value (which may be an odd number).

function - function which returns the step basis.

string - method name which returns the step basis.

Example

local num = 0
{
	type = 'number',
	name = "It's a number!",
	desc = "A very special number.",
	get = function()
		return num
	end,
	set = function(value)
		num = value
	end,
	isPercent = true,
	step = 0.01,
	bigStep = 0.05,
	min = 0.01, -- minimum of 1%
	max = 1, -- maximum of 100%
	stepBasis = 0.05, -- so that steps go 0.01, 0.05, 0.10, 0.15 instead of 0.01, 0.06, 0.11, 0.16.
}

boolean

The boolean type allows you to switch a toggle on and off.

Fields

get

boolean - the boolean the value will always be. (not recommended, use a function)

string - can only be "HALF", anything else is an error. Means to show that it is only partially true.

function - function that will return a boolean (or "HALF")

string - method name that will return a boolean.

set

function - function that will set the value of a boolean. This works in tandem with get, which should return said boolean.

string - method name that will set the value of a boolean.

color

The color type allows you to select a color, possibly with alpha.

Fields

get

function - function that will return the value for a color (in format specified by colorType).

string - method name that will return the value for a color (in format specified by colorType).

set

function - function that will set the value of a color (in format specified by colorType). This works in tandem with get, which should return said color.

string - method name that will set the value of a color (in format specified by colorType).

[hasAlpha]

nil or false - only use red, green, and blue, without alpha level.

true - only use red, green, blue, and alpha.

function - function which returns whether alpha is used.

string - method name which returns whether alpha is used.

[colorType]

nil - use the default (either "tuple" or "tuple:rgba", based on hasAlpha)

string - use a specific color type. (see below for the list)

function - function which returns a specific color type.

Color types

• Without alpha
  • 'tuple' - values work as an r, g, b tuple, e.g. 1, 0, 0 is red. (default)
  • 'hex' - values work as an "rrggbb" hex string, e.g. "ff0000" is red.
  • 'number' - values work as a serialized number, e.g. 16711680 is red and ("%06x"):format(16711680) == "ff0000".
• With alpha
  • 'tuple:rgba' - values work as an r, g, b, a tuple, e.g. 1, 0, 0, 1 is red. (default)
  • 'tuple:argb' - values work as an a, r, g, b tuple, e.g. 1, 1, 0, 0 is red.
  • 'hex:rgba' - values work as an "rrggbbaa" hex string, e.g. "ff0000ff" is red.
  • 'hex:argb' - values work as an "aarrggbb" hex string, e.g. "ffff0000" is red.
  • Note: numbers cannot be serialized properly with alpha, as there are not enough bits to represent by an IEEE-754 double.

Example

local r, g, b
{
	type = 'color',
	name = "The colors",
	desc = "Some description of color.",
	hasAlpha = false
	colorType = 'tuple'
	get = function()
		return r, g, b
	end,
	set = function(r_, g_, b_)
		r, g, b = r_, g_, b_
	end,
}

Or

local color = "ff0000ff"
{
	type = 'color',
	name = "The colors",
	desc = "Some description of color.",
	hasAlpha = true
	colorType = 'hex:rgba'
	get = function()
		return color
	end,
	set = function(value)
		color = value
	end,
}

choice

The choice type allows you to select a value from a list of values.

Fields

get

value - the current value.

function - function that will return the current value.

string - method name that will return the current value.

set

function - function that will set the current value. This works in tandem with get, which should return said value.

string - method name that will set the current value.

choices

table - dictionary in backendValue = "value to show the user" format.

function - function which returns a choices dictionary.

string - method name which returns a choices dictionary.

[choiceType]

nil - guess either "list" or "dict" based on what choices is.

"list" - the choices is a list, do not sort automatically and treat all the values as the backend values.

"dict" - the choices is a dictionary, sort alphabetically and treat the keys as the backend values.

[choiceDescs]

nil - no description for each choice.

table - dictionary in backendValue = "Description for choice" format.

function - function which returns choiceDescs dictionary.

string - method name which returns choiceDescs dictionary.

[choiceIcons]

nil - no icons for choices.

table - dictionary in backendValue = "Icon\\path" format.

function - function which returns choiceIcons dictionary.

string - method name which returns choiceIcons dictionary.

[choiceFonts]

nil - default font. (default)

table - dictionary in backendValue = "Font\\path" format.

function - function which returns choiceFonts dictionary.

string - method name which returns choiceFonts dictionary.

[choiceTextures]

nil - no textures for choices.

table - dictionary in backendValue = "Texture\\path" format.

function - function which returns choiceTextures dictionary.

string - method name which returns choiceTextures dictionary.

[choiceOrder]

nil - no predefined order

table - list of backendValues, specifying the order of the choices.

function - function which returns choiceOrder list.

string - method name which returns choiceOrder list.

Example

local choice = "alpha"
{
	name = "Choices, choices",
	desc = "Here's a description for the choices",
	type = 'choice',
	get = function()
		return choice
	end,
	set = function(value)
		choice = value
	end,
	choices = {
		alpha = "Alpha",
		bravo = "Bravo",
		charlie = "Charlie",
	},

choiceOrder = { "alpha", "bravo", "charlie" },

}

multichoice

The multichoice type allows you to select multiple values from a list of values.

Fields

get

function - function that will return a boolean (or "HALF"), stating whether a given key is enabled.

string - method name that will return a boolean (or "HALF"), stating whether a given key is enabled.

set

function - function that will set a boolean for the given key. This works in tandem with get, which should return said boolean for the given key.

string - method name that will set a boolean for the given key.

choices

table - dictionary inbackendValue = "value to show the user" format.

function - function which returns a choices dictionary.

string - method name which returns a choices dictionary.

[choiceType]

nil - guess either "list" or "dict" based on what choices is.

"list" - the choices is a list, do not sort automatically and treat all the values as the backend values.

"dict" - the choices is a dictionary, sort alphabetically and treat the keys as the backend values.

[choiceDescs]

nil - no description for each choice.

table - dictionary inbackendValue = "Description for choice" format.

function - function which returns choiceDescs dictionary.

string - method name which returns choiceDescs dictionary.

[choiceIcons]

nil - no icons for choices.

table - dictionary inbackendValue = "Icon\\path" format.

function - function which returns choiceIcons dictionary.

string - method name which returns choiceIcons dictionary.

[choiceFonts]

nil - default font. (default)

table - dictionary inbackendValue = "Font\\path" format.

function - function which returns choiceFonts dictionary.

string - method name which returns choiceFonts dictionary.

[choiceTextures]

nil - no textures for choices.

table - dictionary inbackendValue = "Texture\\path" format.

function - function which returns choiceTextures dictionary.

string - method name which returns choiceTextures dictionary.

[choiceOrder]

nil - no predefined order

table - list of backendValues, specifying the order of the choices.

function - function which returns choiceOrder list.

string - method name which returns choiceOrder list.

Example

local choices = {}
{
	name = "Choices, choices",
	desc = "Here's a description for the choices",
	type = 'multichoice',
	get = function(key)
		return choices[key]
	end,
	set = function(key, value)
		choices[key] = value
	end,
	choices = {
		alpha = "Alpha",
		bravo = "Bravo",
		charlie = "Charlie",
	},

choiceOrder = { "alpha", "bravo", "charlie" },

}

string

The string type allows you to enter arbitrary text.

Fields

get

false - do not show a default value. Note: this causes the set to act like a one-way execute with input.

function - function that will return the current string.

string - method name that will return the current string.

set

function - function that will set the current string. This works in tandem with get, which should return said string.

string - method name that will set the current string.

[onChange]

nil - do not call a function when the text changes.

function - function that is called when the text changes.

string - method name that is called when the text changes.

[multiline] -- TODO- Actually implement this

nil or false - just a single line. (default)

true - use multiple lines.

function - function that will return whether multiple lines are used.

string - method name that will return whether multiple lines are used.

[validate]

nil - no validation (default)

function - function that will be passed the string and should return true for a proper string and false, "message" for an improper string.

string - method name that will be passed the string and should return true for a proper string and false, "message" for an improper string.

usage

string - usage text to be displayed.

function - function to return usage text.

Example

local text = "Hello"
{
	name = "Teckst Bocks",
	desc = "Here's the desc",
	type = 'string',
	get = function()
		return text
	end,
	set = function(value)
		text = value
	end,

onChange = function(value) -- do something here end, usage = "Some text",

}

or

local text = "Alpha"
{
	name = "Teckst Bocks",
	desc = "Here's the desc",
	type = 'string',
	get = function()
		return text
	end,
	set = function(value)
		text = value
	end,
	validate = function(value)
		if #value <= 4 then
			return false, "Must be at least 5 characters long."
		else
			return true,
		end
	end,

usage = "Some text at least 5 characters long.",

}

keybinding

The keybinding type allows you to enter a keybinding.

Fields

get

false - do not show a default value.

function - function that will return the current key binding.

string - method name that will return the current key binding.

set Note: this can receive either false or a string, where false is no binding.

function - function that will set the current key binding. This works in tandem with get, which should return said string.

string - method name that will set the current key binding.

[keybindingExcept]

nil - accept everything (or pass on to keybindingOnly).

table - a set of keybindings which will not be accepted.

function - function which returns a set of keybindings.

string - method name which returns a set of keybindings.

[keybindingOnly]

nil - accept everything (or pass on to keybindingExcept).

table - a set of keybindings which are the only ones to be accepted.

function - function which returns a set of keybindings.

string - method name which returns a set of keybindings.

group

The group type provides a tree-like structure to your options, allowing options to be suboptions of said group.

Fields

args

table - dictionary of sub-options in someName = { suboption } format. Keys can be anything unique.

[child_<SomeKey>]

value - this will essentially implant <SomeKey> = value onto the child table.

[child_child_<SomeKey>]

value - this will essentially implant <SomeKey> = value onto the child's child table, ad nauseum.

[groupType]

nil or "normal" : to show in a normal tree fashion.

"tab" : show in tab format. -- TODO- actually implement this

"inline" : show inline in the other options, in a collapseable group.

Example

values = {}
{
	type = 'group',
	name = "My subgroup",
	desc = "Description for the subgroup",
	child_get = function(key)
		return values[key]
	end,
	child_set = function(key, value)
		values[key] = value
	end,
	args = {
		{
			type = 'boolean',
			name = "Some value",
			desc = "Some description",
			passValue = "blah",
		},
		{
			type = 'string',
			name = "Some other value",
			desc = "Some other description",
			usage = "Some text",
			passValue = "blarg",
		},
	}
}

API Documentation

Note: This documentation is auto-generated. Please note that direct modifications may be overwritten on next autogenerate. table

:IsConfigMenuOpen([object])

Arguments

object

table - addon which the config menu could be open to

Returns

boolean - whether the config menu is open to the given addon

Example

local isOpen = Rock("LibRockConfig-1.0"):IsConfigMenuOpen(MyAddon)

:OpenConfigMenu(...)

Arguments

...

tuple - the path to open to.

Notes

• Opens the configuration menu to the current object's configuration
• This must be called after `SetConfigTable'.

Example

MyAddon:OpenConfigMenu()

:RefreshConfigMenu(object)

Arguments

object

type - (needs documentation)

Notes

• Refreshes the config menu if it is open to the current object.
• This will do nothing if the menu is closed or if it is open on a different object.
• This is very useful to call if a setting has changed not in response to someone setting an option.

Example

Rock("LibRockConfig-1.0"):RefreshConfigMenu(MyAddon)

:SetConfigSlashCommand(...)

Arguments

...

type - (needs documentation)

Notes

• Creates slash commands that link to the addon's configuration menu.

Example

MyAddon:SetConfigSlashCommand("/MyAddon")

:SetConfigTable(configTable)

Arguments

configTable

table - a configuration table.

Notes

• Sets the configuration table for the current object
• This will call Rock:GetRockConfigOptions(addon) expecting an unpacked dict as the return. The values of said dict will be placed into the extraArgs section of the configTable.
• This will also call mixin:GetEmbedRockConfigOptions(addon), in the same mechansim as the above process.

Example

MyAddon:SetConfigTable({
	...
})