The ColorPicker control is part of the MX component set.
There is no Spark equivalent.
The ColorPicker control
lets users select a color from a drop-down swatch panel. It initially
appears as a preview sample with the selected color. When a user selects
the control, a color swatch panel appears. The panel includes a
sample of the selected color and a color swatch panel. By default,
the swatch panel displays the web-safe colors (216 colors, where
each of the three primary colors has a value that is a multiple
of 33, such as #CC0066).
When you open the ColorPicker control, the swatch panel
expands over other controls on the application, and normally opens
downwards. If the swatch panel would hit the lower boundary of the
application, but could fit above color picker button, it opens upward.
If you set the showTextField property to true (the
default), the panel includes a text box with a label for the selected
color. If you display a text box and set the editable property
to true (the default), the user can specify a color
by entering a hexadecimal value.
Flex populates the color swatch panel and the text box from a
data provider. By default, the control uses a data provider that
includes all the web-safe colors. If you use your own data provider
you can specify the following:
The colors to display
You must specify the colors if you use your own dataProvider.
Labels to display in the text box for the colors
If you do not specify text labels, Flex uses the hexadecimal
color values.
Additional information for each color
This information can include any information that is of use
to your application, such as IDs or descriptive comments.
The
following image shows an expanded ColorPicker control that uses
a custom data provider that includes color label values. It also
uses styles to set the sizes of the display elements:
Creating a ColorPicker control
You
use the <mx:ColorPicker> tag to define a ColorPicker control
in MXML. Specify an id value if you intend to refer
to a component elsewhere in your MXML, either in another tag or
in an ActionScript block.
The ColorPicker control uses a list-based data provider for the
colors. For more information on this type of data provider, see Data providers and collections. If you omit the data provider,
the control uses a default data provider with the web-safe colors.
The data provider can be an array of colors or an array of objects.
The following example populates a ColorPicker with a simple array
of colors.
The executing SWF file for the previous example is shown below:
You
typically use events to handle user interaction with a ColorPicker
control. The following example adds an event listener for a change event
and an open event to the previous example ColorPicker
control:
The executing SWF file for the previous example is shown below:
The ColorPicker control dispatches open event
when the swatch panel opens. It dispatches a change event
when the value of the control changes due to user interaction. The currentTarget property
of the object passed to the event listener contains a reference
to the ColorPicker control. In this example, the event listeners
use two properties of the ColorPicker control, selectedItem and selectedIndex.
Every change event updates the TextArea control
with the selected item and the item’s index in the control, and
an open event displays the word Opened.
If you populate the ColorPicker control from an array of color
values, the target.selectedItem field contains
the hexadecimal color value. If you populate it from an array of
Objects, the target.selectedItem field contains
a reference to the object that corresponds to the selected item.
The index of items in the ColorPicker control is zero-based,
which means that values are 0, 1, 2, ... , n - 1, where n is
the total number of items; therefore, the target.selectedIndex value
is zero-based, and a value of 2 in the preceding example refers
to the data provider entry with color 0xFF8800.
Using Objects to populate a ColorPicker control
You can populate a ColorPicker
control with an Array of Objects. By default, the ColorPicker uses
two fields in the Objects: one named color, and
another named label. The label field
value determines the text in the swatch panel’s text field. If the
Objects do not have a label field, the control
uses the color field value in the text field. You
can use the ColorPicker control’s colorField and labelField properties
to specify different names for the color and label fields. The Objects
can have additional fields, such as a color description or an internal
color ID, that you can use in ActionScript.
Example: ColorPicker control that uses Objects
The following example
shows a ColorPicker that uses an Array of Objects with three fields: color, label,
and descript:
<?xml version="1.0"?>
<!-- controls\colorpicker\CPObjects.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx">
<fx:Script>
<![CDATA[
import mx.events.ColorPickerEvent;
import mx.events.DropdownEvent;
[Bindable]
public var complexDPArray:Array = [
{label:"Yellow", color:"0xFFFF00",
descript:"A bright, light color."},
{label:"Hot Pink", color:"0xFF66CC",
descript:"It's HOT!"},
{label:"Brick Red", color:"0x990000",
descript:"Goes well with warm colors."},
{label:"Navy Blue", color:"0x000066",
descript:"The conservative favorite."},
{label:"Forest Green", color:"0x006600",
descript:"Great outdoorsy look."},
{label:"Grey", color:"0x666666",
descript:"An old reliable."}]
public function openEvt(event:DropdownEvent):void {
descriptBox.text="";
}
public function changeEvt(event:ColorPickerEvent):void {
descriptBox.text=event.currentTarget.selectedItem.label
+ ": " + event.currentTarget.selectedItem.descript;
}
]]>
</fx:Script>
<fx:Style>
.myStyle {
swatchWidth:25;
swatchHeight:25;
textFieldWidth:95;
}
</fx:Style>
<!-- Convert the Array to an ArrayCollection. Do this if
you might change the colors in the panel dynamically. -->
<fx:Declarations>
<mx:ArrayCollection id="complexDP" source="{complexDPArray}"/>
</fx:Declarations>
<mx:VBox>
<mx:TextArea id="descriptBox"
width="150" height="50"/>
<mx:ColorPicker id="cp"
height="50" width="150"
dataProvider="{complexDP}"
change="changeEvt(event);"
open="openEvt(event);"
editable="false"/>
</mx:VBox>
</s:Application>
The executing SWF file for the previous example is shown below:
In this example, the selectedItem property
contains a reference to the object defining the selected item. The
example uses selectedItem.label to access the object’s label property
(the color name), and selectedItem.descript to
access the object’s descript property (the color
description). Every change event updates the TextArea control
with the label property of the selected item and
the item’s description. The open event clears the
current text in the TextArea control each time
the user opens up the ColorPicker to display the swatch panel.
This
example also uses several of the ColorPicker properties and styles
to specify the control’s behavior and appearance. The editable property
prevents users from entering a value in the color label box (so
they can only select the colors from the dataProvider). The swatchWidth and swatchHeight styles
control the size of the color samples in the swatch panel. The textFieldWidth style ensures
that the text field is long enough to accommodate the longest color name.
Using custom field names
In some cases, you might want to use
custom names for the color and label fields. For example, you would
use a custom name if the data comes from an external data source
with custom column names. The following code changes the previous
example to use custom color and label fields called cName and cVal.
It also shows how to use an <mx:dataProvider> tag
to populate the data provider:
The executing SWF file for the previous example is shown below:
User interaction
A ColorPicker control
can be editable or noneditable. In a noneditable ColorPicker control,
the user must select a color from among the swatch panel options. In
an editable ColorPicker control, a user can select swatch panel
items or enter a hexadecimal color value directly into the label
text field at the top of the swatch panel. Users can type numbers
and uppercase or lowercase letters in the ranges a-f and A-F in
the text box; it ignores all other non-numeric characters.
Mouse interaction
You can use the mouse to navigate and select
from the control:
Click the collapsed control to display
or hide the swatch panel.
Click any swatch in the swatch panel to select it and close
the panel.
Click outside the panel area to close the panel without making
a selection.
Click in the text field to move the text entry cursor.
Keyboard interaction
If the ColorPicker is editable and the swatch
panel has the focus, alphabetic keys in the range A-F and a-f and
numeric keys enter text in the color box. The Backspace and Delete
keys remove text in the color text box. You can also use the following
keystrokes to control the ColorPicker:
Key
Description
Control+Down Arrow
Opens the swatch panel and puts the focus
on the selected swatch.
Control+Up Arrow
Closes the swatch panel, if open.
Home
Moves the selection to the first color in
a row of the swatch panel. Has no effect if there is a single column.
End
Moves the selection to the last color in
a row of the swatch panel. Has no effect if there is a single column.
Page Up
Moves the selection to the top color in
a column of the swatch panel. Has no effect if there is a single
row.
Page Down
Moves the selection to the bottom color
in a column of the swatch panel. Has no effect if there is a single row.
Escape
Closes the swatch panel without changing
the color in the color picker.
Most Web browsers do not support
using this key.
Enter
Selects the current color from the swatch
panel and closes the swatch panel; equivalent to clicking a color swatch.
If the focus is on the text field of an editable ColorPicker, selects
the color specified by the field text.
Arrows
When the swatch panel is open, moves the
focus to the next color left, right, up, and down in the swatch grid.
On a single-row swatch panel, Up and Right Arrow keys are equivalent,
and Down and Left Arrow keys are equivalent.
On a multirow
swatch panel, the selection wraps to the beginning or end of the
next or previous line. On a single-row swatch panel, pressing the
key past the beginning or end of the row loops around on the row.
When
the swatch panel is closed, but has the focus, pressing the Up and
Down arrow keys has no effect. The Left and Right Arrow keys change
the color picker selection, moving through the colors as if the
panel were open.
Note: When the swatch panel
is open, you cannot use the Tab and Shift+Tab keys to move the focus
to another object.
