The Button control is a commonly used rectangular button. Button controls look like they can be pressed, and have a text label, an icon, or both on their face. You can optionally specify graphic skins for each of several Button states.

You can create a normal Button control or a toggle Button control. A normal Button control stays in its pressed state for as long as the mouse button is down after you select it. A toggle Button controls stays in the pressed state until you select it a second time.

Buttons typically use event listeners to perform an action when the user selects the control. When a user clicks the mouse on a Button control, and the Button control is enabled, it dispatches a click event and a buttonDown event. A button always dispatches events such as the mouseMove, mouseOver, mouseOut, rollOver, rollOut, mouseDown, and mouseUp events whether enabled or disabled.

The following example shows a Button control:

You can use customized graphic skins to customize your buttons to match your application's look and functionality. You can give the Button control different image skins for the up, down, and disabled states, and the skins for these states can differ depending on whether the button is selected or not selected. The control can change the image skins dynamically.

The following example shows seven Button controls to control video recording and playback arranged in an HBox layout container. All buttons are in their up state:

Creating a Button control

You define a Button control in MXML by using the <mx:Button> tag, as the following example shows. 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 following code creates a Button control with the label "Hello world!":

<?xml version="1.0"?>
<!-- controls\button\ButtonLabel.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Button id="button1" label="Hello world!" width="100"/>
</mx:Application>
The executing SWF file for the previous example is shown below:

A Button control's icon, if specified, and label are centered within the bounds of the Button control. You can position the text label in relation to the icon by using the labelPlacement property, which accepts the values right, left, bottom, and top.

Embedding an icon in a Button control

Button icons must be embedded at compile time. You cannot reference a Button icon at run time. You can use the @Embed syntax in the icon property value to embed any GIF, JPEG, PNG, SVG, or SWF file, or you can bind to an image that you defined within a script block by using [Embed] metadata. If you must reference your button graphic at run time, you can use an <mx:Image> tag instead of an <mx:Button> tag.

For more information on embedding resources, see Embedding Assets.

The following code example creates a Button control with a label and an icon:

<?xml version="1.0"?>
<!-- controls\button\ButtonLabelIcon.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Button 
        label="Icon Button" 
        icon="@Embed(source='assets/logo.jpg')"
        height="36"
     />
</mx:Application>
The executing SWF file for the previous example is shown below:

The icon is in the assets subdirectory of the directory containing the application file. This results in a button with the icon displayed to the left of the label text:

For an overview of resource embedding, see Embedding Assets.

Sizing a Button control

By default, Flex stretches the Button control width to fit the size of its label, any icon, plus 6 pixels of padding around the icon. You can override this default width by explicitly setting the width property of the Button control to a specific value or to a percentage of its parent container. If you specify a percentage value, the button resizes between its minimum and maximum widths as the size of its parent container changes.

If you explicitly size a Button control so that it is not large enough to accommodate its label, the label is truncated and terminated by an ellipsis (...). The full label displays as a tooltip when you move the mouse over the Button control. If you have also set a tooltip by using the tooltip property, the tooltip is displayed rather than the label text.

Text that is vertically larger than the Button control is also clipped. If you explicitly size a Button control so that it is not large enough to accommodate its icon, icons larger than the Button control extend outside the Button control's bounding box.

Button control user interaction

When a user clicks the mouse on a Button control, the Button control dispatches a click event, as the following example shows:

<?xml version="1.0"?>
<!-- controls\button\ButtonClick.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <!-- Input field. -->
    <mx:TextInput id="myInput" width="150" text=""/>

    <!-- Button control that triggers the copy. -->
    <mx:Button id="myButton" label="Copy Text"
        click="myText.text=myInput.text;"/>

    <!-- Output text box. -->
    <mx:TextArea id="myText" text="" width="150" height="20"/>
</mx:Application>
The executing SWF file for the previous example is shown below:

In this example, clicking the Button control copies the text from the TextInput control to the TextArea control.

If a Button control is enabled, it behaves as follows:

• When the user moves the mouse pointer over the Button control, the Button control displays its rollover appearance.
• When the user clicks the Button control, focus moves to the control and the Button control displays its pressed appearance. When the user releases the mouse button, the Button control returns to its rollover appearance.
• If the user moves the mouse pointer off the Button control while pressing the mouse button, the control's appearance returns to the original state and it retains focus.
• If the toggle property is set to true, the state of the Button control does not change until the user releases the mouse button over the control.

If a Button control is disabled, it displays its disabled appearance, regardless of user interaction. In the disabled state, all mouse or keyboard interaction is ignored.

Skinning a Button control

You can specify a set of up to eight different image skin properties, where each property corresponds to a different button state. These skins determine the basic appearance of the buttons. You can specify images for each of the following button states:

• Up (the mouse is not over the control)
• Down (the mouse is over the control and the mouse button is pressed)
• Over (the mouse hovers over the control)
• Disabled
• Selected and up
• Selected and down
• Selected and over
• Selected and disabled

You specify the default appearance of a Button control by specifying an up state image (the upSkin property). All other states use the up state image or the image from another state as their default. For example, if you do not specify an image for the down state, Flex uses the image specified for the over state; if you don't specify an image for the over state, Flex uses the image for the up state. The selected states are used only for toggle buttons that are selected (pressed).

The skin image determines the appearance of the button, including its shape. The image can be GIF, JPEG, PNG, SVG, or SWF file. You can create the skins as independent image files, or incorporate multiple images in a single SWF file.

Flex must embed the button images in the application's SWF file at compile time; you cannot download images from the server at run time. To embed the image, use the @Embed MXML compiler directive. The following code example shows how to use a GIF file as the up (default) button image:

upSkin="@Embed(source='assets/buttonUp.gif')"

The following code example creates a toggle button with an image for up, down, over, and disabled states. The button has both a label and an icon:

<?xml version="1.0"?>
<!-- controls\button\ButtonSkin.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

<mx:Button label="Image Button" 
    toggle="true" 
    color="0xFFFFAA" 
    textRollOverColor="0xAAAA55" 
    textSelectedColor="0xFFFF00"
    upSkin="@Embed(source='assets/buttonUp.gif')"
    overSkin="@Embed(source='assets/buttonOver.gif')"
    downSkin="@Embed(source='assets/buttonDown.gif')"
    disabledSkin="@Embed(source='assets/buttonDisabled.gif')"
    icon="@Embed(source='assets/logo.gif')"/>
</mx:Application>
The executing SWF file for the previous example is shown below: