Using the Interface Options Addons panel

Blizzard's InterfaceOptions frame can also display configuration options for third-party addons. This page describes how an addon can take advantage of the built-in Interface options UI.

The functionality described on this page is documented primarily in comments in FrameXML/InterfaceOptionsFrame.lua; search for "HOWTO: Add new categories of options."

Summary
The InterfaceOptions framework requires an addon to supply its own configuration frame (panel). The supplied panel will be repositioned by FrameXML and displayed when the addon's configuration category is selected.

When the user presses the Okay, Cancel or Defaults buttons on the Interface Options frame, the panels will be notified by calling specific functions in the supplied frame table.

API Functions
The following functions are provided in FrameXML to interact with the InterfaceOptions framework:
 * InterfaceOptions_AddCategory(panel[, _, position]) : Adds a configuration panel (with the fields described in below set) to the category list. The optional position argument (number) allows addons to insert top-level panels at arbitrary positions in the category list.
 * InterfaceOptionsFrame_OpenToCategory(panelName or panel) : Opens the Interface Options frame and navigates to the specified panel.
 * InterfaceOptionsFrame_Show : Toggles visibility of the Interface Options frame.

Panel fields
The InterfaceOptions code uses certain fields on the configuration panel to interact with the panel:
 * name : Required, String - name displayed in the Interface Options category list (your addon name, or a panel-specific name)
 * parent : Optimal, String - the panel.name value of the parent configuration panel, used to display a hierarchical category tree. If the parent panel is not specified or does not exist, the panel is displayed as a top-level panel.
 * refresh : Optional, Function - called when the frame is initially displayed, and after requesting the default values to be restored.
 * okay : Optional, Function - called when the player presses the Okay button, indicating that settings should be saved.
 * cancel : Optional, Function - called when the player presses the Cancel button, indicating that changes made should be discarded.
 * default : Optional, Function - called when the player presses the Defaults button, indicating that default settings for the addon should be restored.

Thus, the minimum required code to create a custom Interface Options panel is: local panel = CreateFrame("FRAME") panel.name = "My Awesome Addon" InterfaceOptions_AddCategory(panel)

Example XML with Okay and Cancel buttons
This example is taken from an addon called SC_ChaChing, available from http://wowui.incgamers.com/?p=mod&m=4934.

The XML frame
All we need to do first is to create the Frame. As we are using the Interface Options - Addon panels, we do not need to use any sizing or movement options.

The OnLoad script calls the Panel_OnLoad function.


 * XML Frame

 . . .          SC_ChaChingPanel_OnLoad(self);   

The Lua function
All we need to do with this function, is to set the name of the panel. Along with the Functions needed for the Okay and Cancel Buttons. Then to call the function that adds the Category to the Interface Options - Addon Category list.


 * Lua Function

function SC_ChaChingPanel_OnLoad(panel) . . .        -- Set the name for the Category for the Panel --        panel.name = "SC_ChaChing " .. GetAddOnMetadata("SC_ChaChing", "Version"); -- When the player clicks okay, run this function. --        panel.okay = function (self) SC_ChaChingPanel_Close; end; -- When the player clicks cancel, run this function. --        panel.cancel = function (self)  SC_ChaChingPanel_CancelOrLoad;  end; -- Add the panel to the Interface Options --        InterfaceOptions_AddCategory(panel); end

Example entirely in Lua
MyAddon = {}; MyAddon.panel = CreateFrame( "Frame", "MyAddonPanel", UIParent ); -- Register in the Interface Addon Options GUI -- Set the name for the Category for the Options Panel MyAddon.panel.name = "MyAddon"; -- Add the panel to the Interface Options InterfaceOptions_AddCategory(MyAddon.panel); -- Make a child panel MyAddon.childpanel = CreateFrame( "Frame", "MyAddonChild", MyAddon.panel); MyAddon.childpanel.name = "MyChild"; -- Specify childness of this panel (this puts it under the little red [+], instead of giving it a normal AddOn category) MyAddon.childpanel.parent = MyAddon.panel.name; -- Add the child to the Interface Options InterfaceOptions_AddCategory(MyAddon.childpanel);

Removing an existing options panel
FrameXML does not provide an API to remove an existing addon options panel from the list. Should you want to do so, you could use the following function: local function RemoveInterfaceOptions(frameName, bParent) -- Ensure that the variables passed are valid assert(type(frameName) == "string" and (type(bParent) == "boolean" or bParent == nil), 'Syntax: RemoveInterfaceOptions(frameName[, bParent])'); -- Setup local variables local removeList = {}; local nextFreeArraySpace = 1; -- If the name given is NOT a parent frame if not(bParent) then -- Add this frame to the list to be deleted removeList[frameName] = true; end -- Loop though Bliz's Interface Options Frames looking for the frames to remove for i=1, #INTERFACEOPTIONS_ADDONCATEGORIES do           -- Store this Interface frame local v = INTERFACEOPTIONS_ADDONCATEGORIES[i]; -- Check if this is the frame we want to remove or if bParent -- the child of the want we want to remove -- or just one we want to keep if (removeList[v.name] or (bParent and v.parent == frameName)) or (bParent and removeList[v.parent]) then -- Wipe this frame from the array by making it 'true' removeList[v.name] = true; else -- We want to keep this frame so move it up the array -- to remove any holes caused by the deleted frames INTERFACEOPTIONS_ADDONCATEGORIES[nextFreeArraySpace] = INTERFACEOPTIONS_ADDONCATEGORIES[i]; nextFreeArraySpace = nextFreeArraySpace + 1; end; end; -- Loop though all of the interface frames after the last good one removing them for i=nextFreeArraySpace, #INTERFACEOPTIONS_ADDONCATEGORIES do           INTERFACEOPTIONS_ADDONCATEGORIES[i] = nil; end; -- Tell Bliz's interface frame to update now to reflect the removed frames InterfaceAddOnsList_Update; end The function takes a string argument frameName, which specifies which panel (along with all of its children) should be removed from the category list. If the optional boolean argument bParent is true, only panels with the specified frameName as there parent (and their children) will be removed.