Common Flex Controls

The Flex framework includes a plethora of basic, and not so basic, controls for building beautiful and functional user interfaces. This documentation does not intend to introduce all of them, but rather the common controls used frequently in many Flex applications.

All of the controls introduced on this page belong to the mx.controls package.

TODO... embed example (X_CommonControls)

The examples and code below make use of MXML and Events.

Button (mx.controls.Button)

A Button is... oh you know what a button is. Just click it.

Commonly used properties:

• label:String - the string label for the button
• icon:Class - an image or icon
• useHandCursor:Boolean - makes the cursor appear as a hand rather than the standard arrow

Commonly used events:

• click - dispatched when the button is clicked

Button code example:

   <mx:Button label="Push Me" click="Alert.show('Button Pushed');" />

CheckBox (mx.controls.CheckBox)

The CheckBox control consists of a small box that can contain a check mark. When a user clicks a CheckBox control or its associated text, the CheckBox control toggles its state (from checked to unchecked or from unchecked to checked).

A CheckBox can have an optional label, the text of which can be positioned to the left, right, top, or bottom or the control.

Commonly used properties:

• selected:Boolean - whether or not the box is checked
• label:String - the text of the associated label
• labelPlacement:String - where to position the associated text (right, left, bottom, or top)

Commonly used events:

• change - dispatched when the selected property changes
• click - dispatched when the check box is clicked (checked or unchecked)

CheckBox code example:

   <mx:CheckBox label="CheckBox" click="Alert.show('CheckBox Clicked');" />

RadioButton (mx.controls.RadioButton)

The RadioButton control lets a select a single choice within a set of mutually exclusive choices. A RadioButton group is composed of two or more controls with the same groupName property.

A RadioButton can have an optional label, the text of which can be positioned to the left, right, top, or bottom or the control.

Commonly used properties:

• groupName:String - the name of the group the radio button belongs too
• selected:Boolean - whether or not the box is checked
• label:String - the text of the associated label
• labelPlacement:String - where to position the associated text (right, left, bottom, or top)

Commonly used events:

• change - dispatched when the selected property changes
• click - dispatched when the check box is clicked (checked or unchecked)

RadioButton code example:

   <mx:RadioButton label="RadioButton 1" click="Alert.show('RadioButton 1 Clicked');" />
   <mx:RadioButton label="RadioButton 2" click="Alert.show('RadioButton 2 Clicked');" />

ComboBox (mx.controls.ComboBox)

A ComboBox control contains a drop-down list from which the user can select a single value. A ComboBox can be editable, allowing the user can to type into the input portion to specify a value not in the list.

Commonly used properties:

• dataProvider:Object - the data provider used to populate the drop-down list
• selectedItem:Object - the item selected in the data provider from the drop-down list
• selectedIndex:Number - the index of the selectedItem
• prompt:String - a string to use to prompt the user to make a selection (when selectedIndex = -1)
• editable:Boolean - whether or not the user may input a value

Commonly used events:

• change - event fired when a selection is made from the drop-down list
• enter - dispatched when the user presses the Enter key while typing in the editable text field (if the editable property is set to true and )

ComboBox code example:

   <mx:ComboBox prompt="Is this a ComboBox?" selectedIndex="-1"
   change="Alert.show('You made a selection.');">
      <mx:dataProvider>
         <mx:Array>
            <mx:String>Yes</mx:String>
            <mx:String>No</mx:String>
            <mx:String>Maybe</mx:String>
         </mx:Array>
      </mx:dataProvider>
   </mx:ComboBox>

Image (mx.controls.Image)

The Image control lets you display JPEG, PNG, GIF, and SWF files via run-time loading and/or asset embedding.

Commonly used properties:

• source:Object - the URL, object, class or string name of a class to load
• useHandCursor:Boolean - makes the cursor appear as a hand rather than the standard arrow

Commonly used events:

• click - dispatched when the button is clicked

Image code example:

   <mx:Image source="http://www.adobe.com/ubi/globalnav/include/adobe-lq.png" />

Learn more about Images and Icons in Flex...

Text Controls (Label, Text, TextArea, TextInput)

Flex's Text Controls provide the basic elements for displaying and inputting text in your Flex applications.

Standard Text controls:

• Label - displays single line, non-editable text
• Text - displays multi-line, non-editable text
• TextInput - allows single-line, editable text input
• TextArea - allows multi-line, editable text input

TODO... embed example (TextControls1)

Commonly used properties:

• text - the text the control displays
• htmlText - the HTML text the control displays

Commonly used events:

• change - event fired when the text changes
• textInput - event fired when text is input or pasted

   <mx:TextInput text="TextInput Control" />
   <mx:TextArea text="TextArea Control" />
   <mx:Text text="Text Control" />
   <mx:Label text="Label Control" />

TODO: embed example (TextControls)

Learn more about Text Controls...

DataGrid (mx.controls.DataGrid)

A DataGrid displays tabular data in rows and columns.

TODO: embed example (DataGrid1)

Commonly used properties:

• dataProvider:Object - the data provider used to populate the grid
• columns:Array - the columns used to display the data
• selectedItem:Object - the item selected in the data provider from the drop-down list
• selectedIndex:Number - the index of the selectedItem
• draggableColumns:Boolean - whether or not users can drag and reorder columns

Commonly used events:

• itemClick - event fired when an item (row) is clicked
• itemDoubleClick - event fired when an item (row) is double-clicked

DataGrid code example:

   <mx:DataGrid>
      <mx:columns>
         <mx:DataGridColumn headerText="First Name" />
         <mx:DataGridColumn headerText="Last Name" />
         <mx:DataGridColumn headerText="Email Address" />
      </mx:columns>
   </mx:DataGrid>

Learn more about the Flex DataGrid control...

Numeric Stepper (mx.controls.NumericStepper)

The NumericStepper control select or input a number from a (usually) bounded range.

Commonly used properties:

• value:Number - the numeric value selected/input
• maximum:Number - the maximum allowed value
• minimum:Number - the minimum allowed value
• stepSize:Number - the unit of change between values (non-zero) when the up/down controls are used

Commonly used events:

• change - event fired when the value changes

NumericStepper code example:

   <mx:NumericStepper value="0" minimum="0" maximum="10" stepSize="1" />

HSlider and VSlider (mx.controls.HSlider, VSlider)

The HSlider and VSlider controls are both slider controls. Slider controls let users select a value by moving a slider thumb between the end points of the slider track. The current value of the slider is determined by the relative location of the thumb between the end points of the slider, corresponding to the slider's minimum and maximum values.

Commonly used properties:

• value:Number - the numeric value selected
• maximum:Number - the maximum allowed value
• minimum:Number - the minimum allowed value
• snapInterval:Number - the increment value of the slider thumb as the user moves the thumb
• tickInterval:Number - spacing of the tick marks relative to the maximum value of the control

Commonly used events:

• change - event fired when the value changes

Slider code example:

   <mx:HSlider minimum="0" maximum="10" snapInterval="1" tickInterval="1" />

ProgressBar (mx.controls.ProgressBar)

A ProgressBar control provides a visual representation of the progress of a task over time.

There are two types of ProgressBar controls:

• A determinate ProgressBar control is a linear representation of the progress of a task over time. You use a determinate ProgressBar when the scope of the task is known.
• An indeterminate ProgressBar control represents time-based processes for which the scope is not yet known. As soon as you can determine the scope, you should use a determinate ProgressBar control.

Commonly used properties:

• indeterminate:Boolean - whether the ProgressBar control has a determinate or indeterminate appearance
• mode:String - specifies the method used to update the bar (event, mode, or manual)
• label:String - the text of the associated label
• labelPlacement:String - where to position the associated text (right, left, bottom, or top)

Commonly used events:

• change - dispatched when the selected property changes
• click - dispatched when the check box is clicked (checked or unchecked)

   <mx:ProgressBar indeterminate="true" minimum="0" maximum="100" label="Indeterminate" />

TODO: embed example (Progress1)

Learn more about Flex's ProgressBar control...

Date Controls (DateField and DateChooser)

The DateField control that shows a date in a text field with a calendar icon on its right side. Clikcing the calendar icon opens a DateChooser control, allowing the user to select a date.

The DateChooser control allows a user to select a date, a range of dates, or multiple dates from a calendar-like display.

Commonly used properties:

• selectedDate:Date - date selected by the control

Commonly used events:

• change - dispatched when a date is selected or changed

   <mx:DateField />
   <mx:DateChooser />

TODO... embed example (DateControls1)

Learn more about the Flex Date controls...

List Controls (List, TileList)

List controls refer to a special group of controls that display, and potentially allow manipulation of, collections of items.

Commonly used properties:

• dataProvider:Object - the data provider used to populate the grid
• selectedItem:Object - the item selected in the data provider from the drop-down list
• selectedIndex:Number - the index of the selectedItem

Commonly used events:

• itemClick - event fired when an item (row) is clicked
• itemDoubleClick - event fired when an item (row) is double-clicked

   <mx:List>
      <mx:dataProvider>
         <mx:Array>
            <mx:String>Yes</mx:String>
            <mx:String>No</mx:String>
            <mx:String>Maybe</mx:String>
         </mx:Array>
      </mx:dataProvider>
   </mx:List>

Learn more about Flex List controls...

Related Links:

• Text Controls
• List Controls
• Containers
• http://livedocs.adobe.com/flex/3/langref/mx/controls/package-detail.html