WoW:USERAPI ConfigMode

From AddOn Studio
Jump to navigation Jump to search
This page documents a <i>user-defined API</i> that is provided by third-party addons.

AddOn defined functions < ConfigMode

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.


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
 -- 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 not 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[edit]

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.
Red exclamation mark iconAn handler MUST NOT act when the first parameter is unknown. This allows for future extension of this specification.

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
 -- Declare our handler
 CONFIGMODE_CALLBACKS["MyAddon"] = function(action)
   if action == "ON" then
   elseif action == "OFF" then


Please follow the below syntax for an addon with modules; it will allow controller addons to group them if they so desire.

 CONFIGMODE_CALLBACKS["MyAddon - ModOne"] = ...
 CONFIGMODE_CALLBACKS["MyAddon - ModTwo"] = ...
 CONFIGMODE_CALLBACKS["MyAddon - ModThree"] = ...

Multimode handler[edit]

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.
Red exclamation mark iconNote 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
 -- 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
   elseif action == "GETMODES" then
     return "party", "raid"

LoD addons[edit]

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
"I" iconController addons will be listing the real name of your addon while the addon is not loaded. So you probably want to register your CONFIGMODE_CALLBACKS entry using the exact name of the addon!

Implementation notes for controller addons[edit]

  • 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!
  • 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.
  • When you LoD an addon, do not expect the addon's name to appear in CONFIGMODE_CALLBACKS. Indeed, the addon could be registering multiple callbacks!

You are of course free to not call all handlers listed in the table. You can e.g. allow making sets of addons that are config-enabled and disabled. Or know about circumstances where it makes sense to not show some addons. That is beyond the scope of this specification.

Your addon can certainly also handle unlocking and showing blizzard frames, and/or frames of addons not implementing the ConfigMode spec. That is also beyond the scope of this specification.