Home

How to make your addon support ClassColors

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:

Old:

local color = RAID_CLASS_COLORS["SHAMAN"]

New:

local color = (CUSTOM_CLASS_COLORS or RAID_CLASS_COLORS)["SHAMAN"]

Callback usage

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

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:

RegisterCallback

CUSTOM_CLASS_COLORS:RegisterCallback(method[, handler])

Registers a function to be called when values in CUSTOM_CLASS_COLORS are changed.

Arguments

• method — function or string
• handler — nil or table

Details

• If method is a function, that function will be called when class colors are changed, with no arguments.
• If method is a string, handler is a table, and handler[method] is a function, that function will be called when class colors are changed, with handler as 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.

UnregisterCallback

CUSTOM_CLASS_COLORS:UnegisterCallback(method[, handler])

Removes a function from the callback registry, so it will no longer be called when class colors are changed.

Arguments

• method — function or string
• handler — nil or table

Details

• 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

NotifyChanges

CUSTOM_CLASS_COLORS:NotifyChanges()

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.

GetClassToken

CUSTOM_CLASS_COLORS:GetClassToken(localizedClassName)

Returns the locale-independent token (eg. "WARLOCK") for the specified localized class name (eg. "Warlock" or "Hexenmeister").

Arguments

• localizedClassName — string: a localized class name

Returns

• classToken — string: a locale-independent class token

Caveats

You should not set the !ClassColors addon as a dependency for your addon, or check for the !ClassColors addon by name — eg. with IsAddOnLoaded or GetAddOnInfo — as a means of implementing support for custom class colors. There are two main reason for this:

1. 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.
2. CUSTOM_CLASS_COLORS is 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 CUSTOM_CLASS_COLORS table.

Use the methods described above instead to ensure consistent support for users’ custom class colors.

Alternate implementations

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:

1. Create a global CUSTOM_CLASS_COLORS table with the same keys and structure as RAID_CLASS_COLORS
2. Define :RegisterCallback and :UnregisterCallback metamethods on the CUSTOM_CLASS_COLORS table
3. Define :NotifyChanges and :GetClassToken metamethods on the CUSTOM_CLASS_COLORS table

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_COLORS and, 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 RAID_CLASS_COLORS.