An alternative to using the AceGUI container BlizOptionsGroup to create entries in the Blizzard options panel. All entries created use the same frame objects allowing for minimal memory use. An entry can be created and an options table assigned to it later allowing for LOD options. The library monitors for AceConfigDialog-3.0, AceConfigRegistry-3.0, and AceGUI-3.0 to be loaded before using them to further facilitate LOD behavior.
Example usage (basic):
Code:
-- In main module (myAddon):
myAddon.config = LibStub('LibOptionsAssist-1.1').AddEntry("myAddon", nil, "myAddon_Config")
myAddon.config:SetInfo(format("Version: %s", GetAddOnMetadata("myAddon", 'Version')))
-- In LOD module (myAddon_Config):
LibStub('AceConfigRegistry-3.0'):RegisterOptionsTable("myAddon", myAddon.options)
myAddon.config:AssignOptions("myAddon")
Example usage (w/ FetchData):
Code:
-- In main module:
local addonName, addon = ...
addon.config = LibStub('LibOptionsAssist-1.1').AddEntry(addonName, nil, { addonName .. "_Config", addonName, addon })
addon.config:SetInfo(format("Version: %s", GetAddOnMetadata(addonName, 'Version')))
-- In LOD module:
local addonName, addon = LibStub('LibOptionsAssist-1.1').FetchData()
LibStub('AceConfigRegistry-3.0'):RegisterOptionsTable(addonName, addon.options)
addon.config:AssignOptions(addonName)
API
entry = lib.AddEntry(name [, parent [, loadOnDemand [, key]]])
Add an entry to Blizzard's interface options panel under the AddOns tab.
Arguments:
name - (string) The text to appear in the Blizzard options panel under the AddOns tab.
parent - (string) If this is to be a child entry then this should be the name that was used to create
the parent entry.
loadOnDemand - (string) If it is a child entry and the string "parent" is initially passed then the load on demand behavior of the parent will be used instead.(function) Will be run the first time the entry is selected, passing entry as it's only argument. Any returns will be placed into the array portion of a table and processed as if that table was given.
(table) The value at index 1 should be a string and will be processed as if that string was given. Any remaining array values will be available as returns from the lib.FetchData function.
(string) An addon with that name will be loaded if it isn't already.
key - (any) A value used to prevent the Recycle method from removing the metatable from the entry.
Returns:
entry - (table) A table with the required fields to work with the Blizzard options panel (see Entries below).
... = lib.FetchData()
Returns any available values during the load on demand processing as described in the lib.
AddEntry function.
Returns:
... - (any) Values available for return.
index, entry = lib.HasEntry(name [, parent])
Determines if an entry is in Blizzard's interface options panel under the AddOns tab.
Arguments:
name - (string) The name of the entry to check for.
parent - (string) The name of the parent entry if a child is being looked for.
Returns:
index - (number) Index of the entry or nil if it doesn't exist.
entry - (table) The table for the entry or nil if it doesn't exist.
for index, entry in lib.IterateEntries([parent]) do
Acts as a special case ipairs for Blizzard's INTERFACEOPTIONS_ADDONCATEGORIES table.
Arguments:
parent - (string) If a string is provided then all entries returned will be children of that parent, otherwise only entries with no parent are returned.
Returns:
index - (number) Index of the entry.
entry - (table) The table for the entry.
loaded, reason = lib.LoadModule(name)
Loads an addon even if it, or a dependency, is disabled.
Arguments:
name - (string) The addon's name as it appears in the Interface\AddOns folder.
Returns:
loaded - (boolean) Whether or not the addon is loaded.
reason - (string) If the addon is not loaded then this will be the reason why.
entry = lib.OpenEntry(name [, parent [, toggle]])
Open an entry in Blizzard's interface options panel under the AddOns tab.
Arguments:
name - (string) The name of the entry to open.
parent - (string) The name of the parent entry if a child is being opened.
toggle - (boolean) Set to evaluate as true to close entry if it is already open.
Returns:
entry - (table) The table for the entry if open or nil.
entry = lib.OpenNextMember(name [, resume])
Open a parent entry, or one of it's children (if any), in Blizzard's interface options panel under the AddOns tab. Each call opens an entry going in sequential order, cycling back to the parent after the last child has been opened.
Arguments:
name - (string) The name of the parent entry of the members to open.
resume - (boolean) Set to evaluate as true to start with the first member shown but not visible.
Returns:
entry - (table) The table for the entry if open or nil.
lib.RemoveEntry(name [, parent])
Removes an entry, and any children, from Blizzard's interface options panel under the AddOns tab.
Arguments:
name - (string) The name of the entry to remove.
parent - (string) The name of the parent entry if a child is being removed.
lib.SortChildren(parent [, sortFunc])
Sort the children of an entry.
Arguments:
parent - (string) The name of the parent entry whose children are to be sorted.
sortFunc - (function) An optional function to be used for determining the order of the child entries. A default function will be used if none is provided that ignores case, color codes, and extra spaces.
Entries
Any entry created by lib.AddEntry() is a normal table that emulates certain frame methods to allow it to work in the Blizzard options panel. A metatable provides the following frame-like methods: ClearAllPoints, GetScript, HasScript, Hide, IsShown, IsVisible, SetAllPoints, SetParent, SetPoint, SetScript, SetShown, and Show. The only scripts supported by an entry are OnHide and OnShow. The metatable also provides a dummy function for the fields: cancel, defaults, okay, and refresh.
The entry may also be treated like a function, with entry() being the same as entry:Open(). Entries also have the following additional methods:
entry:AssignOptions(name [, ...])
Set the AceConfigRegistry-3.0 table to be used to display options when the entry is selected.
Arguments:
name - (string) A name as from an AceConfigRegistry-3.0 RegisterOptionsTable call.
... - Zero or more table keys that lead to a sub-table.
entry:FlagAsLoaded()
Cancel any pending load on demand behavior for the entry.
desc = entry:GetDesc()
Get the value currently set to be displayed for the entry's description text.
Returns:
desc - (string) The current value of the description text.
info = entry:GetInfo()
Get the value currently set to be displayed for the entry's information text.
Returns:
info - (string) The current value of the information text.
title = entry:GetTitle()
Get the value currently set to be displayed for the entry's title text.
Returns:
title - (string) The current value of the title text.
entry = entry:Open(toggle)
Opens entry in Blizzard's interface options panel under the AddOns tab.
Arguments:
toggle - (boolean) Set to evaluate as true to close entry if it is already open.
Returns:
entry - (table) The table for the entry if open or nil.
entry:Recycle([key])
Removes the entry, and any children, from Blizzard's options panel. May also optionally remove the metatable from entry as well as removing all internal references so that it may be be garbage collected.
Arguments:
key - (any) This value must match what was provided via AddEntry or SetKey to remove the metatable and allow garbage collection.
entry:Refresh()
Force a display update of the assigned options.
entry:SetDesc(desc)
Set the description text to be displayed. This text is small, left-aligned, and below the title.
Arguments:
desc - (string) The text to be displayed.
entry:SetInfo(info)
Set the information text to be displayed. This text is small, right-aligned, and opposite the title.
Arguments:
info - (string) The text to be displayed.
success = entry:SetKey(newKey, oldKey)
Set the value needed to completely Recycle entry.
Arguments:
newKey - (any) The value that key should be set to.
oldKey - (any) The current value needed to fully Recycle entry.
Returns:
success - (boolean or nil) True if the key was changed, nil otherwise.
entry:SetTitle(title)
Set the title text to be displayed. This text is large, left-aligned, and anchored in the upper-left corner. When an entry is first created with lib.AddEntry() the title is automatically set to the name given.
Arguments:
title - (string) The text to be displayed.