Editing WoW:Using the ColorPickerFrame

{{wow/uihowto}}
'''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 <code>ColorPickerFrame.hasOpacity</code> 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&#58;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&#58;GetColorRGB() : returns the color component, each value in the [0, 1] range.
; a = OpacitySliderFrame&#58;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);
==Limitations==
[[File:ColorPickerTools.jpg|320px|right|thumb|ColorTools.]]
The color picker has three main limitations:
*You have no way to know exactly which color is chosen (no color code)
*You can't copy color values from one instance of the color picker to another one
*You cannot move the color picker in case it obscures another underlying frame

All these problems are solved with the addon [http://wow.curse.com/downloads/wow-addons/details/colortools.aspx ColorTools ].

==Note==
As [[User:Exawatt|Exawatt]] stated, ColorPickerFrame:SetColorRGB(R, G, B) will execute ColorPickerFrame.func
This is very important when you're reusing ColorPickerFrame with another callback function. In that case make sure you set the new callback before you call SetColorRGB(R, G, B)