API: colorpicker YAHOO.widget.ColorPicker (YUI Library)

# Yahoo! UI Library

### colorpicker 2.8.0r4

Yahoo! UI Library > colorpicker > YAHOO.widget.ColorPicker
Search:
Filters Show Private Show Protected Show Deprecated

## Class YAHOO.widget.ColorPicker - extends YAHOO.util.Element

A widget to select colors

### Constructor

YAHOO.widget.ColorPicker `( el(optional) , attr )`

Parameters:
  `el(optional) <HTMLElement | String | Object>` The html element that represents the colorpicker, or the attribute object to use. An element will be created if none provided.
  `attr <Object>` (optional) A key map of the colorpicker's initial attributes. Ignored if first arg is attributes object.

### Properties

#### DEFAULT - `final object`

Constants for the control's default default values

#### hueSlider - `YAHOO.widget.Slider`

The hue slider

#### ID - `final object`

The element ids used by this control

#### ID.B - `final String`

The id for the "blue" form field
Default Value: yui-picker-b

#### ID.B_HEX - `final String`

The id for the "blue" hex pair output
Default Value: yui-picker-bhex

#### ID.CONTROLS - `final object`

The id for the control details
Default Value: yui-picker-controls

#### ID.CONTROLS_LABEL - `final object`

The id for the controls section header
Default Value: yui-picker-controls-label

#### ID.G - `final String`

The id for the "green" form field
Default Value: yui-picker-g

#### ID.G_HEX - `final String`

The id for the "green" hex pair output
Default Value: yui-picker-ghex

#### ID.H - `final String`

The id for the "hue" form field
Default Value: yui-picker-h

#### ID.HEX - `final String`

The id for the hex value form field
Default Value: yui-picker-hex

#### ID.HEX_CONTROLS - `final object`

The id for the hsv controls
Default Value: yui-picker-hex-controls

#### ID.HEX_SUMMARY - `final object`

The id for the hex summary
Default Value: yui-picker-hex-summary

#### ID.HSV_CONTROLS - `final object`

The id for the hsv controls
Default Value: yui-picker-hsv-controls

#### ID.HUE_BG - `final String`

The id for the hue slider
Default Value: yui-picker-hue-bg

#### ID.HUE_THUMB - `final String`

The id for the hue thumb
Default Value: yui-picker-hue-thumb

#### ID.PICKER_BG - `final String`

The id for the picker region slider
Default Value: yui-picker-bg

#### ID.PICKER_THUMB - `final String`

The id for the picker region thumb
Default Value: yui-picker-thumb

#### ID.R - `final String`

The id for the "red" form field
Default Value: yui-picker-r

#### ID.R_HEX - `final String`

The id for the "red" hex pair output
Default Value: yui-picker-rhex

#### ID.RGB_CONTROLS - `final object`

The id for the rgb controls
Default Value: yui-picker-rgb-controls

#### ID.S - `final String`

The id for the "saturation" form field
Default Value: yui-picker-s

#### ID.SWATCH - `final String`

The id for the color swatch
Default Value: yui-picker-swatch

#### ID.V - `final String`

The id for the "value" form field
Default Value: yui-picker-v

#### ID.WEBSAFE_SWATCH - `final String`

The id for the websafe color swatch
Default Value: yui-picker-websafe-swatch

#### IMAGE - `final object`

Constants for the default image locations for img tags that are generated by the control. They can be modified by passing the complete list to the contructor for the "images" attribute

#### OPT - `final object`

Constants for the control's configuration attributes

#### pickerSlider - `YAHOO.widget.Slider`

The picker region

#### skipAnim - `Boolean`

Flag to allow individual UI updates to forego animation if available. True during construction for initial thumb placement. Set to false after that.
Default Value: true

#### TXT - `final object`

Constants for any script-generated messages. The values here are the default messages. They can be updated by providing the complete list to the constructor for the "txt" attribute.

#### Properties inherited from YAHOO.util.Element:

`DOM_EVENTS`

#### Properties inherited from YAHOO.util.AttributeProvider:

`_configs`

### Methods

#### _bindUI

`protected void _bindUI ( )`
Adds event listeners to Sliders and UI elements. Wires everything up.

Returns: `void`

#### _createHostElement

`protected void _createHostElement ( )`
Creates the host element if it doesn't exist

Returns: `void`

#### _getCommand

`protected int _getCommand ( e )`
Key map to well-known commands for txt field input

Parameters:
  `e <Event>` the keypress or keydown event

Returns: `int`
  a command code
  - 0 = not a number, letter in range, or special key
  - 1 = number
  - 2 = a-fA-F
  - 3 = increment (up arrow)
  - 4 = decrement (down arrow)
  - 5 = special key (tab, delete, return, escape, left, right)
  - 6 = return

#### _getH

`protected int _getH ( )`
Translates the slider value into hue, int[0,359]

Returns: `int`
  the hue from 0 to 359

#### _getS

`protected int _getS ( )`
Translates the slider value into saturation, int[0,1], left to right

Returns: `int`
  the saturation from 0 to 1

#### _getV

`protected int _getV ( )`
Translates the slider value into value/brightness, int[0,1], top to bottom

Returns: `int`
  the value from 0 to 1

#### _getValuesFromSliders

`protected void _getValuesFromSliders ( )`
Reads the sliders and converts the values to RGB, updating the internal state for all the individual form fields

Returns: `void`

#### _hexFieldKeypress

`protected void _hexFieldKeypress ( e , el , prop )`
Handle keydown on the hex field

Parameters:
  `e <Event>` the keypress event
  `el <HTMLElement>` the field
  `prop <string>` the key to the linked property

Returns: `void`

#### _hexOnly

`protected boolean _hexOnly ( e , numbersOnly )`
Allows numbers and special chars, and by default allows a-f. Used for the hex field keypress handler.

Parameters:
  `e <Event>` the event
  `numbersOnly <object>` omits a-f if set to true

Returns: `boolean`
  false if we are canceling the event

#### _hideShowEl

`protected void _hideShowEl ( id , on )`
Returns the cached element reference. If the id is not a string, it is assumed that it is an element and this is returned.

Parameters:
  `id <string|HTMLElement>` the element key, id, or ref
  `on <boolean>` hide or show. If true, show

Returns: `void`

#### _initElements

`protected void _initElements ( )`
Creates any missing DOM structure.

Returns: `void`

#### _initSliders

`protected void _initSliders ( )`
Creates the Hue and Value/Saturation Sliders.

Returns: `void`

#### _numbersOnly

`protected boolean _numbersOnly ( e )`
Allows numbers and special chars only. Used for the rgb and hsv fields keypress handler.

Parameters:
  `e <Event>` the event

Returns: `boolean`
  false if we are canceling the event

#### _onHueSliderChange

`protected void _onHueSliderChange ( newOffset )`
Event handler for the hue slider.

Parameters:
  `newOffset <int>` pixels from the start position

Returns: `void`

#### _onPickerSliderChange

`protected void _onPickerSliderChange ( newOffset )`
Event handler for the picker slider, which controls the saturation and value/brightness.

Parameters:
  `newOffset <{x: int, y: int}>` x/y pixels from the start position

Returns: `void`

#### _rgbFieldKeypress

`protected void _rgbFieldKeypress ( e , el , prop )`
Handle keypress on one of the rgb or hsv fields.

Parameters:
  `e <Event>` the keypress event
  `el <HTMLElement>` the field
  `prop <string>` the key to the linked property

Returns: `void`

#### _updateFormFields

`protected void _updateFormFields ( )`
Updates the form field controls with the state data contained in the control.

Returns: `void`

#### _updateHex

`protected void _updateHex ( )`
Parses the hex string to normalize shorthand values, converts the hex value to rgb and updates the rgb attribute (which updates the state for all of the other values) method _updateHex

Returns: `void`

#### _updateHueSlider

`protected void _updateHueSlider ( )`
Moves the hue slider into the position dictated by the current state of the control

Returns: `void`

#### _updatePickerSlider

`protected void _updatePickerSlider ( )`
Moves the picker slider into the position dictated by the current state of the control

Returns: `void`

#### _updateRGB

`protected void _updateRGB ( )`
Updates the rgb attribute with the current state of the r,g,b fields. This is invoked from change listeners on these attributes to facilitate updating these values from the individual form fields

Returns: `void`

#### _updateRGBFromHSV

`protected void _updateRGBFromHSV ( )`
Updates the RGB values from the current state of the HSV values. Executed when the one of the HSV form fields are updated _updateRGBFromHSV

Returns: `void`

#### _updateSliders

`protected void _updateSliders ( )`
Moves the sliders into the position dictated by the current state of the control

Returns: `void`

#### _updateSwatch

`protected void _updateSwatch ( )`
Updates the background of the swatch with the current rbg value. Also updates the websafe swatch to the closest websafe color

Returns: `void`

#### _useFieldValue

`protected void _useFieldValue ( e , el , prop )`
Use the value of the text field to update the control

Parameters:
  `e <Event>` an event
  `el <HTMLElement>` the field
  `prop <string>` the key to the linked property

Returns: `void`

#### getElement

`HTMLElement getElement ( id )`
Returns the element reference that is saved. The id can be either the element id, or the key for this id in the "id" config attribute. For instance, the host element id can be obtained by passing its id (default: "yui_picker") or by its key "YUI_PICKER".

Parameters:
  `id <string>` the element id, or key

Returns: `HTMLElement`
  a reference to the element

#### initAttributes

`void initAttributes ( attr )`
Sets up the config attributes and the change listeners for this properties

Parameters:
  `attr <object>` An object containing default attribute values

Returns: `void`

#### initPicker

`void initPicker ( )`
Sets the initial state of the sliders

Returns: `void`

#### setValue

`void setValue ( rgb , silent )`
Sets the control to the specified rgb value and moves the sliders to the proper positions

Parameters:
  `rgb <[int, int, int]>` the rgb value
  `silent <boolean>` whether or not to fire the change event

Returns: `void`

#### syncUI

`void syncUI ( skipAnim )`
Wrapper for _updateRGB, but allows setting

Parameters:
  `skipAnim <Boolean>` Omit Slider animation for this action

Returns: `void`

#### Methods inherited from YAHOO.util.Element:

`_setHTMLAttrConfig, addClass, addListener, appendChild, appendTo, delegate, fireQueue, getElementsByClassName, getElementsByTagName, getStyle, hasChildNodes, hasClass, initAttributes, insertBefore, on, removeChild, removeClass, removeDelegate, removeListener, replaceChild, replaceClass, setStyle, subscribe`

#### Methods inherited from YAHOO.util.AttributeProvider:

`configureAttribute, fireBeforeChangeEvent, fireChangeEvent, get, getAttributeConfig, getAttributeKeys, refresh, register, resetAttributeConfig, resetValue, set, setAttributeConfig, setAttributes`

### Events

#### beforeBlueChange

`beforeBlueChange ( event )`
Fires before the value for the configuration attribute 'blue' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeContainerChange

`beforeContainerChange ( event )`
Fires before the value for the configuration attribute 'container' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeElementsChange

`beforeElementsChange ( event )`
Fires before the value for the configuration attribute 'elements' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeGreenChange

`beforeGreenChange ( event )`
Fires before the value for the configuration attribute 'green' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeHexChange

`beforeHexChange ( event )`
Fires before the value for the configuration attribute 'hex' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeHueChange

`beforeHueChange ( event )`
Fires before the value for the configuration attribute 'hue' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeIdsChange

`beforeIdsChange ( event )`
Fires before the value for the configuration attribute 'ids' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeImagesChange

`beforeImagesChange ( event )`
Fires before the value for the configuration attribute 'images' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforePickersizeChange

`beforePickersizeChange ( event )`
Fires before the value for the configuration attribute 'pickersize' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeRedChange

`beforeRedChange ( event )`
Fires before the value for the configuration attribute 'red' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeSaturationChange

`beforeSaturationChange ( event )`
Fires before the value for the configuration attribute 'saturation' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeShowcontrolsChange

`beforeShowcontrolsChange ( event )`
Fires before the value for the configuration attribute 'showcontrols' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeShowhexcontrolsChange

`beforeShowhexcontrolsChange ( event )`
Fires before the value for the configuration attribute 'showhexcontrols' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeShowhexsummaryChange

`beforeShowhexsummaryChange ( event )`
Fires before the value for the configuration attribute 'showhexsummary' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeShowhsvcontrolsChange

`beforeShowhsvcontrolsChange ( event )`
Fires before the value for the configuration attribute 'showhsvcontrols' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeShowrgbcontrolsChange

`beforeShowrgbcontrolsChange ( event )`
Fires before the value for the configuration attribute 'showrgbcontrols' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeShowwebsafeChange

`beforeShowwebsafeChange ( event )`
Fires before the value for the configuration attribute 'showwebsafe' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeTxtChange

`beforeTxtChange ( event )`
Fires before the value for the configuration attribute 'txt' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeValueChange

`beforeValueChange ( event )`
Fires before the value for the configuration attribute 'value' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeWebsafeChange

`beforeWebsafeChange ( event )`
Fires before the value for the configuration attribute 'websafe' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### blueChange

`blueChange ( event )`
Fires when the value for the configuration attribute 'blue' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### containerChange

`containerChange ( event )`
Fires when the value for the configuration attribute 'container' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### elementsChange

`elementsChange ( event )`
Fires when the value for the configuration attribute 'elements' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### greenChange

`greenChange ( event )`
Fires when the value for the configuration attribute 'green' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### hexChange

`hexChange ( event )`
Fires when the value for the configuration attribute 'hex' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### hueChange

`hueChange ( event )`
Fires when the value for the configuration attribute 'hue' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### idsChange

`idsChange ( event )`
Fires when the value for the configuration attribute 'ids' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### imagesChange

`imagesChange ( event )`
Fires when the value for the configuration attribute 'images' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### pickersizeChange

`pickersizeChange ( event )`
Fires when the value for the configuration attribute 'pickersize' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### redChange

`redChange ( event )`
Fires when the value for the configuration attribute 'red' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### saturationChange

`saturationChange ( event )`
Fires when the value for the configuration attribute 'saturation' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### showcontrolsChange

`showcontrolsChange ( event )`
Fires when the value for the configuration attribute 'showcontrols' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### showhexcontrolsChange

`showhexcontrolsChange ( event )`
Fires when the value for the configuration attribute 'showhexcontrols' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### showhexsummaryChange

`showhexsummaryChange ( event )`
Fires when the value for the configuration attribute 'showhexsummary' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### showhsvcontrolsChange

`showhsvcontrolsChange ( event )`
Fires when the value for the configuration attribute 'showhsvcontrols' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### showrgbcontrolsChange

`showrgbcontrolsChange ( event )`
Fires when the value for the configuration attribute 'showrgbcontrols' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### showwebsafeChange

`showwebsafeChange ( event )`
Fires when the value for the configuration attribute 'showwebsafe' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### txtChange

`txtChange ( event )`
Fires when the value for the configuration attribute 'txt' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### valueChange

`valueChange ( event )`
Fires when the value for the configuration attribute 'value' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### websafeChange

`websafeChange ( event )`
Fires when the value for the configuration attribute 'websafe' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### Events inherited from YAHOO.util.Element:

`appendTo, available, beforeAppendTo, beforeElementChange, contentReady, elementChange,`

### Configuration Attributes

#### blue `- int`

The current blue value 0-255

#### container `- YAHOO.widget.Panel`

If the color picker will live inside of a container object, set, provide a reference to it so the control can use the container's events.

#### elements `- {id: HTMLElement}`

The element refs used by this control. Set at initialization

#### green `- int`

The current green value 0-255

#### hex `- string`

The current hex value #000000-#FFFFFF, without the #

#### hue `- int`

The current hue value 0-360

#### ids `- writeonce {referenceid: realid}`

A list of element ids and/or element references used by the control. The default is the this.ID list, and can be customized by passing a list in the contructor

#### images `- writeonce {key: image}`

The img src default list is this.IMAGES

#### pickersize `- int`

The size of the picker. Trying to change this is not recommended.
Default Value: 180

#### red `- int`

The current red value 0-255

#### saturation `- int`

The current saturation value 0-100

#### showcontrols `- boolean`

Hide/show the entire set of controls
Default Value: true

#### showhexcontrols `- boolean`

Hide/show the hex controls
Default Value: true

#### showhexsummary `- boolean`

Hide/show the hex summary
Default Value: true

#### showhsvcontrols `- boolean`

Hide/show the hsv controls
Default Value: false

#### showrgbcontrols `- boolean`

Hide/show the rgb controls
Default Value: true

#### showwebsafe `- boolean`

Hide/show the websafe swatch
Default Value: true

#### txt `- writeonce {key: txt}`

A list of txt strings for internationalization. Default is this.TXT

#### value `- int`

The current value/brightness value 0-100

#### websafe `- int`

The closest current websafe value

#### Configuration attributes inherited from YAHOO.util.Element:

`element,`

Copyright © 2009 Yahoo! Inc. All rights reserved.