Skip to content

Types

Jump to bottom
Sebastian Lindfors edited this page Feb 20, 2024 · 15 revisions

Base

LibSettings.ListItem

Field Type Description
name string Display name of the element
id string Generative identifier of the element
type function Factory function (optional, can be resolved implicitly)

LibSettings.Canvas

Inherits: Frame

Field Type Description
OnCommit function Callback function for committing
OnDefault function Callback function for resetting
OnRefresh function Callback function for refreshing

LibSettings.Variable

Inherits: LibSettings.ListItem

Field Type Description
variable string Unique variable ID of the element
search boolean Show the element in search results
tooltip string Tooltip for the element
show LibSettings.Pred Predicate(s) for showing the element
modify LibSettings.Pred Predicate(s) for allowing modification
event LibSettings.Event Event to trigger the element to update
parent string Relative key to parent initializer

LibSettings.Setting

Inherits: LibSettings.Variable

Field Type Description
default LibSettings.Value Default value of the setting
set function Callback function for setting a value
get function Function to get current value
key any Optional key for value in storage table
table table / string Table/global ref. to store value
cvar string CVar to store and access value

Category

LibSettings.Category.Canvas

Inherits: LibSettings.ListItem

Description: Canvas layout container. If this is the root node, it will be registered with Settings.RegisterCanvasLayoutCategory, otherwise it will be registered with Settings.RegisterCanvasLayoutSubcategory.

Field Type Description
frame LibSettings.Canvas Frame to insert in the canvas
anchor LibSettings.Anchors Anchor point(s) for the frame inside the canvas

LibSettings.Category.Vertical

Inherits: LibSettings.Setting

Description: Vertical layout container. If this is the root node, it will be registered with Settings.RegisterVerticalLayoutCategory, otherwise it will be registered with Settings.RegisterVerticalLayoutSubcategory.

Field Type Description
[1] table<i, LibSettings.ListItem> List of child elements

Widget

LibSettings.Types.Binding

Inherits: LibSettings.Variable

Description: Wrapper for a registered binding.

Template: KeyBindingFrameBindingTemplate

Field Type Description
binding string Binding to modify

LibSettings.Types.Button

Inherits: LibSettings.Variable

Description: Clickable button with callback.

Template: SettingButtonControlTemplate

Field Type Description
click function Callback function for the button
title string Title of the button

LibSettings.Types.CheckBox

Inherits: LibSettings.Setting

Template: SettingsCheckBoxControlTemplate

Field Type Description
default boolean Default value of the checkbox

LibSettings.Types.CheckBoxDropDown

Inherits: LibSettings.Types.CheckBox

Description: Combines a checkbox with a dropdown. The dropdown is disabled when the checkbox is unchecked.

Template: SettingsCheckBoxDropDownControlTemplate

Field Type Description
[1] LibSettings.Types.DropDown Dropdown next to the checkbox

LibSettings.Types.CheckBoxSlider

Inherits: LibSettings.Types.CheckBox

Description: Combines a checkbox with a slider. The slider is disabled when the checkbox is unchecked.

Template: SettingsCheckBoxSliderControlTemplate

Field Type Description
[1] LibSettings.Types.Slider Slider next to the checkbox

LibSettings.Types.Color

Inherits: LibSettings.Setting

Description: Color in eight-digit hex notation.

Template: SettingsListElementTemplate

Field Type Description
default string Default value of the color in hex (AARRGGBB)

LibSettings.Types.DropDown

Inherits: LibSettings.Setting

Description: Dropdown with single value selection.

Template: SettingsDropDownControlTemplate

Field Type Description
default any Default value of the dropdown
options LibSettings.Options / LibSettings.OptGen Options table or generator

LibSettings.Types.Element

Inherits: LibSettings.Variable

Description: Generic element with a name container in a vertical layout. Used for custom widgets.

Template: SettingsListElementTemplate

Field Type Description
width number Width of the element (default: 280px)
height number Height of the element (default: 26px)
extent number Extent of the element (height + padding)

LibSettings.Types.ExpandableSection

Inherits: LibSettings.ListItem

Description: Inline section that can be expanded and collapsed, and hides/shows child widgets in response.

Template: SettingsExpandableSectionTemplate

Field Type Description
expanded boolean Whether the section is expanded or not

LibSettings.Types.Header

Inherits: LibSettings.ListItem

Description: Simple text header in a vertical layout.

Template: SettingsListSectionHeaderTemplate

LibSettings.Types.Key

Inherits: LibSettings.Setting

Description: Custom binding container which responds to keyboard and gamepad input.

Template: CustomBindingButtonTemplate

Field Type Description
agnostic boolean Key chord is agnostic to meta key side
single boolean Key chord is single key

LibSettings.Types.Slider

Inherits: LibSettings.Setting

Template: SettingsSliderControlTemplate

Field Type Description
default number Default value of the slider
min number Minimum value of the slider
max number Maximum value of the slider
step number Step value of the slider
format function Function to format the slider value

LibSettings.Types.Spacer

Inherits: LibSettings.ListItem

Description: A blank line in a vertical layout.

Template: SettingsCategoryListSpacerTemplate

Result

LibSettings.Result.Base

Description: Result object from the LibSettings API, a wrapper for the Blizzard Settings API object.

Field Type Description
id string Unique identifier of the object

LibSettings.Result.Init

Inherits: LibSettings.Result.Base

Description: Basic initializer of a hierarchy widget.

Field Type Description
object Blizzard.Initializer Widget object that was created

LibSettings.Result.Setting

Inherits: LibSettings.Result.Init

Description: Initializer carrying a setting object. Includes wrapper functions to set and get the value of the setting.

Field Type Description
setValue LibSettings.SetValue Wrapped function for setting a value
getValue LibSettings.GetValue Wrapped function for getting a value

LibSettings.Result.Combined

Inherits: LibSettings.Result.Setting

Description: Initializer carrying a combined setting object. Includes wrapper functions to set and get the secondary setting value.

Field Type Description
setOption LibSettings.SetValue Wrapped function for setting an option
getOption LibSettings.GetValue Wrapped function for getting an option

LibSettings.Result.Layout

Inherits: LibSettings.Result.Base

Description: Initializer carrying a layout type, child hierarchy, and supports links to data storage.

Field Type Description
children table Nested table of created child widgets
layout Blizzard.Layout Layout object that was created
setValue LibSettings.Setter Callback function for setting a value
getValue LibSettings.Getter Callback function for getting a value

Values

LibSettings.Value

string | number | boolean

Represents the value types supported by the Settings API.

LibSettings.Pred

function | table <i, function>

Represents either a single function or a sequential table of functions. Predicates are functions that determine whether a certain condition is met.

LibSettings.Event

string | table<integer, string>

Represents either a single string or a sequential table of strings. Events are identifiers used to handle specific situations or changes in state.

LibSettings.OptionList

Mutation: Blizzard.Option

Field Type Description
[1] any Value of the option
[2] string Display name of the option
[3] string Optional tooltip line for the option

LibSettings.Options

Index Type Description
i LibSettings.OptionList The ith option in the table, where i is the index of the option

LibSettings.AnchorList

Mutation: Blizzard.Anchor

Field Type Description
[1] any Value of the option
[2] string Display name of the option
[3] string Optional tooltip line for the option

LibSettings.Anchors

Index Type Description
i LibSettings.AnchorList The ith option in the table, where i is the index of the anchor

Functions

LibSettings.SetValue

fun(value: any)

Description: Sets a value to a registered setting. This function is wrapped so that it fires all necessary callbacks and updates the value in the corresponding storage.

Parameters:

Name Type Description
value any The value to be set to the registered setting.

Returns: None.

Example:

slider.setValue(180);

LibSettings.GetValue

fun() : any

Description: Retrieves the value of a registered setting. This function is wrapped so that it retrieves the value from the corresponding storage.

Parameters: None.

Returns: The current value of the registered setting.

Example:

local value = slider.getValue(); -- 180

LibSettings.Getter

fun(internal: LibSettings.Setting, setting: Blizzard.Setting) : any

Description: Retrieves the value of a registered setting. It takes two parameters: the properties table of the setting (internal: LibSettings.Setting) and the generated setting from instantiating the properties table (setting: Blizzard.Setting). This function signature is used in table lookups when using the default table getter, or when invoked by a custom getter.

Parameters:

Name Type Description
internal LibSettings.Setting The properties table of the setting.
setting Blizzard.Setting The generated setting from instantiating the properties table.

Returns: The current value of the setting.

Example of custom function:

MyAddOn_SavedVars = {customCheckBox = false,  testCheckBox = true};

local function CustomGet(internal, setting)
    return MyAddOn_SavedVars[internal.someKey or setting:GetVariable()];
end

LibSettings({
    name  = "MyAddOn",
    get   = CustomGet,
    {
        {
            type = LibSettings.Types.CheckBox;
            name = "Use Custom Key";
            default = false;
            someKey = "customCheckBox";
        };
        {
            type = LibSettings.Types.CheckBox;
            name = "Use Variable Key";
            default = true;
            variable = "testCheckBox";
        };
    };
});

LibSettings.Setter

fun(internal: LibSettings.Setting, setting: Blizzard.Setting, value: any)

Description: Sets the value of a registered setting. It takes three parameters: the properties table of the setting (internal: LibSettings.Setting), the generated setting from instantiating the properties table (setting: Blizzard.Setting), and the value to be set. This function signature is used in table lookups when using the default table setter, or when invoked by a custom setter.

Parameters:

Name Type Description
internal LibSettings.Setting The properties table of the setting.
setting Blizzard.Setting The generated setting from instantiating the properties table.
value any The value to be set to the registered setting.

Example of custom function:

MyAddOn_SavedVars = {customCheckBox = false,  testCheckBox = true};

local function CustomSet(internal, setting, value)
    MyAddOn_SavedVars[internal.someKey or setting:GetVariable()] = value;
end

LibSettings({
    name  = "MyAddOn",
    set   = CustomSet,
    {
        {
            type = LibSettings.Types.CheckBox;
            name = "Use Custom Key";
            default = false;
            someKey = "customCheckBox";
        };
        {
            type = LibSettings.Types.CheckBox;
            name = "Use Variable Key";
            default = true;
            variable = "testCheckBox";
        };
    };
});

LibSettings.OptGen

fun(internal: LibSettings.Setting) : Blizzard.Option[]

Description: Generates options for a registered setting. It takes one parameter: the properties table of the setting (internal: LibSettings.Setting). The function returns an array of options for the setting.

Parameters:

Name Type Description
internal LibSettings.Setting The properties table of the setting.

Returns: An array of Blizzard.Option objects.

Example: (using LibSettings.OptionList and a generator)

local function CreateOptionsTable(options)
    local container = Settings.CreateControlTextContainer();
    for _, option in ipairs(options) do
        container:Add(unpack(option));
    end
    return container:GetData();
end

local function OptGen(internal)
    return CreateOptionsTable({
        {1, "Option 1", "This option has an extra tooltip line."};
        {2, "Option 2", internal.line2};
        {3, "Option 3"};
    });
end

local dropDownProps = {
    type = LibSettings.Types.DropDown;
    name = "My DropDown";
    options = OptGen;
    default = 2;
    line2 = "This is the second line of the second option.";
};

Internal

Blizzard.Anchor

Description: Internal object containing an anchor point with X and Y offsets.

Field Type Description
p FramePoint Anchor point relative to parent
x number X-offset
y number Y-offset

Blizzard.Option

Description: Internal object containing a dropdown option.

Field Type Description
value any Value of the option
name string Display name of the option
tooltip string Optional tooltip line for the option
disabled boolean Option is disabled

Blizzard.Initializer

Inherits: SettingsListElementInitializer

Description: Internal object that handles initialization of settings list elements.

Properties:

Field Type Description
Init method Initializes the settings list element with a frame template.
GetTemplate method Returns the template of the settings list element.
GetExtent method Returns the extent of the settings list element.
Factory method Creates a new instance of the settings list element.
InitFrame method Initializes the frame of the settings list element.
Resetter method Resets the settings list element to its initial state.
IsTemplate method Checks if the provided frame template matches the settings list element's template.
SetParentInitializer method Sets the parent initializer of the settings list element.
GetParentInitializer method Returns the parent initializer of the settings list element.
AddModifyPredicate method Adds a modify predicate to the settings list element.
GetModifyPredicates method Returns the modify predicates of the settings list element.
GetEvaluateStateFrameEvents method Returns the evaluate state frame events of the settings list element.
AddEvaluateStateFrameEvent method Adds an evaluate state frame event to the settings list element.
Indent method Indents the settings list element.
IsParentInitializerInCurrentSettingsCategory method Checks if the parent initializer is in the current settings category.
GetIndent method Returns the indent of the settings list element.
GetData method Returns the data of the settings list element.
GetName method Returns the name of the settings list element.
GetTooltip method Returns the tooltip of the settings list element.
GetOptions method Returns the options of the settings list element.
SetSetting method Sets the setting of the settings list element.
GetSetting method Returns the setting of the settings list element.
IsNewTagShown method Checks if the new tag is shown for the settings list element.
SetSettingIntercept method Sets the setting intercept function of the settings list element.
GetSettingIntercept method Returns the setting intercept function of the settings list element.

Blizzard.Setting

Inherits: AddOnSettingMixin

Description: Internal object that handles representation, states and callbacks for a registered addon setting.

Properties:

Field Type Description
Init method Initializes the setting with a name, variable, and variable type.
AddCommitFlag method Adds a flag that determines how the setting is committed.
Commit method Commits the setting's current value.
GetCommitOrder method Returns the order in which the setting is committed.
GetDefaultValue method Gets the setting's default value.
GetDefaultValueInternal method Returns the default value of the add-on setting.
GetOriginalValue method Returns the original value of the setting.
GetName method Returns the name of the setting.
GetVariable method Returns the variable associated with the setting.
GetVariableType method Returns the type of the variable associated with the setting.
GetValue method Returns the current value of the setting.
GetValueInternal method Returns the current value of the add-on setting.
HasCommitFlag method Checks if the setting has a specific commit flag.
IsModified method Checks if the setting has been modified.
IsNewTagShown method Checks if the new tag is shown for the setting.
ReinitializeValue method Reinitializes the value of the setting.
RemoveCommitFlag method Removes a flag from the setting's commit flags.
Revert method Reverts the setting to its original value.
SetCommitFlags method Sets the flags that determine how the setting is committed.
SetCommitOrder method Sets the order in which the setting is committed.
SetIgnoreApplyOverride method Sets whether the setting should ignore apply overrides.
SetNewTagShown method Sets whether the new tag is shown for the setting.
SetValue method Sets the value of the setting. If force is true, the value is set even if it's the same as the current value.
SetValueInternal method Sets the value of the add-on setting.
SetValueToDefault method Sets the setting's value to its default value.
UpdateIgnoreApplyFlag method Updates the setting's ignore apply flag based on its current state.

Blizzard.Category

Inherits: SettingsCategoryMixin

Description: Internal object that handles representation, states and callbacks for a registered addon category.

Properties:

Field Type Description
Init method Initializes the settings category with a name.
GetID method Returns the ID of the settings category.
GetName method Returns the name of the settings category.
SetName method Sets the name of the settings category.
GetOrder method Returns the order of the settings category.
SetOrder method Sets the order of the settings category.
GetQualifiedName method Returns the qualified name of the settings category.
GetParentCategory method Returns the parent category of the settings category.
SetParentCategory method Sets the parent category of the settings category.
HasParentCategory method Checks if the settings category has a parent category.
SetCategorySet method Sets the category set of the settings category.
GetCategorySet method Returns the category set of the settings category.
GetSubcategories method Returns the subcategories of the settings category.
HasSubcategories method Checks if the settings category has subcategories.
CreateSubcategory method Creates a subcategory for the settings category.
SetCategoryTutorialInfo method Sets the tutorial information for the settings category.
GetCategoryTutorialInfo method Returns the tutorial information for the settings category.

Blizzard.Layout

Inherits: SettingsLayoutMixin

Description: Internal object for managing and initializing layout settings.

Properties:

Field Type Description
LayoutType Enum An enumeration with possible values "Vertical" and "Canvas".
Init method Initializes the settings layout with a layout type.
GetLayoutType method Returns the layout type of the settings vertical layout.
IsVerticalLayout method Checks if the layout type is vertical.

Blizzard.Vertical

Inherits: Blizzard.Layout, SettingsVerticalLayoutMixin

Description: Internal object for managing and initializing vertical layout settings.

Field Type Description
Init method Initializes the settings layout with a vertical layout type.
GetInitializers method Returns the initializers of the settings vertical layout.
IsEmpty method Checks if the settings vertical layout is empty.
AddInitializer method Adds an initializer to the settings vertical layout.
AddMirroredInitializer method Adds a mirrored initializer to the settings vertical layout.
EnumerateInitializers method Enumerates the initializers of the settings vertical layout.

Blizzard.Canvas

Inherits: Blizzard.Layout, SettingsCanvasLayoutMixin

Description: Internal object for managing and initializing a canvas layout.

Properties:

Field Type Description
Init method Initializes the settings canvas layout with a frame.
GetFrame method Returns the frame of the settings canvas layout.
AddAnchorPoint method Adds Blizzard.Anchor to the settings canvas layout.
GetAnchorPoints method Returns the anchor points of the settings canvas layout.

Clone this wiki locally