WoW:Using the ColorPickerFrame: Difference between revisions

From AddOn Studio
Jump to navigation Jump to search
m (Move page script moved page Using the ColorPickerFrame to Using the ColorPickerFrame without leaving a redirect)
 
(7 intermediate revisions by 7 users not shown)
Line 1: Line 1:
== What is it? ==
{{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.


The ColorPickerFrame (See: [[XML_User_Interface#ColorSelect]]) is the default WoW frame to easily select color and opacity using a GUI.
== Overview ==
The ColorPickerFrame comes with customizable functions, which are next.
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.


== ColorPickerFrame functions ==
The opacity slider's visibility is controlled by the <code>ColorPickerFrame.hasOpacity</code> boolean value.


ColorPickerFrame.func;
== Showing the color picker ==
--Called on changing the color wheel
The ColorPickerFrame is already defined by Blizzard. You can display it by simply calling: ColorPickerFrame:Show()


ColorPickerFrame.opacityFunc;
However, displaying it is not enough if you want it to have any functionality. So, you also need to define the following three functions:
--Called on changing the opacity slider
* ColorPickerFrame.func()
* ColorPickerFrame.opacityFunc()
* ColorPickerFrame.cancelFunc()


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.
--Called on hitting CANCEL button OR pressing ESCAPE.
--cancelFunc is called with the argument ColorPickerFrame.previousValues so set that when
--you show the frame


These functions can be specified by you to do something.  The best example is setting some variables to the selected color as it changes. Check the following code:
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.
  ColorPickerFrame.func = MY_COLOR_FUNCTION
  function ShowColorPicker(r, g, b, a, changedCallback)
ColorPickerFrame.cancelFunc = MY_CANCEL_FUNCTION
  ColorPickerFrame:SetColorRGB(r,g,b);
 
  ColorPickerFrame.hasOpacity, ColorPickerFrame.opacity = (a ~= nil), a;
function MY_COLOR_FUNCTION()
  ColorPickerFrame.previousValues = {r,g,b,a};
   local R,G,B = ColorPickerFrame:GetColorRGB();
  ColorPickerFrame.func, ColorPickerFrame.opacityFunc, ColorPickerFrame.cancelFunc =  
end
   changedCallback, changedCallback, changedCallback;
function MY_CANCEL_FUNCTION(prevvals)
  ColorPickerFrame:Hide(); -- Need to run the OnShow handler.
  local R,G,B = unpack(prevvals)
  ColorPickerFrame:Show();
  end
  end


All the functions can be set in that manner.
== 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).


== ColorPickerFrame Misc ==
You can fetch the user-selected color values using two functions:
ColorPickerFrame.hasOpacity = boolean;
; r, g, b = ColorPickerFrame&#58;GetColorRGB() : returns the color component, each value in the [0, 1] range.
--Sets whether or not to show the opacity slider.
; a = OpacitySliderFrame&#58;GetValue() : returns the alpha component in the [0, 1] range.
--You MUST set this explicitly every time as the default UI will not reset it from a value
--set previously.


  ColorPickerFrame.opacity = Alpha;
An example callback handler function is shown below.
  --Sets the initial value of the opacity slider.
  local r,g,b,a = 1, 0, 0, 1;
 
   
ColorPickerFrame.previousValues = {R, G, B}
local function myColorCallback(restore)
--Sets the values passed to the cancelFunc when Esc is pressed or the close button is pressed.
  local newR, newG, newB, newA;
 
  if restore then
ColorSwatch:SetTexture(R, G, B);
  -- The user bailed, we extract the old color from the table created by ShowColorPicker.
--Sets the color square to show specified color
  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


  ColorPickerFrame:Show();
This can then be used with the previously described ShowColorPicker function:
--Shows the frame
  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


ColorPickerFrame:Hide();
All these problems are solved with the addon [http://wow.curse.com/downloads/wow-addons/details/colortools.aspx ColorTools ].
--Hides the frame


ColorPickerFrame:SetColorRGB(R, G, B);
==Note==
--Set the color in the color frame
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)
local R,G,B = ColorPickerFrame:GetColorRGB();
--Gets the color from the color frame
 
local A = OpacitySliderFrame:GetValue();
--Gets the opacity from the opacity slider on the color frame.
 
== Examples of use ==
 
Open frame with specified values:
 
ColorPickerFrame:Show();
ColorPickerFrame:SetColorRGB(R, G, B);
 
Set R, G, and B to the ColorWheel's colors on changing the selected color
function MY_COLOR_FUNCTION()
  local R,G,B = ColorPickerFrame:GetColorRGB();
end
ColorPickerFrame.func = MY_COLOR_FUNCTION
[[Category:HOWTOs|Use the ColorPickerFrame]]

Latest revision as of 04:49, 15 August 2023

HOWTOs

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[edit]

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[edit]

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[edit]

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);

Limitations[edit]

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

Note[edit]

As 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)