Basically, any time you’d look up a value in the
RAID_CLASS_COLORS table, check for the existence of a global
CUSTOM_CLASS_COLORS table and — if it exists — get the value from it instead:
local color = RAID_CLASS_COLORS["SHAMAN"]
local color = (CUSTOM_CLASS_COLORS or RAID_CLASS_COLORS)["SHAMAN"]
If your addon creates a local upvalue (variable) for
RAID_CLASS_COLORS, or maintains its own table of class colors, you should register for the
PLAYER_LOGIN event and, when it fires, redirect your upvalue to
CUSTOM_CLASS_COLORS or update your table with the values from
It is strongly recommended that you also register for a callback to be notified when class colors are changed by the user, and update your upvalue or table when the callback is fired:
Registers a function to be called when values in
CUSTOM_CLASS_COLORS are changed.
method— function or string
handler— nil or table
methodis a function, that function will be called when class colors are changed, with no arguments.
methodis a string,
handleris a table, and
handler[method]is a function, that function will be called when class colors are changed, with
handleras its first and only argument.
- If the provided arguments do not identify a valid function, an error will be thrown.
- If the function is already registered, nothing will happen.
Removes a function from the callback registry, so it will no longer be called when class colors are changed.
method— function or string
handler— nil or table
- If the provided arguments do not identify a valid function, nothing will happen.
- If the function is not registered, nothing will happen.
Other API Functions
Notifies other addons that class colors have changed. !ClassColors does this automatically when you use its options UI, so you would only need to use this function if your addon provides its own UI for changing class colors, but does not provide its own full implementation of CUSTOM_CLASS_COLORS, and you want colors set through your UI to propigate to other addons and be saved in CUSTOM_CLASS_COLORS between sessions.
Returns the locale-independent token (eg. "WARLOCK") for the specified localized class name (eg. "Warlock" or "Hexenmeisterin").
localizedClassName— string: a localized class name
classToken— string: a locale-independent class token
You should not set the !ClassColors addon as a dependency for your addon, or check for the !ClassColors addon by name — eg. with
GetAddOnInfo — as a means of implementing support for custom class colors. There are two main reason for this:
- The loading order of addons is not defined, and not all users are on systems which load files in alphabetical order, so you cannot guarantee that !ClassColors will be loaded before your addon, unless you clutter up your TOC by setting !ClassColors as an optional dependency for your addon.
CUSTOM_CLASS_COLORSis meant to be a community standard, not a single addon. Currently, there are no known alternate implementations, but you should not assume that the !ClassColors addon is the only way for your users to get a
Use the methods described above instead to ensure consistent support for users’ custom class colors.
CUSTOM_CLASS_COLORS is a proposed commnity standard defining a globally-accessible table of alternate class colors that can be freely modified without tainting parts of the Blizzard UI. Since it creates a new table, rather than modifying Blizzard’s
RAID_CLASS_COLORS, addons must explictily include support for it.
The !ClassColors addon is only one possible implementation of this standard (though, it is currently the only one I know about). Any implementation must:
- Create a global
CUSTOM_CLASS_COLORStable with the same keys and structure as
:UnregisterCallbackmetamethods on the
:GetClassTokenmetamethods on the
The API methods must be defined using a metatable so that addons can freely iterate over the table using pairs() and get only the same keys and data structures they’d get from
RAID_CLASS_COLORS without adding any special code to handle function or other non-standard values.
The following features are recommended, but can be left out without actually breaking anything:
- Provide a UI for changing color values
- Save and restore custom color values between sessions
- Maintain a list of functions requesting callbacks, and call them when any color values are changed
- Check if another addon has already defined
CUSTOM_CLASS_COLORSand, if so, avoid overwriting it
- Apply custom color values to the Blizzard UI
Implementations may also provide any number of other features, as long as they do not pollute the raw key/value structure of the
CUSTOM_CLASS_COLORS table. The intent is that
CUSTOM_CLASS_COLORS is a drop-in replacement for
If you’ve released an alternate implementation of
CUSTOM_CLASS_COLORS, please send me a PM so I can add a link to it here!
If you have any questions or comments about this documentation, send me a PM!
- Date created
- Mar 14, 2010
- Last updated
- Dec 22, 2013