Using the ColorPickerFrame

Main Menu
WoW API Lua API FrameXML util Widget API Widget scripts XML schema Events CVars Macro commands Combat Log Escape sequences Hyperlinks API changes HOWTOs wowuidev

ColorPickerFrame is a FrameXML-provided frame that is used by the UI to allow the user to customize color and opacity properties of various objects. The frame can also be used by third-party addons.

Overview

There is only one instance of the ColorPickerFrame, and, as such, only color selection request can be processed at a time. When the player interacts with the color picker, the frame calls functions assigned to the following variables:

ColorPickerFrame.func ()

Called when color selection is changed.

ColorPickerFrame.opacityFunc ()

Called when opacity is changed.

ColorPickerFrame.cancelFunc (previousValues)

Called when the user cancels color modification. previousValues is the value assigned to ColorPickerFrame.previousValues.

The opacity slider's visibility is controlled by the ColorPickerFrame.hasOpacity boolean value.

Showing the color picker

The ColorPickerFrame is already defined by Blizzard. You can display it by simply calling: ColorPickerFrame:Show()

However, displaying it is not enough if you want it to have any functionality. So, you also need to define the following three functions:

• ColorPickerFrame.func()
• ColorPickerFrame.opacityFunc()
• ColorPickerFrame.cancelFunc()

When you want to prompt the user to select a color, you need to assign your own callback functions to the ColorPickerFrame variables, set the currently selected color to your previous value, and show the ColorPickerFrame.

To set the initial color and opacity values, you need to:

ColorPickerFrame:SetColorRGB(r,g,b)

Sets the initial color.

ColorPickerFrame.opacity

Place initial opacity (if relevant) into this variable; ColorPickerFrame's OnShow script will update the relevant slider.

The following example function performs all of the required tasks: sets the initial color, enables/disables the opacity control and registers your callback function before showing the color picker.

function ShowColorPicker(r, g, b, a, changedCallback)
 ColorPickerFrame:SetColorRGB(r,g,b);
 ColorPickerFrame.hasOpacity, ColorPickerFrame.opacity = (a ~= nil), a;
 ColorPickerFrame.previousValues = {r,g,b,a};
 ColorPickerFrame.func, ColorPickerFrame.opacityFunc, ColorPickerFrame.cancelFunc = 
  changedCallback, changedCallback, changedCallback;
 ColorPickerFrame:Hide(); -- Need to run the OnShow handler.
 ColorPickerFrame:Show();
end

Responding to user interactions

The functions assigned to the ColorPickerFrame table will be called when the user alters the color; your registered callback function should handle the changed color by updating your internal color storage and the display. The function is called without arguments, except when the user cancels the color selection (in which case, the previousValue field on ColorPickerFrame is passed as the sole argument).

You can fetch the user-selected color values using two functions:

r, g, b = ColorPickerFrame:GetColorRGB()

returns the color component, each value in the [0, 1] range.

a = OpacitySliderFrame:GetValue()

returns the alpha component in the [0, 1] range.

An example callback handler function is shown below.

local r,g,b,a = 1, 0, 0, 1;

local function myColorCallback(restore)
 local newR, newG, newB, newA;
 if restore then
  -- The user bailed, we extract the old color from the table created by ShowColorPicker.
  newR, newG, newB, newA = unpack(restore);
 else
  -- Something changed
  newA, newR, newG, newB = OpacitySliderFrame:GetValue(), ColorPickerFrame:GetColorRGB();
 end
 
 -- Update our internal storage.
 r, g, b, a = newR, newG, newB, newA;
 -- And update any UI elements that use this color...
end

This can then be used with the previously described ShowColorPicker function:

ShowColorPicker(r, g, b, a, myColorCallback);