LibRockConfig-1.0

From WowAce Wiki
Jump to: navigation, search

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({
	...
})