EasyOptions

The easy way to build a World of Warcraft addon!

Quick Start Guide

Install EasyOptions (this addon).
Install the EasyOptionsExamples addon to explore examples in-game or as source code.
Install the EasyOptionsTemplate or EasyOptionsTemplateBasic addons. Follow a few instructions included in those addons.
Done!

Developer Benefits

Makes it quick and easy to add options to any new or existing addon.
One line per option is all you need!
Provides an intuitive and modernized process that eliminates the need for many tedious tasks.
Simplifies addon development, allowing developers to spend more time adding features.
Includes advanced control types that add enhanced functionality with minimal effort.
No need to include libraries in your addon.
- Helpful functions are also provided to assist in the development of your addon.

Player Benefits

Automatically allows players to save, load, and manage different sets of options for all addons that implement EasyOptions.
Automatically allows players to reset individual options to their default values by right clicking the desired control or reset all options by clicking a button.

Resources

EasyOptionsExamples

Highly recommended.
Provides a large set of examples showing how to use EasyOptions.
Explore examples in-game or as source code.
You may copy any code from EasyOptionsExamples into your addon.

EasyOptionsTemplate

Recommended as a starting point if you are creating a standard or complex addon.
Includes built-in support for EasyOptions.
Makes it quick and easy to start using EasyOptions in a new or existing addon.
Instructions are included in the addon.

EasyOptionsTemplateBasic

Recommended as a starting point if you are creating a minimalistic addon.
Includes built-in support for EasyOptions.
Makes it quick and easy to start using EasyOptions in a new or existing addon.
Instructions are included in the addon.

HealthWarning

A fully functional addon.
Uses EasyOptions to provide a rich set of over 200 options with ease.
Check it out to see what is possible!

Features

Designed to simplify addon development.
Built for maximum compatibility. Works in all playable versions of WoW (from Vanilla through the latest retail version) while avoiding version-specific code.
You choose your format. Declare your options in a condensed indexed format, a traditional parameter name format, or a combination of those formats.
Provides a large set of control types and command types.
No need to include libraries in your addon.
Highly consistent code contained in a single addon make it easy to navigate and review the source code.
Automatically updates the values of your options.
Automatically handles the layout of your controls with high precision so the controls in your options frames are aligned and look clean.
Automatically sizes container controls like GroupBoxes, TabControls, and ListViews to fit their contents. This behavior can be overridden by specifying a custom size.
Automatically handles disabling indented controls under a CheckBox control when the CheckBox is unchecked. This behavior can be fully disabled or controlled manually.
Automatically adds support for allowing the user to save, load, and manage different sets of options for your addon, either through EasyOptions' Addon Manager or with a macro.
Automatically adds support for allowing the user to reset options to their default values by right clicking an individual control or by clicking a Reset All button.
Uses an intuitive Start-End format for building rows of controls or container controls like GroupBoxes, TabControls, and ListViews.
Allows for custom layouts through intuitive commands such as StartRow, EndRow, SetPosition, MovePosition, SavePosition, and RestorePosition.
Easily include a minimap button for your addon with the ShowMinimapIcon control type. You only need to specify the default visible state (true or false) and an icon. EasyOptions handles the rest!
TextBox and MultiLineTextBox control types can store their option value as a delimited array of strings. Simply specify the desired DelimiterInfo and EasyOptions handles the conversion between the displayed text and the stored array of strings.
Advanced control types such as EditableDropDown, ColorPicker, FontFilePath, or SoundFilePath add enhanced functionality with ease.
Supports user-defined custom control types.
Provides control types for managing frames, such as a frame's state, size, position, and scale.
Implements logic to maintain a frame's position as the frame's size is scaled.
Provides callback method support so your addon can be notified when an individual option value has changed or when any option value has changed (in which case the option name is provided).
Provides numerous support methods that simplify and standardize common tasks such as printing messages or showing dialog windows.
Provides a Format method that automatically formats various value types and tables. Also supports .NET-style format strings (e.g., EasyOptions:Format("Value1 = {1}, Value2 = {2}", value1, value2)).
Provides a localization function that integrates localization with .NET-style format string support and allows the localization table for your addon's default language (e.g., enUS) to be empty.
Supported by the EasyOptionsExamples addon which demonstrates all the above features.
Supported by the EasyOptionsTemplate and EasyOptionsTemplateBasic addons to help you get started quickly and easily. Instructions are included in those addons.

Development Basics

EasyOptions uses OptionItems to define your options. OptionItems can be declared using a condensed indexed format, a traditional parameter name format, or a combination of those formats. Parameter name format takes precedence over indexed format if a value is assigned to the same parameter using both formats.

It is highly recommended that you install the EasyOptionsExamples addon for a large set of examples and use either the EasyOptionsTemplate addon or the EasyOptionsTemplateBasic addon as a starting point if you are building a new addon. Those addons were specifically created to make your life easier.

Common OptionItem Format

[1] Name, [2] Text (Optional), [3] TooltipText (Optional), [4] PositionInfo (Optional), [5] Type

Note: The above format is shared by all OptionItems, although some OptionItem types ignore one or more of the parameters. Many OptionItem types also support additional parameters.

Parameter Descriptions:

Name

Specifies the name of the OptionItem which must be unique within your addon. The name is also used as the key of the entry in your addon's saved variables table that stores the value of this item.

Example: If the name of your addon's saved variables table is MyCoolAddonDB and the Name of an OptionItem is "MyCoolOption", then MyCoolAddonDB["MyCoolOption"] will contain the value of that option.

Text

Specifies the text that is displayed for the control. If a control has a label then this text will be displayed in the control's label, otherwise this text will be displayed in the control.

Note: This is not the text that is displayed in a TextBox or similar control. The DefaultValue parameter determines the default text that is displayed in those control types.

TooltipText

Specifies the text for the tooltip that is associated with the OptionItem's control.

PositionInfo

Specifies the position information for the control. The default position for the control will be used if the value of this parameter is nil.

See below for supported formats

Type (or ControlType)

Specifies the control type or command type. See below for a list of possible types and their corresponding formats.

Examples:

Indexed format:

{"SettingsTabControl", "Settings", "Contains settings for this addon.", 0, "StartTabControl"}

Parameter name format:

{

Name = "SettingsTabControl",

Text = "Settings",

TooltipText = "Contains settings for this addon.",

PositionInfo = 0,

Type = "StartTabControl"

}

OptionItem Types and Type-specific Formats

Hidden

[6] DefaultValue (Any Value or Table)

GroupTitle

[6] Size (Optional), [7] WordWrap (Optional), [8] FontInfo (Optional), [9] TextColor (Optional), [10] IncludeUnderline (Optional), [11] UnderlineWidth (Optional)

GroupBox

[6] Size (Optional), [7] FontInfo (Optional), [8] TextColor (Optional)

StartGroupBox

[6] Size (Optional), [7] AutoFitWidth (Optional), [8] AutoFitHeight (Optional), [9] FontInfo (Optional), [10] TextColor (Optional)

EndGroupBox

N/A

StartTabControl

[6] TabsOnBottom (Optional), [7] Size (Optional), [8] AutoFitWidth (Optional), [9] AutoFitHeight (Optional), [10] FontInfo (Optional), [11] TextColor (Optional)

EndTabControl

N/A

StartTab

[6] Width (Optional), [7] OnClickHandler (Optional)

EndTab

N/A

StartListView

[6] ListViewPanelWidth (Optional), [7] Size (Optional), [8] AutoFitWidth (Optional), [9] AutoFitHeight (Optional), [10] FontInfo (Optional), [11] TextColor (Optional)

EndListView

N/A

StartListViewItem

[6] OnClickHandler (Optional)

EndListViewItem

N/A

Label

[6] Size (Optional), [7] WordWrap (Optional), [8] FontInfo (Optional), [9] TextColor (Optional), [10] IncludeUnderline (Optional), [11] UnderlineWidth (Optional)

Separator

[6] Width (Optional)

Button

[6] Size (Optional), [7] OnClickHandler

ReloadUIButton

Same as Button.

CheckBox

[6] DefaultValue, [7] FontInfo (Optional), [8] TextColor (Optional), [9] OnOptionValueChangedHandler (Optional), [10] OnClickHandler (Optional)

StartCheckBoxGroup

Same as CheckBox.

EndCheckBoxGroup

N/A

EndAllCheckBoxGroups

N/A

RadioButton

[6] DefaultValue, [7] RadioButtonGroupName, [8] FontInfo (Optional), [9] TextColor (Optional), [10] OnOptionValueChangedHandler (Optional), [11] OnClickHandler (Optional)

RadioButtonGroup

[6] DefaultValue, [7] RadioButtonInfos, [8] AlignAsRow (Optional), [9] FontInfo (Optional), [10] TextColor (Optional), [11] OnOptionValueChangedHandler (Optional), [12] OnClickHandler (Optional)

DropDown

[6] DefaultValue, [7] DropDownItemInfos, [8] Width (Optional), [9] FontInfo (Optional), [10] TextColor (Optional), [11] OnOptionValueChangedHandler (Optional), [12] OnClickHandler (Optional), [13] OnValueChangedHandler (Optional)

EditableDropDown

[6] DefaultValue, [7] DropDownItemInfos, [8] Width (Optional), [9] ShowTextBox (Optional), [10] TextBoxWidth (Optional), [11] FontInfo (Optional), [12] TextColor (Optional), [13] TextBoxTooltipText (Optional), [14] TestButtonText (Optional), [15] TestButtonTooltipText (Optional), [16] OnTestHandler (Optional), [17] OnOptionValueChangedHandler (Optional), [18] OnClickHandler (Optional), [19] OnValueChangedHandler (Optional)

TextBox

[6] DefaultValue, [7] Width (Optional), [8] LabelFontInfo (Optional), [9] LabelTextColor (Optional), [10] DelimiterInfo (Optional), [11] OnOptionValueChangedHandler (Optional), [12] OnTextAcceptedHandler (Optional), [13] OnTextChangedHandler (Optional)

ValueBox

[6] DefaultValue, [7] MinValue (Optional), [8] MaxValue (Optional), [9] FormatString (Optional), [10] Width (Optional), [11] LabelFontInfo (Optional), [12] LabelTextColor (Optional), [13] OnOptionValueChangedHandler (Optional), [14] OnTextAcceptedHandler (Optional), [15] OnTextChangedHandler (Optional)

MultiLineTextBox

[6] DefaultValue, [7] Size (Optional), [8] LabelFontInfo (Optional), [9] LabelTextColor (Optional), [10] DelimiterInfo (Optional), [11] OnOptionValueChangedHandler (Optional), [12] OnTextAcceptedHandler (Optional), [13] OnTextChangedHandler (Optional)

Slider

[6] DefaultValue, [7] MinValue, [8] MaxValue, [9] ValueStep, [10] FormatString (Optional), [11] LabelPositionInfo (Optional), [12] Width (Optional), [13] ValueBoxWidth (Optional), [14] ValueBoxPositionInfo (Optional), [15] LabelFontInfo (Optional), [16] LabelTextColor (Optional), [17] OnOptionValueChangedHandler (Optional), [18] OnValueChangedHandler (Optional)

ColorPicker

[6] DefaultValue, [7] Size (Optional), [8] BorderWidth (Optional), [9] LabelPositionInfo (Optional), [10] FontInfo (Optional), [11] TextColor (Optional), [12] OnOptionValueChangedHandler (Optional)

SoundChannel

[6] DefaultValue

SoundFilePath

[6] DefaultValue, [7] DropDownItemInfos (Optional), [8] IncludeDefaultItemInfos (Optional), [9] GetSoundChannel (Optional), [10] DropDownWidth (Optional), [11] ShowTextBox (Optional), [12] TextBoxWidth (Optional), [13] OnOptionValueChangedHandler (Optional)

FontFilePath

[6] DefaultValue (Optional), [7] DropDownItemInfos (Optional), [8] IncludeDefaultItemInfos (Optional), [9] DropDownWidth (Optional), [10] ShowTextBox (Optional), [11] TextBoxWidth (Optional), [12] OnOptionValueChangedHandler (Optional)

FontSize

Same as Slider.

ShowMinimapIcon

[6] DefaultValue, [7] MinimapIconFilePath, [8] MinimapIconText (Optional), [9] MinimapIconTooltipText (Optional), [10] OnMinimapIconClickHandler (Optional), [11] FontInfo (Optional), [12] TextColor (Optional), [13] OnOptionValueChangedHandler (Optional), [14] OnClickHandler (Optional)

FrameVisible

[6] DefaultValue, [7] Frame

FrameLocked

[6] DefaultValue, [7] Frame

FrameClampedToScreen

[6] DefaultValue, [7] Frame

FramePosition

[6] DefaultValue (As FramePositionInfo), [7] Frame, [8] ParentFrame (Optional), [9] ShowParentAnchorPoint (Optional), [10] AlignOnSingleRow (Optional), [11] MinOffsetX (Optional), [12] MaxOffsetX (Optional), [13] MinOffsetY (Optional), [14] MaxOffsetY (Optional), [15] OnOptionValueChangedHandler (Optional)

FrameSize

[6] DefaultValue, [7] Frame, [8] MinValue (Optional), [9] MaxValue (Optional)

FrameWidth

Same as FrameSize.

FrameHeight

Same as FrameSize.

FrameScale

[6] DefaultValue, [7] Frame, [8] MinValue (Optional), [9] MaxValue (Optional)

FrameStrata

[6] DefaultValue, [7] Frame

FrameLevel

[6] DefaultValue, [7] Frame, [8] MinValue (Optional), [9] MaxValue (Optional)

FrameBackgroundColor

[6] DefaultValue, [7] Frame

CustomControl

[6] DefaultValue, [7] GetCustomControl

StartRow

[6] IndexOfItemToUseAsRowHeight (Optional), [7] Height (Optional)

EndRow

N/A

SetPosition

N/A

MovePosition

N/A

SavePosition

[6] Key (String, Number, or nil)

RestorePosition

[6] Key (String, Number, or nil)

DisableAutoCheckBoxGrouping

N/A

EnableAutoCheckBoxGrouping

N/A

Examples:

Indexed format:

{"Threshold1", "Threshold 1", "Specifies the first threshold.", 0, "Slider", 50.0, 0.0, 100.0, 0.1, "%.1f"}

Parameter name format:

{

Name = "Threshold1",

Text = "Threshold 1",

TooltipText = "Specifies the first threshold.",

PositionInfo = 0,

Type = "Slider"

DefaultValue = 50.0

MinValue = 0.0

MaxValue = 100.0

ValueStep = 0.1

FormatString = "%.1f"

}

Hybrid format:

{"Threshold1", "Threshold 1", "Specifies the first threshold.", 0, "Slider", 50.0, 0.0, 100.0, 0.1, "%.1f", Width = 300}

Supported Formats for Special Parameter Types:

PositionInfo

value

Represents an indent count. Float values are allowed and a value of 1 corresponds to 20 pixels.

Examples: nil, 0, 1, 2, etc.

Note: If the indent count of a control immediately after a CheckBox is larger than the indent count of that CheckBox, then the control will be disabled when that CheckBox is unchecked. This behavior can be disabled if desired.

{offsetX}

Represents the offset in the x-direction (in pixels).

Example: {20}

{offsetX, offsetY}

Represents the offsets in the x-direction and y-direction (in pixels).

Example: {20, 16}

FramePositionInfo

{anchorPoint, x, y}

Example: {"CENTER", 0, -100}

{childAnchorPoint, parentAnchorPoint, x, y}

Example: {"CENTER", "CENTER", 0, -100}

Size

width

Examples: nil, 50, 100, 200, etc.

{width}

Example: {200}

{width, height}

Example: {200, 16}

Note: The width can be set to "Fill" for some control types in which case the control's width will fill the available space of the parent control.

TabInfo

text

Example: "Tab 1"

{text, customWidth}

Example: {"Tab 1", 100}

ColorInfo

{red, blue, green}

Example: {1.0, 0.5, 0.0}

{red, blue, green, alpha}

Example: {1.0, 0.5, 0.0, 0.5}

FontInfo

fontSize

Example: 16

fontFilePath or fontObjectName

Example of fontFilePath: "Fonts\\FRIZQT__.TTF"

Example of fontObjectName: "GameFontNormal"

{fontSize} -- e.g., {16}

Example: {16}

{fontFilePath or fontObjectName}

Example of fontFilePath: {"Fonts\\FRIZQT__.TTF"}

Example of fontObjectName: {"GameFontNormal"}

{fontFilePath or fontObjectName, fontSize} -- e.g., {"Fonts\\FRIZQT__.TTF" or "GameFontNormal", 16}

Example of fontFilePath: {"Fonts\\FRIZQT__.TTF", 16}

Example of fontObjectName: {"GameFontNormal", 16}

{fontSize, fontFlags}

Example: {16, "OUTLINE, THICKOUTLINE, MONOCHROME"}

{fontFilePath or fontObjectName, fontSize, fontFlags}

Example of fontFilePath: {"Fonts\\FRIZQT__.TTF", 16, "OUTLINE, THICKOUTLINE, MONOCHROME"}

Example of fontObjectName: {"GameFontNormal", 16, "OUTLINE, THICKOUTLINE, MONOCHROME"}

DropDownItemInfo

{value1, value2, ...}

Example: {1, 2, 3}

Example: {"One", "Two", "Three"}

{{value1}, {value2}, ...}

Example: {{1}, {2}, {3}}

Example: {{"One"}, {"Two"}, {"Three"}}

{{value1, text1}, {value2, text2}, ...}

Example: {{1, "Value 1"}, {2, "Value 2"}, {3, "Value 3"}}

Example: {{"One", "Value 1"}, {"Two", "Value 2"}, {"Three", "Value 3"}}

Note: The value of a DropDownItemInfo may be a number or a string, but empty strings or nil are not allowed.

RadioButtonInfo

Same as DropDownItemInfo format.

DelimiterInfo

Parameters

Delimiter

Specifies the delimiter.

Type: String

DelimiterPrefix

Indicates a string to insert before the delimiter when converting the items in a table to a string.

Type: String

DelimiterSuffix

Indicates a string to add after the delimiter when converting the items in a table to a string.

Type: String

TrimItems

Indicates whether to trim each item when converting a string to a table of items.

Type: Boolean

Example:

local info = {}
info.Delimiter = ","
info.DelimiterPrefix = ""
info.DelimiterSuffix = " "
info.TrimItems = true

Example:

local info = EasyOptions:CreateBarDelimiterInfo()

Example:

local info = EasyOptions:CreateCommaDelimiterInfo()

Example:

local info = EasyOptions:CreateLinesDelimiterInfo()