Wikia

WoWWiki

USERAPI ConfigMode

Talk0
101,310pages on
this wiki
This page documents a user-defined API 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.

Specification Edit

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 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.
Icon-warning-22x22An 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
 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

Modules Edit

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.
Icon-warning-22x22Note 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 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
Icon-information-22x22Controller 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.

Addons Edit

Around Wikia's network

Random Wiki