Editing WoW:USERAPI ConfigMode

{{userapi}}
Those of you who have played [http://www.warhammeronline.com/ Warhammer Online] or used addons like [http://wow.curse.com/downloads/wow-addons/details/project-5570.aspx 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 [http://forums.wowace.com/showthread.php?t=14765 this WoWAce forum thread].

== Specification ==
<div style="margin-left: 3%;">

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 ===
<div style="margin-left: 3%;">

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-exclamation}}An 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

</div>
=== Modules ===
<div style="margin-left: 3%;">

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"] = ...

</div>

=== Multimode handler ===
<div style="margin-left: 3%;">

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-exclamation}}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

</div>

=== LoD addons ===
<div style="margin-left: 3%;">

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}}Controller 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!


</div>
</div>

== Implementation notes for controller addons ==
<div style="margin-left: 3%;">

* 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.

</div>

== Addons ==
<div style="margin-left: 3%;">

=== Controller addons ===
* [http://wow.curse.com/downloads/wow-addons/details/onebuttonconfig.aspx OneButtonConfig] by Adirelle

=== Compliant addons ===

* [http://wow.curse.com/downloads/wow-addons/details/auracle.aspx Auracle (de)buff Monitor]
* [http://wow.curse.com/downloads/wow-addons/details/auto-bar.aspx AutoBar]
* [http://www.wowinterface.com/downloads/info11177-Capping.html Capping]
* [http://wow.curse.com/downloads/wow-addons/details/castbars.aspx Castbars]
* [http://wow.curse.com/downloads/wow-addons/details/cellular.aspx Cellular]
* [http://wow.curse.com/downloads/wow-addons/details/configmodeblizzard.aspx ConfigModeBlizzard]
* [http://wow.curse.com/downloads/wow-addons/details/configmodedemos.aspx ConfigModeDemos]
* [http://wow.curse.com/downloads/wow-addons/details/dominos.aspx Dominos]
* [http://www.wowace.com/addons/grid2/ Grid2]
* [http://wow.curse.com/downloads/wow-addons/details/omen-threat-meter.aspx Omen]
* [http://wow.curse.com/downloads/wow-addons/details/parrot.aspx Parrot]
* [http://wow.curse.com/downloads/wow-addons/details/sexycooldown.aspx SexyCooldown]
* [http://www.wowinterface.com/downloads/info13494-ShadowedUnitFrames.html Shadowed Unit Frames]
* [http://wow.curse.com/downloads/wow-addons/details/stuf-unit-frames.aspx Stuf Unit Frames]
* [http://wow.curse.com/downloads/wow-addons/details/visualheal.aspx VisualHeal]
* [http://wow.curse.com/downloads/wow-addons/details/yatba.aspx Yatba]

</div>