ColorPicker control

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

For complete reference information, see ColorPicker in the ActionScript 3.0 Reference for the Adobe Flash Platform.

About the ColorPicker control

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.

<?xml version="1.0"?>
<!-- controls\colorpicker\CPSimple.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[
            [Bindable]
            public var simpleDP:Array = ['0x000000', '0xFF0000', '0xFF8800',
                '0xFFFF00', '0x88FF00', '0x00FF00', '0x00FF88', '0x00FFFF', 
                '0x0088FF', '0x0000FF', '0x8800FF', '0xFF00FF', '0xFFFFFF'];
        ]]>    
    </fx:Script>
    
    <mx:ColorPicker id="cp" dataProvider="{simpleDP}"/>
</s:Application>

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:

<?xml version="1.0"?>
<!-- controls\colorpicker\CPEvents.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 the event classes.
            import mx.events.DropdownEvent;
            import mx.events.ColorPickerEvent;

            [Bindable]
            public var simpleDP:Array = ['0x000000', '0xFF0000', '0xFF8800',
               '0xFFFF00', '0x88FF00', '0x00FF00', '0x00FF88', '0x00FFFF',
               '0x0088FF', '0x0000FF', '0x8800FF', '0xFF00FF', '0xFFFFFF'];
        
            public function openEvt(event:DropdownEvent):void {
                forChange.text="Opened";
            }       

            public function changeEvt(event:ColorPickerEvent):void {
                forChange.text="Selected Item: "
                   + event.currentTarget.selectedItem + " Selected Index: "
                   + event.currentTarget.selectedIndex;
            }
        ]]>
    </fx:Script>

    <mx:VBox>
        <mx:TextArea id="forChange" 
            width="150"/>
        <mx:ColorPicker id="cp" 
            dataProvider="{simpleDP}"
            open="openEvt(event);" 
            change="changeEvt(event);"/> 
    </mx:VBox>
</s:Application>

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:

<?xml version="1.0"?>
<!-- controls\colorpicker\CPCustomFieldNames.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;

            public function openEvt(event:DropdownEvent):void {
                descriptBox.text="";
            }
            
            public function changeEvt(event:ColorPickerEvent):void {
                descriptBox.text=event.currentTarget.selectedItem.cName
                    + ": " + event.currentTarget.selectedItem.cDescript; 
            }
        ]]>    
    </fx:Script>
    
    <fx:Style>
        .myStyle {
            swatchWidth:25;
            swatchHeight:25;
            textFieldWidth:95;
        }    
    </fx:Style>
    
    <mx:VBox>
        <mx:TextArea id="descriptBox" 
            width="150" height="50"/>
        <mx:ColorPicker id="cp" 
            height="50" width="150"
            labelField="cName" 
            colorField="cVal" 
            change="changeEvt(event)" 
            open="openEvt(event)" 
            swatchPanelStyleName="myStyle"
            editable="false">
            <mx:dataProvider>
                <mx:ArrayCollection>
                    <mx:source>
                        <fx:Object cName="Yellow" cVal="0xFFFF00" 
                            cDescript="A bright, light color."/> 
                        <fx:Object cName="Hot Pink" cVal="0xFF66CC" 
                            cDescript="It's HOT!"/>
                        <fx:Object cName="Brick Red" cVal="0x990000" 
                            cDescript="Goes well with warm colors."/> 
                        <fx:Object cName="Navy Blue" cVal="0x000066" 
                            cDescript="The conservative favorite."/> 
                        <fx:Object cName="Forest Green" cVal="0x006600" 
                            cDescript="Great outdoorsy look."/> 
                        <fx:Object cName="Grey" cVal="0x666666" 
                            cDescript="An old reliable."/>
                    </mx:source>
                </mx:ArrayCollection>
            </mx:dataProvider>
        </mx:ColorPicker>
    </mx:VBox>
</s:Application>

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.