ConfigMode

This page documents a user-defined API that is provided by third-party addons.

Those of you who have played Warhammer Online or used addons like nShakeDown know how useful it is to be able to click a single button and immediately see the screen real-estate occupied by all UI components and addons.

Unfortunately, WoW's UI does not provide this, and the nShakeDown approach (knowing about every addon out there) tends to fail due the burden on the single addon author keeping everything up to date.

The intent of the "ConfigMode" spec is to make a central registry where all addons can say "call this function to have me display my movable frames". And then you can have a single light addon that just calls all of these functions.

It is not meant as a way to open configuration dialog boxes. The purpose is to quickly show and unlock all movable/sizeable frames so the user can arrange them.

The idea evolved in this WoWAce forum thread.

Specification

At its core, an addon supports ConfigMode by simply creating an entry in the global CONFIGMODE_CALLBACKS table:

 -- Create the global table if it does not exist yet
 CONFIGMODE_CALLBACKS = CONFIGMODE_CALLBACKS or {}
 -- Declare our handler
 CONFIGMODE_CALLBACKS["MyAddon"] = function(...) ...code... end

The "MyAddon" name will likely be visible in controller addons implementing this spec.

Note that you are restricted to a single entry per addon. You can have multiple entries if it makes sense for you (e.g. multiple modules in an addon). We strongly recommend that you follow a pattern of "addonName - moduleName" when you do so, including the spaces. This may then be used by controlling addons to group your modules.

Simple handler

This handler, let's say myHandlerFunc, can be called in two ways:

* myHandlerFunc("ON"): the addon should enter configuration mode,
* myHandlerFunc("OFF"): the addon should leave configuration mode.

Here is a simple handler sample for an addon named MyAddon that provides two methods to lock and unlocks its frames:

 -- Create the global table if it does not exist yet
 CONFIGMODE_CALLBACKS = CONFIGMODE_CALLBACKS or {}
 -- Declare our handler
 CONFIGMODE_CALLBACKS["MyAddon"] = function(action)
   if action == "ON" then
     MyAddon:UnlockFrames()
   elseif action == "OFF" then
     MyAddon:LockFrames()
   end
 end

Multimode handler

Some addons can have several different layouts and thus different test modes. This is the case of several unit frame addons.

Such addons can publish a more elaborated handler that supports the following calls:

* handlerFunc("ON", mode): enter configuration mode mode
* handlerFunc("OFF"): leave configuration mode
* mode1, mode2, mode3, ... = handlerFunc("GETMODES"): list available modes.

Note that you HAVE to be prepared to just receive ("ON") without a mode from a "simple" controller addon. In this case, you can e.g. pick the last mode your addon was in, or whatever makes sense to your addon (UF addon in a raid? show raid mode. In a party? show party mode.)

Here is the sample of a unit frame multimode handler:

 -- Create the global table if it does not exist yet
 CONFIGMODE_CALLBACKS = CONFIGMODE_CALLBACKS or {}
 -- Declare our handler
 CONFIGMODE_CALLBACKS["MyUnitFrameAddon"] = function(action, mode)
   if action == "ON" then
     MyUnitFrameAddon:EnableTestMode(mode)  -- note: mode can be nil!
   elseif action == "OFF" then
     MyUnitFrameAddon:DisableTestMode()
   elseif action == "GETMODES" then
     return "party", "raid"
   end
 end

LoD addons

If your addon is load-on-demand, you may want to give controlling addons a hint that your addon can/should be loaded. If so, add the following line to your .toc file:

 X-ConfigMode: true

If you want to list the modes that your addon supports (just so that the list will be available in the controlling addon without actually loading your addon), you can do so also:

 X-ConfigMode-Modes: party, raid

Note that the latter is VERY optional; a LoD multimode addon does not need to list its modes in the .toc file - controller addons are still required to fire a "GETMODES" call after actually loading your addon.

Implementation notes for controller addons

• For a very simple controller addon, you do NOT need to implement "GETMODES" functionality, nor LoD support. But do tell your users if you do not.

• Do not assume that you can cache the CONFIGMODE_CALLBACKS contents for extended times, nor the returns from "GETMODES" calls. Addons are allowed to add and remove as many entries as they like, dynamically. Even the mode list can be dynamic; perhaps it is a list of user-configurable profiles!

• When you load a LoD addons that has an "X-ConfigMode-Modes" list, you STILL have to fire a "GETMODES" call after loading the addon. In part because the toc field may be out of date, but mainly because the list may be dynamically generated (or added to). (Though in the latter case the addon probably should not publish a fixed list in the .toc at all)

• Treat all "X-ConfigMode" toc values other than "false" (with case variations) as "true". I.e. "blahblah; name=val" is still "true". This allows for future extensions in the field.

Addons

Controller addons

• OneButtonConfig by Adirelle