Flex 2 Developer's Guide > Building User Interfaces for Flex Applications > Using Controls > ColorPicker control

ColorPicker control

The ColorPicker control lets users select a color from a drop-down swatch panel (palette). 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 Adobe Flex 2 Language Reference.

Subtopics

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.

The following example shows a collapsed and expanded ColorPicker control that uses the default settings of the mx:ColorPicker tag:

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.

The ColorPicker control has the following default sizing characteristics:

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. For example, the ColorPicker control in the image was generated using the following, minimal, code:

<mx:ColorPicker id="cp"/>

The ColorPicker control uses a list-based data provider for the colors. For more information on this type of data provider, see Using 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. For information on using a more complex dataProvider, see Using Objects to populate a ColorPicker control.

<?xml version="1.0"?>
<!-- controls\colorpicker\CPSimple.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script>
        <![CDATA[
            [Bindable]
            public var simpleDP:Array = ['0x000000', '0xFF0000', '0xFF8800',
                '0xFFFF00', '0x88FF00', '0x00FF00', '0x00FF88', '0x00FFFF', 
                '0x0088FF', '0x0000FF', '0x8800FF', '0xFF00FF', '0xFFFFFF'];
        ]]>    
    </mx:Script>
    
    <mx:ColorPicker id="cp" dataProvider="{simpleDP}"/>
</mx:Application>

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 -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx: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;
            }
        ]]>
    </mx:Script>

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

The ColorPicker control dispatches open event when the swatch panel opens and 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 your 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 -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx: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; 
            }
        ]]>    
    </mx:Script>
    
    <!-- Convert the Array to an ArrayCollection. Do this if 
    you might change the colors in the panel dynamically. -->
    <mx:ArrayCollection id="complexDP" source="{complexDPArray}"/>
    
    <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);" 
            swatchWidth="25" 
            swatchHeight="25"
            textFieldWidth="95" 
            editable="false"/>      
    </mx:VBox>
</mx:Application>

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, and 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, 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 -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx: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; 
            }
        ]]>    
    </mx:Script>
    
    <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)" 
            swatchWidth="25"
            swatchHeight="25" 
            textFieldWidth="95" 
            editable="false">
            <mx:dataProvider>
                <mx:ArrayCollection>
                    <mx:source>
                        <mx:Object cName="Yellow" cVal="0xFFFF00" 
                            cDescript="A bright, light color."/> 
                        <mx:Object cName="Hot Pink" cVal="0xFF66CC" 
                            cDescript="It's HOT!"/>
                        <mx:Object cName="Brick Red" cVal="0x990000" 
                            cDescript="Goes well with warm colors."/> 
                        <mx:Object cName="Navy Blue" cVal="0x000066" 
                            cDescript="The conservative favorite."/> 
                        <mx:Object cName="Forest Green" cVal="0x006600" 
                            cDescript="Great outdoorsy look."/> 
                        <mx:Object cName="Grey" cVal="0x666666" 
                            cDescript="An old reliable."/>
                    </mx:source>
                </mx:ArrayCollection>
            </mx:dataProvider>
        </mx:ColorPicker>
    </mx:VBox>
</mx:Application>

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, numeric keys, and the Backspace and Delete keys enter and remove text in the color text box. You can also use the following keystrokes to control the ColorPicker:

Flex 2.01