Button and ToggleButton control

Creating a Button control

The Button and ToggleButton controls are part of both the MX and Spark component sets. While you can use the MX controls in your application, Adobe recommends that you use the Spark controls instead.

Note: In MX, you create a toggle button by setting the toggle property of the MX Button control to true. in Spark, the ToggleButton is a separate component.

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 ToggleButton control. A normal Button control stays in its pressed state for as long as the mouse button is down after you select it. A ToggleButton stays in the pressed state until you select it a second time. The ToggleButton control is available in Spark. In MX, the Button control contains a toggle property that provides similar functionality.

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.

You can use customized graphic skins to customize your buttons to match your application’s look and functionality. You can give the Button and ToggleButton controls different skins. The control can change the image skins dynamically. The following table describes the skin states (Spark) and skin styles (MX) available for the Button and ToggleButton controls:

Spark Button skin states	Spark ToggleButton skin states	MX Button skin styles
disabled	disabled	disabledSkin
down	disabledAndSelected	downSkin
over	down	overSkin
up	downAndSelected	selectedDisabledSkin
---	over	selectedDownSkin
---	overAndSelected	selectedOverSkin
---	up	selectedUpSkin
---	upAndSelected	upSkin

Creating a Button control

You define a Button control in MXML by using the <s:Button> tag, as the following example shows. Specify an id value if you intend to refer to the button 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 -->
<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">

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

In Spark, all visual elements of a component, including layout, are controlled by the skin. For more information on skinning, see About Spark skins.

In MX, 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.

Sizing a Button control

By default, Flex stretches the Button control width to fit the size of its label, any icon, plus six 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" encoding="utf-8"?>
<!-- controls\button\ButtonClick.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.controls.Alert;
            protected function myBtn_clickHandler(event:MouseEvent):void {
                Alert.show("Goodbye!");
            }
        ]]>
    </fx:Script>

    <s:Button id="myBtn"
        x="83" y="92"
        label="Hello World!"
        click="myBtn_clickHandler(event)"/>
        
</s:Application>The executing SWF file for the previous example is shown below:

In this example, clicking the Button triggers an Alert control to appear with a message to the user.

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

When the user moves the 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 pointer off the Button control while pressing the mouse button, the control’s appearance returns to the rollover state and it retains focus.
For MX controls, 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. For the Spark ToggleButton, this statement applies to the selected property.

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.

Embedding an icon in a Button control

The Button controls define a style property, icon, that you use to add an icon to the button. A button icon can be a GIF, JPEG, PNG, SVG, or SWF file.

Note: For the MX Button control, icons must be embedded at compile time. You cannot load the icon at runtime.

Use the @Embed syntax in the icon property value to embed an icon 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 runtime, you can use an Image control instead of a Button control.

For more information on embedding resources, see Embedding assets.

The following code example creates a Spark Button control with a label and icon.

<?xml version="1.0" encoding="utf-8"?>
<!-- controls\button\ButtonLabelIconSpark.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 assets.*;
            import mx.controls.Alert;
            protected function myClickHandler():void{
                Alert.show("Thanks for submitting.")
            }
        ]]>
    </fx:Script>
    
    <s:Button id="iconButton"
              width="100" height="30"
              x="10" y="10"
              label="Submit to"
              icon="@Embed('assets/logo.jpg')"
              click="myClickHandler();"/>
</s:Application>The executing SWF file for the previous example is shown below: