Adobe

Products

Acrobat

Creative Cloud

Creative Suite

Digital Marketing Suite

Digital Publishing Suite

Elements

Photoshop

Touch Apps

Student and Teacher Editions

More products

Solutions

Creative tools for business

Digital marketing

Digital media

Education

Financial services

Government

Web Experience Management

Using the Button component

by Peter deHaan

Content

Creating an instance of the Button component using ActionScript
Setting a Button component's label
Resizing and positioning buttons
Detecting when a button is pressed
Enabling and disabling Button instances
Setting button styles
Setting text formats
Embedding fonts
Creating emphasized buttons
Setting icons
Creating auto-repeating buttons
Creating toggle buttons

Modified

23 November 2010

Requirements

User level

Beginning

Required products

Flash Professional (Download trial)

The Button component is a resizable, rectangular button that a user can press with the mouse or the spacebar to initiate an action in the application. You can add a custom icon to a Button instance. You can also change the behavior of a Button instance from push to toggle. A toggle button stays pressed when clicked and returns to its up state when clicked again.

A button is a fundamental part of many forms and web applications. You can use buttons wherever you want a user to initiate an event. For example, most forms have a Submit button. You could also add Previous and Next buttons to a presentation.

The next sections describe the most popular and useful ways to use this component.

Note: The following examples require that a Button component exists in your document's library.

Creating an instance of the Button component using ActionScript

To dynamically create a new instance of the Button class using ActionScript, you first need to drag a copy of the component from the Components panel into your current Flash document's library. Next, you need to import the fl.controls.Button class using the import statement. This step is required since the component files are not implicitly imported, like the flash.* packages. Once the Button class has been imported into your current document, you can create a new Button instance using the new operator. Finally, the new instance can be added to the display list using the addChild() method.

Note: To see which files are implicitly imported, see the implicitImports.xml XML file in the Adobe Flash CS3 Configuration\ActionScript 3.0 folder.

Example

The following example creates a new instance of the Button component dynamically and adds it to the display list. You must first drag a copy of the component from the Component's panel into the library.

        import fl.controls.Button;

var myButton:Button = new Button();
addChild(myButton);

Result

This content requires Flash To view this content, JavaScript must be enabled, and you need the latest version of the Adobe Flash Player. To view this content, JavaScript must be enabled, and you need the latest version of the Adobe Flash Player.

Download the source files for this example:

using_button_component_section01_example1.zip (ZIP, 390K)

Setting a Button component's label

The text displayed on a Button component instance can be changed by setting the instance's label property. The label only accepts plain text (not HTML-formatted text) but text formatting can be applied by creating a text format and applying it to the button using the setStyle() method. For more information on working with button text formats, see Setting text formats.

If you are using an icon with a Button instance, you can control the placement of the text label, relative to the icon, by setting the labelPlacement property using one of the constants from the ButtonLabelPlacement class (fl.controls.ButtonLabelPlacement). For more information on working with button icons, see Setting icons.

Note: Setting a Button component's label property dispatches a labelChange event (represented by the fl.events.ComponentEvent.LABEL_CHANGE constant).

Example

The following example creates a new Button instance and sets the button's label to "Click me":

        import fl.controls.Button;

var myButton:Button = new Button();
myButton.label = "Click me";
addChild(myButton);

Result

Download the source files for this example:

using_button_component section02 example1.zip (ZIP, 390K)

Resizing and positioning buttons

There are several methods and properties you can use to resize and reposition instances on the Stage. Resizing component instances can be done using one of two techniques: 1) setting the width and height properties, or 2) calling the setSize() method (inherited from fl.core.UIComponent). The setSize() method takes two parameters (width and height) and resizes the component accordingly. Using either one of these two techniques causes a resize event (represented by the fl.events.ComponentEvent.RESIZE constant) to be dispatched. By listening for this event, you can detect when a component instance has been resized and respond as needed. One benefit to using the setSize() method instead of the width and height properties is that the resize event is dispatched only once instead of twice (once for the width property and once for the height property).

In addition to setting a component's x-coordinate and y-coordinate using their x and y properties, you can also reposition a component on the Stage using the move() method (which like the setSize() method, is inherited from the UIComponent class). Setting a component's x property or y property, or calling the instance's move() method, causes the component to dispatch a move event (represented by the fl.events.ComponentEvent.MOVE constant).

Example

The following example creates a Button instance, resizes it using the setSize() method and repositions it using the move() method:

        import fl.controls.Button;

var myButton:Button = new Button();
myButton.label = "Click me";
myButton.setSize(120, 40);
myButton.move(10, 10);
addChild(myButton);
                  
    

Result

Download the source files for this example:

using_button_component section03 example1.zip (ZIP, 390K)

Example

The following example creates a new Button instance and listens for its resize and move events to be dispatched:

        // Import the required component classes.  
import fl.controls.Button;
import fl.events.ComponentEvent;

// Create a new TextField object, and add it to the display list. 
var myTextField:TextField = new TextField();
myTextField.autoSize = TextFieldAutoSize.LEFT;
myTextField.multiline = true;
myTextField.text = "";
myTextField.x = 140;
myTextField.y = 10;
addChild(myTextField);

/* Create a new Button component instance, add listeners for the move and 
   resize events, and add it to the display list. */
var myButton:Button = new Button();
myButton.label = "Click me";
myButton.addEventListener(ComponentEvent.RESIZE, resizeHandler);
myButton.addEventListener(ComponentEvent.MOVE, moveHandler);
myButton.setSize(120, 40);
myButton.move(10, 10);
addChild(myButton);

/* Handler function for the Button component instance. This function appends 
   text to the text field after the button was resized. */
function resizeHandler(evt:ComponentEvent):void {
    var btn:Button = evt.currentTarget as Button;
    myTextField.appendText("component was resized. w:" + btn.width + ", h:" + btn.height + "\n");
}

/* Handler function for the Button component instance. This function appends
   text to the text field after the button was moved. */
function moveHandler(evt:ComponentEvent):void {
    var btn:Button = evt.currentTarget as Button;
    myTextField.appendText("component was moved. x:" + btn.x + ", y:" + btn.y + "\n");
}
             
    

Result

Download the source files for this example:

using_button_component section03 example2.zip (ZIP, 422K)

Detecting when a button is pressed

You can detect when a Button instance is pressed by listening for its click event (using the flash.events.MouseEvent.CLICK constant) or its change event (using the flash.events.Event.CHANGE constant) to be dispatched. Using ActionScript 3.0, you listen for events using the addEventListener() method. For more information on handling events in ActionScript 3.0, see the Event handling Quick Start article.

Note: ActionScript 2.0 provided three event handling models. ActionScript 3.0 simplifies the process by using a single event handling model. Also, ActionScript 2.0 didn't use constants for event names but ActionScript 3.0 does.

The following example creates a listener for the click event on a Button instance called myButton.

        // Requires a Button component instance on the Stage with an instance name of "myButton".
myButton.addEventListener(MouseEvent.CLICK, clickHandler);

function clickHandler(eventObj:MouseEvent):void {
    trace("clicked");
}
     
    

For more information on handling component events, see Handling events section of the Getting started with Flash CS3 user interface components Quick Start article.

For more information on events with the Button component, see Creating auto-repeating buttons and Creating toggle buttons.

Example

The following example uses an event listener to detect when the button's click event has been dispatched, and updates the label accordingly:

        // Import the required component classes.  
import fl.controls.Button;

// Create a new Button component instance, and add it to the display list.
var myButton:Button = new Button();
myButton.label = "Click me";
myButton.move(10, 10);
myButton.addEventListener(MouseEvent.CLICK, clickHandler);
addChild(myButton);

/* Handler function for the Button component instance. This function updates
   the button's label property when the button is clicked. */
function clickHandler(event:MouseEvent):void {
    myButton.label = "Ouch!";
}
        
    

The previous example listens for the click event. Later in this article, you also will learn how you can listen for the buttonDown and change events.

Result

Download the source files for this example:

using_button_component section04 example1.zip (ZIP, 390K)

Example

If you want the button to display a hand cursor when the mouse is over the instance, set the button instance's useHandCursor property to true:

        import fl.controls.Button;

var myButton:Button = new Button();
myButton.label = "useHandCursor = true";
myButton.width = 160;
myButton.move(10, 10);
myButton.useHandCursor = true;
addChild(myButton);

    

Result

Download the source files for this example:

using_button_component section04 example2.zip (ZIP, 390K)

Enabling and disabling Button instances

There are many cases where you might want to disable a button in your application. For example, you might want to prevent a user from hitting the Submit button twice, or you might want to disable a Submit button until the user first checks a check box.

Note: You can specify alternate icons, skins, and text formats to use when a Button instance is disabled. For more information, see the inherited disabledIcon, disabledSkin, disabledTextFormat, selectedDisabledIcon, and selectedDisabledSkin styles in the ActionScript 3.0 Reference for the Adobe Flash Platform.

Example

The following example creates two Button instances. The first instance is enabled and allows the user to click on the button. The second instance has its enabled property set to false which prevents the user from interacting with the component and dispatching its click event:

        // Import the required component classes.  
import fl.controls.Button;

// Create a new Button component instance and add it to the display list.
var enabledButton:Button = new Button();
enabledButton.label = "enabled = true";
enabledButton.move(10, 10);
enabledButton.addEventListener(MouseEvent.CLICK, clickHandler);
addChild(enabledButton);

/* Create a new Button component instance, set the enabled property to false, 
   and add it to the display list. */
var disabledButton:Button = new Button();
disabledButton.enabled = false;
disabledButton.label = "enabled = false";
disabledButton.move(120, 10);
disabledButton.addEventListener(MouseEvent.CLICK, clickHandler);
addChild(disabledButton);

/* Handler function for the enabledButton and disabledButton button instances. This
   function updates the target button's label property when the button is clicked. */
function clickHandler(event:MouseEvent):void {
    var btn:Button = event.currentTarget as Button;
    btn.label = "Ouch!";
}
               
    

Result

Download the source files for this example:

using_button_component section05 example1.zip (ZIP, 390K)

Setting button styles

The ActionScript 3.0 User Interface components also have a completely new method for skinning and styling components. Setting Button styles is now handled using the setStyle() method. You can get a list of each of the Button component's native and inherited styles by using the getStyleDefiniton() method. By setting various Button styles you can do the following tasks:

Set icons to use with a button,
Assign a text format for the button's label
Embed fonts
Change a Button's skins to change its appearance
Specify the interval for an auto-repeating button to dispatch buttonDown events.

When working with styles, you'll often use the following methods:

setStyle() - Sets a style property on a Button instance.
getStyle() - Retrieves a style property that is set in the style lookup chain of the button.
clearStyle() - Deletes a style property from a Button instance.
getStyleDefinition() - Retrieves the default style map for the current button.

Example

The following example uses the getStyleDefinition() method to display a list of the Button component's style names and default values. Clicking the skin styles in the data grid displays a preview of the selected skin. This example requires the Button, DataGrid and UILoader components to be in the library.

        // Import the required component classes.
import fl.containers.UILoader;
import fl.controls.Button;
import fl.controls.DataGrid;
import fl.controls.dataGridClasses.DataGridColumn;
import fl.data.DataProvider;

// Create some variables.
var styleArray:Array = new Array();
var styleObject:Object = Button.getStyleDefinition();
var styleName:String;

/* Convert the styles returned from the getStyleDefinition() method into an 
   array of objects so it can be converted to a data provider. */
for (styleName in styleObject) {
    styleArray.push({name:styleName, value:String(styleObject[styleName]), data:styleObject[styleName]});
}

// Sort the items in the styleArray array alphabetically by name. 
styleArray.sortOn("name", Array.CASEINSENSITIVE);

// Create a new DataGridColumn object.
var nameCol:DataGridColumn = new DataGridColumn("name");
nameCol.headerText = "Style name:";

// Create a new DataGridColumn object.
var valueCol:DataGridColumn = new DataGridColumn("value");
valueCol.headerText = "Default value:";

/* Create a new DataGrid component instance, add the two DataGridGolumn objects created
   earlier, set the data provider to the styleArray array, and add to the display list. */
var styleGrid:DataGrid = new DataGrid();
styleGrid.addColumn(nameCol);
styleGrid.addColumn(valueCol);
styleGrid.dataProvider = new DataProvider(styleArray);
styleGrid.setSize(530, 300);
styleGrid.move(10, 10);
styleGrid.addEventListener(Event.CHANGE, changeHandler);
addChild(styleGrid);

/* Create a UILoader component instance, and add it to the display list. This UILoader will
   be used to display the selected style, as long as it is a visual asset. */ 
var previewLoader:UILoader = new UILoader();
previewLoader.setSize(530, 70);
previewLoader.move(10, 320);
addChild(previewLoader);

/* Handler function for the UILoader component instance. This function gets the currently 
   selected item in the data grid and attempts to set the UILoader instance's source property
   to the selected item's data property. If the item cannot be displayed in a UILoader, the
   UILoader instance's source property is set to null which causes any previously displayed
   content to be cleared. */
function changeHandler(event:Event):void {
    var item:Object = DataGrid(event.currentTarget).selectedItem;
    try {
        previewLoader.source = getDefinitionByName(item.data);
    } catch (error:*) {
        previewLoader.source = null;
    }
}
                 
    

Result

Download the source files for this example:

using_button_component section06 example1.zip (ZIP, 514K)

For examples on setting styles using the setStyle() method, see the following sections:

Setting text formats
Embedding fonts
Creating emphasized buttons
Setting icons

Setting text formats

When customizing a button, you'll most likely want to start with changing the label's text format. Changing the textFormat style allows you to specify a new TextFormat object (flash.text.TextFormat) to use when displaying the label. This allows you to modify the label's alignment, color, font weight (bold), font emphasis (italics), font face, and font size as well as other properties.

Note: Not all properties of the TextFormat class are supported. For example, setting a TextFormat objects url property has no effect on a Button instance.

When working with text formatting, you'll often use the following properties and styles:

textFormat style - The TextFormat object to use to render the button's label by setting TextFormat properties such as font, color, size, and so on..
disabledTextFormat style - The TextFormat object to use to render the button's label when the button is disabled.
embedFonts style - Indicates whether embedded font outlines are used to render the text field. For more information, see the Embedding fonts section.
textField property - A reference to the button's internal text field.

Example

The following example creates a new TextFormat object and sets the button's text to a red, bold font:

        // Import the required component classes.
import fl.controls.Button;

// Create a new TextFormat object which will be used for the button's label.
var myTextFormat:TextFormat = new TextFormat();
myTextFormat.bold = true;
myTextFormat.color = 0xFF0000;

/* Create a new Button component instance and set the textFormat style to the
   TextFormat object created earlier. */
var myButton:Button = new Button();
myButton.label = "Click me";
myButton.move(10, 10);
myButton.setStyle("textFormat", myTextFormat);
addChild(myButton);
                      
    

Result

Download the source files for this example:

using_button_component section07 example1.zip (ZIP, 390K)

You can also set the text format for a disabled Button instance.

Example

The following example demonstrates how to set a text format on a disabled Button instance:

        // Import the required component classes.
import fl.controls.Button;

// Create a new TextFormat object which will be used when the button is enabled.
var enabledTextFormat:TextFormat = new TextFormat();
enabledTextFormat.bold = true;
enabledTextFormat.font = "Comic Sans MS";
enabledTextFormat.size = 14;

// Create a new TextFormat object which will be used when the button is disabled.
var disabledTextFormat:TextFormat = new TextFormat();
disabledTextFormat.color = 0xFF0000;
disabledTextFormat.font = "Comic Sans MS";
disabledTextFormat.italic = true;
disabledTextFormat.size = 12;

/* Create a new Button component instance, set the textFormat style, and add the 
   button to the display list. */
var enabledButton:Button = new Button();
enabledButton.label = "enabled = true";
enabledButton.setStyle("textFormat", enabledTextFormat);
enabledButton.setSize(140, 40);
enabledButton.move(10, 10);
addChild(enabledButton);

/* Create a new Button component instance, set the textFormat style, and add the 
   button to the display list. */
var disabledButton:Button = new Button();
disabledButton.enabled = false;
disabledButton.label = "enabled = false";
disabledButton.setStyle("disabledTextFormat", disabledTextFormat);
disabledButton.setSize(140, 40);
disabledButton.move(160, 10);
addChild(disabledButton);

    

Result

Download the source files for this example:

using_button_component section07 example2.zip (ZIP, 390K)

You can access a Button instance's internal textField object through the textField property.

Example

The following example demonstrates how to create a button with a multiline label using the textField property to access the Button instance's internal textField object:

        // Import the required component classes.
import fl.controls.Button;

// Create a new TextFormat object and set the align property to "center".
var myTextFormat:TextFormat = new TextFormat();
myTextFormat.align = TextFormatAlign.CENTER;

/* Create a new Button component instance, set the textFormat style to the
   TextFormat object created earlier, and add the button to the display list. */
var myButton:Button = new Button();
myButton.label = "The quick brown fox jumped over the lazy dog";
myButton.textField.wordWrap = true;
myButton.setStyle("textFormat", myTextFormat);
myButton.setSize(120, 60);
myButton.move(10, 10);
addChild(myButton);
                      
    

Result

Download the source files for this example:

using_button_component section07 example3.zip (ZIP, 390K)

Embedding fonts

Embedding fonts in a Flash document allows you to rotate text fields (such as a button label) without the font disappearing. They also enable you to apply advanced anti-aliasing which can increase a font's readability at smaller sizes (such as 10 points and lower). Using an embedded font also allows you to use fonts in your Flash documents that a user may not have installed on their machine.

Note: The biggest limitation to using embedded fonts is that they increase the file size or download size of your application.

Using embedded fonts with a Button instance is a multi-step process:

Create a new font symbol in the Flash document's library by selecting New Font from the Library panel's pop-up menu (upper-right corner of the Library panel).
Select the desired font face and properties in the Font Symbol Properties dialog box.
Set the linkage information for the Font symbol.
Create a new Font symbol instance using ActionScript.
Create a new TextFormat object and specify the name of the embedded font face.
Set the Button instance's embedFonts style to true.
Set the Button instance's textFormat style to the TextFormat object created in step 5.

For more information on embedding fonts, see the Embedding Fonts Quick Start article.

Tip: If you're using an embedded font with a Button instance, you can enable advanced anti-aliasing to improve a font's visual quality at smaller sizes.

Example

The following example creates two Button instances, enables embedded fonts for one of the instances, and rotates each of the buttons 90 degrees. This example requires a font in your Flash document's library with a linkage class of MyFont.

        // Import the required component classes.
import fl.controls.Button;

// Create a new Font object from the MyFont linkage in the library.
var myFont:Font = new MyFont();

/* Create a new TextFormat object and set the font name to the Font object's 
   fontName property. */
var myTextFormat:TextFormat = new TextFormat();
myTextFormat.font = myFont.fontName;

/* Create a new Button component instance, set the rotation to 90 degrees, 
   set the embedFonts style to true, set the textFormat style to the previously
   created TextFormat object, and add the button to the display list. */
var embedTrue:Button = new Button();
embedTrue.rotation = 90;
embedTrue.width = 120;
embedTrue.label = "embedFonts = true";
embedTrue.move(30, 10);
embedTrue.setStyle("embedFonts", true);
embedTrue.setStyle("textFormat", myTextFormat);
addChild(embedTrue);

/* Create a new Button component instance, set the rotation to 90 degrees, 
   set the embedFonts style to false (default), set the textFormat style to the 
   previously created TextFormat object, and add the button to the display list.
   Since the font is not embedded for this button instance, the button's label will
   not display any text after the button is rotated. */
var embedFalse:Button = new Button();
embedFalse.rotation = 90;
embedFalse.width = 120;
embedFalse.label = "embedFonts = false";
embedFalse.move(60, 10);
embedFalse.setStyle("embedFonts", false);
embedFalse.setStyle("textFormat", myTextFormat);
addChild(embedFalse);
                      
    

Result

Download the source files for this example:

using_button_component section08 example1.zip (ZIP, 410K)

Example

The following example demonstrates how to apply advanced anti-aliasing to a Button instance's embedded text field using the textField property: This example requires a font in your Flash document's library with a linkage class of MyFont.

        // Import the required component classes.
import fl.controls.Button;

// Create a new Font object from the MyFont linkage in the library.
var myFont:Font = new MyFont();

// Create a new TextFormat object and set the font name and font size.
var myTextFormat:TextFormat = new TextFormat();
myTextFormat.font = myFont.fontName;
myTextFormat.size = 8;

/* Create a new Button component instance, set the embedFonts style to true,
   set the nested text field's antiAliasType property to "normal", and add
   the button to the display list. */
var normalAliasButton:Button = new Button();
normalAliasButton.label = "AntiAliasType.NORMAL";
normalAliasButton.setStyle("embedFonts", true);
normalAliasButton.setStyle("textFormat", myTextFormat);
normalAliasButton.textField.antiAliasType = AntiAliasType.NORMAL;
normalAliasButton.width = 140;
normalAliasButton.move(10, 10);
addChild(normalAliasButton);

/* Create a new Button component instance, set the embedFonts style to true,
   set the nested text field's antiAliasType property to "advanced", and add
   the button to the display list. */
var advancedAliasButton:Button = new Button();
advancedAliasButton.label = "AntiAliasType.ADVANCED";
advancedAliasButton.setStyle("embedFonts", true);
advancedAliasButton.setStyle("textFormat", myTextFormat);
advancedAliasButton.textField.antiAliasType = AntiAliasType.ADVANCED;
advancedAliasButton.width = 140;
advancedAliasButton.move(160, 10);
addChild(advancedAliasButton);

    

Result

Download the source files for this example:

using_button_component section08 example2.zip (ZIP, 410K)

Creating emphasized buttons

When building applications, often you might want to add emphasis to a certain button. For example, if you had a simple feedback form with both a Submit and a Cancel button, you may want to add a border around the Submit button to make it a bit more visible to the user. Adding emphasis around a Button instance is easy using the Button component, as you only need to set the emphasized property to true.

When working with emphasized buttons, you'll often use the following properties and styles:

emphasized property - A Boolean value that indicates whether a border is drawn around the Button component when the button is in its up state.
emphasizedPadding style - The padding, in pixels, to be applied between the double lines that define the Button's perimeter.
emphasizedSkin style - The skin to be used when a button has emphasis.

Example

The following example creates an emphasized button.

        // Import the required component classes.
import fl.controls.Button;

/* Create a new Button component instance, set the emphasized property to 
   true, and add the button to the display list. */
var myButton:Button = new Button();
myButton.label = "emphasized = true";
myButton.emphasized = true;
myButton.width = 120;
myButton.move(10, 10);
addChild(myButton);
                      
    

Result

Download the source files for this example:

using_button_component section09 example1.zip (ZIP, 390K)

Example

The following example uses an instance of the Slider component to control the value of the Button instance's emphasizedPadding style. This example requires both a Button component and a Slider component in the library.

        // Import the required component classes.
import fl.controls.Button;
import fl.controls.Slider;
import fl.events.SliderEvent;

/* Create a new Button component instance, set the emphasized property to
   true, and add the button to the display list. */  
var myButton:Button = new Button();
myButton.label = "emphasized = true";
myButton.emphasized = true;
myButton.width = 120;
myButton.move(10, 10);
addChild(myButton);

/* Create a new Slider component instance, set the liveDragging property to
   true, and add the slider to the display list. */
var mySlider:Slider = new Slider();
mySlider.liveDragging = true;
mySlider.minimum = 0;
mySlider.maximum = 10;
mySlider.value = 2;
mySlider.tickInterval = 1;
mySlider.width = 120;
mySlider.move(10, 65);
mySlider.addEventListener(SliderEvent.CHANGE, changeHandler);
addChild(mySlider);

/* Handler function for the Slider component instance. This function sets the
   emphasizedPadding style to the value of the slider. */
function changeHandler(event:SliderEvent):void {
    myButton.setStyle("emphasizedPadding", event.value);
}
              
    

Tip: The emphasized border is calculated from the outer edge of the Button instance. If the Button instance is positioned at an x and y position of 20 pixels and has its emphasizedPadding style set to 5, the top left corner of the emphasized border would be at 15 pixels.

Result

Download the source files for this example:

using_button_component section09 example2.zip (ZIP, 430K)

Setting icons

When using a Button component, you optionally can specify an icon that appears next to the button's label. This allows you to easily add a check mark icon for a Submit button and a red X for a Cancel button, or you could put a product's logo next to its name.

When working with icons, you'll typically use the following styles:

icon - Name of the class to use as the icon when a toggle button is not selected and the mouse is not over the button.
disabledIcon - Name of the class to use as the icon when the button is disabled.
downIcon - Name of the class to use as the icon when the button is not selected and the mouse button is down.
overIcon - Name of the class to use as the icon when the button is not selected and the mouse is over the component.
upIcon - Name of the class to use as the icon when a toggle button is not selected and the mouse is not over the button.
selectedDisabledIcon - Name of the class to use as the icon when the button is selected and disabled.
selectedDownIcon - Name of the class to use as the icon when the button is selected and the mouse button is down.
selectedOverIcon - Name of the class to use as the icon when the button is selected and the mouse is over the component.
selectedUpIcon - Name of the class to use as the icon when the button is selected and the mouse button is up.

For more information on toggle buttons, see Creating toggle buttons.

Note: Setting a Button instance's icon style sets the default icon for each of the button states (up, down, over, disabled, etc.)

Example

The following example demonstrates how to set a Button instance's icon style. Note that only the icon style is set, and the icon propagates to the other icon styles automatically:

        // Import the required component classes.
import fl.controls.Button;

/* Create a new Button component instance, set the icon style to the BulletCheck 
   linkage in the library, and add the button to the display list. */
var myButton:Button = new Button();
myButton.label = "Confirm";
myButton.move(10, 10);
myButton.setStyle("icon", BulletCheck);
addChild(myButton);
                      
    

Result

Download the source files for this example:

using_button_component section10 example1.zip (ZIP, 390K)

You can use the labelPosition property to position the button's label relative to the icon.

Example

The following example demonstrates the four possible values for the labelPosition property, using the constants from the ButtonLabelPosition class (fl.controls.ButtonLabelPosition). This example requires a symbol in your Flash document's library with a linkage class of AdobeLogo.

        // Import the required component classes.
import fl.controls.Button;
import fl.controls.ButtonLabelPlacement;

/* Create a new Button component instance, set the icon style to the AdobeLogo
   linkage in the library, set the labelPlacement property to "left", and add 
   the button to the display list. */
var buttonLeft:Button = new Button();
buttonLeft.label = "ButtonLabelPlacement.LEFT";
buttonLeft.labelPlacement = ButtonLabelPlacement.LEFT;
buttonLeft.setStyle("icon", AdobeLogo);
buttonLeft.setSize(200, 60);
buttonLeft.move(10, 10);
addChild(buttonLeft);

/* Create a new Button component instance, set the icon style to the AdobeLogo
   linkage in the library, set the labelPlacement property to "right", and add 
   the button to the display list. */
var buttonRight:Button = new Button();
buttonRight.label = "ButtonLabelPlacement.RIGHT";
buttonRight.labelPlacement = ButtonLabelPlacement.RIGHT;
buttonRight.setStyle("icon", AdobeLogo);
buttonRight.setSize(200, 60);
buttonRight.move(10, 80);
addChild(buttonRight);

/* Create a new Button component instance, set the icon style to the AdobeLogo
   linkage in the library, set the labelPlacement property to "top", and add 
   the button to the display list. */
var buttonTop:Button = new Button();
buttonTop.label = "ButtonLabelPlacement.TOP";
buttonTop.labelPlacement = ButtonLabelPlacement.TOP;
buttonTop.setStyle("icon", AdobeLogo);
buttonTop.setSize(200, 60);
buttonTop.move(10, 150);
addChild(buttonTop);

/* Create a new Button component instance, set the icon style to the AdobeLogo
   linkage in the library, set the labelPlacement property to "bottom", and add 
   the button to the display list. */
var buttonBottom:Button = new Button();
buttonBottom.label = "ButtonLabelPlacement.BOTTOM";
buttonBottom.labelPlacement = ButtonLabelPlacement.BOTTOM;
buttonBottom.setStyle("icon", AdobeLogo);
buttonBottom.setSize(200, 60);
buttonBottom.move(10, 220);
addChild(buttonBottom);
                      
    

Result

Download the source files for this example:

using_button_component section10 example2.zip (ZIP, 390K)

You can specify the amount of space that appears between button's icon and its label by setting the textPadding property.

Example

The following example uses the Slider component to control the amount of text padding between the Button instance's icon and label. This example requires a symbol in the document's library with a linkage class of AdobeLogo, as well as a Button and a Slider component.

        // Import the required component classes.
import fl.controls.Button;
import fl.controls.Slider;
import fl.events.SliderEvent;

/* Create a new Button component instance, set the icon style to the AdobeLogo 
   linkage in the library, set the textPadding style to 5 pixels, and add the
   button to the display list. */
var myButton:Button = new Button();
myButton.label = "textPadding: 5";
myButton.setStyle("icon", AdobeLogo);
myButton.setStyle("textPadding", 5);
myButton.setSize(140, 40);
myButton.move(10, 10);
addChild(myButton);

/* Create a new Slider component instance, set the liveDragging property to true,
   and add the slider to the display list. This slider will be used to control the
   amount of text padding between the button instance's icon and label text. */
var mySlider:Slider = new Slider();
mySlider.minimum = 0;
mySlider.maximum = 15;
mySlider.value = 5;
mySlider.liveDragging = true;
mySlider.tickInterval = 1;
mySlider.width = myButton.width;
mySlider.move(10, 60);
mySlider.addEventListener(SliderEvent.CHANGE, changeHandler);
addChild(mySlider);

/* Handler function for the Slider component instance. This function sets the 
   button instance's textPadding style based on the current value of the slider. */
function changeHandler(event:SliderEvent):void {
    myButton.setStyle("textPadding", event.value);
    myButton.label = "textPadding: " + event.value;
}
                  
    

Result

Download the source files for this example:

using_button_component section10 example3.zip (ZIP, 431K)

You can specify a different icon for any of the Button's states by setting one or more of the Button's icon styles.

Example

The following example sets each of the icon styles for a Button instance:

        // Import the required component classes.
import fl.controls.Button;
import fl.controls.CheckBox;

/* Create a new Button component instance, set the various icon styles, and add 
   the button to the display list. */
var myButton:Button = new Button();
myButton.label = "icons";
myButton.enabled = true;
myButton.toggle = true;
myButton.setStyle("upIcon", BulletCheck);
myButton.setStyle("overIcon", BulletWarning);
myButton.setStyle("downIcon", BulletCritical);
myButton.setStyle("disabledIcon", IconCheck);
myButton.setStyle("selectedUpIcon", BulletCheckSelected);
myButton.setStyle("selectedOverIcon", BulletWarningSelected);
myButton.setStyle("selectedDownIcon", BulletCriticalSelected);
myButton.setStyle("selectedDisabledIcon", IconCheckSelected);
myButton.setSize(120, 40);
myButton.move(10, 10);
addChild(myButton);

/* Create a new CheckBox component instance, and add it to the display list. This button 
   will control whether or not the button instance is enabled. */
var enabledCheckBox:CheckBox = new CheckBox();
enabledCheckBox.label = "enabled";
enabledCheckBox.selected = myButton.enabled;
enabledCheckBox.move(10, 60);
enabledCheckBox.addEventListener(Event.CHANGE, enabledChangeHandler);
addChild(enabledCheckBox);

/* Create a new Button component instance, and add it to the display list. This button
   will control whether or not the button instance is toggled. */
var toggleCheckBox:CheckBox = new CheckBox();
toggleCheckBox.label = "toggle";
toggleCheckBox.selected = myButton.toggle;
toggleCheckBox.move(10, 80);
toggleCheckBox.addEventListener(Event.CHANGE, toggleChangeHandler);
addChild(toggleCheckBox);

/* Handler function for the enabled check box. This function gets called when the value
   of the enabledCheckBox is changed, and sets the button's enabled property based on 
   whether the enabledCheckBox instance is currently selected. */
function enabledChangeHandler(event:Event):void {
    myButton.enabled = enabledCheckBox.selected;
}

/* Handler function for the toggle check box. This function gets called when the value
   of the toggleCheckBox is changed, and sets the button's toggle property based on 
   whether the toggleCheckBox instance is currently selected. */
function toggleChangeHandler(event:Event):void {
    myButton.toggle = toggleCheckBox.selected;
}
               
    

Result

Download the source files for this example:

using_button_component section10 example4.zip (ZIP, 430K)

You can load an image from a remote location to use it for a button icon.

Example

The following example demonstrates how to load a remote image for a button icon using both a Loader instance and a UILoader component instance:

        // Import the required component classes.
import fl.controls.Button;
import fl.containers.UILoader;

// Create a new Loader instance, and load an external PNG image.
var logo:Loader = new Loader();
logo.contentLoaderInfo.addEventListener(Event.COMPLETE, completeHandler1);
logo.load(new URLRequest("http://www.helpexamples.com/flash/images/logo.png"));

// Create a new UILoader component instance and load an external PNG image.
var logo2:UILoader = new UILoader();
logo2.scaleContent = false;
logo2.addEventListener(Event.COMPLETE, completeHandler2);
logo2.load(new URLRequest("http://www.helpexamples.com/flash/images/logo.png"));

// Create a new Button component instance, and add it to the display list.
var myButton:Button = new Button();
myButton.label = "Loader";
myButton.move(10, 10);
myButton.setSize(140, 100);
addChild(myButton);

// Create a new Button component instance, and add it to the display list.
var secondButton:Button = new Button();
secondButton.label = "UILoader";
secondButton.move(160, 10);
secondButton.setSize(140, 100)
addChild(secondButton);

/* Handler function for the Loader instance. This function sets the icon 
   style for the myButton button instance, and updates the button's display
   using the validateNow() method. */
function completeHandler1(event:Event):void {
    myButton.setStyle("icon", logo);
    myButton.validateNow();
}

/* Handler function for the UILoader component instance. This function sets
   the icon style on the secondButton button instance, and updates the UILoader 
   and Button components display using the validateNow() method. */
function completeHandler2(event:Event):void {
    secondButton.setStyle("icon", logo2);
    logo2.validateNow();
    secondButton.validateNow();
}
                 
    

Result

Download the source files for this example:

using_button_component section10 example5.zip (ZIP, 410K)

Creating auto-repeating buttons

When building applications or games in Flash, often you might want a button to continually dispatch an event for as long as a user has the Button instance pressed. For example, if you were building a custom numeric stepper you would want the numbers to increase or decrease for as long as the user pressed the arrow keys. Similarly, if you were building a game, you may want the character to keep running for as long as the user clicks a button. The Button component has an autoRepeat property (inherited from the fl.controls.BaseButton class) which controls whether the buttonDown event (represented by the fl.events.ComponentEvent.BUTTON_DOWN constant) is dispatched more than one time when the user holds the mouse button down over the component.

Using the repeatDelay and repeatInterval styles (inherited from the fl.controls.LabelButton class), you can control the delay before the initial buttonDown event, and the frequency at which the event is dispatched while the button is pressed. The repeatDelay style determines the number of milliseconds (ms) to wait after the buttonDown event is first dispatched before sending a second buttonDown event (the default value is 500 ms). The repeatInterval style determines the interval, in milliseconds, between buttonDown events that are dispatched after the delay that is specified by the repeatDelay style (the default value is 35 ms). For example, if you set the repeatDelay style to 2000, and the repeatInterval style to 500, the first buttonDown event would be dispatched 2 seconds (2000 ms) after the user pressed the button, and every 500 ms for as long as the user held the button down.

Example

The following example creates a Button instance, sets its autoRepeat property to true, and adds event listeners for the buttonDown and click events:

        // Import the required component classes.
import fl.controls.Button;
import fl.controls.TextArea;
import fl.events.ComponentEvent;

var init:Boolean = false;

/* Create a new Button component instance, set its autoRepeat property to 
   true, and add it to the display list. */
var myButton:Button = new Button();
myButton.autoRepeat = true;
myButton.label = "autoRepeat = true";
myButton.width = 120;
myButton.move(10, 10);
myButton.addEventListener(ComponentEvent.BUTTON_DOWN, buttonDownHandler);
myButton.addEventListener(MouseEvent.CLICK, clickHandler);
addChild(myButton);

// Create a new TextArea component instance, and add it to the display list.
var debugTextArea:TextArea = new TextArea();
debugTextArea.setSize(200, 100);
debugTextArea.move(10, 40);
addChild(debugTextArea);

/* Handler function for the Button component instance. This function gets called
   whenever the button instance dispatches the buttonDown event. This function 
   checks the value of the init variable, and if true clears any existing text from
   the text area, next a string is appended to the debugTextArea instance, and 
   scrolls the text area to the last line. */ 
function buttonDownHandler(event:ComponentEvent):void {
    if (init) {
        debugTextArea.text = "";
        init = false;
    }
    debugTextArea.appendText("[" + getTimer() + "ms] " + event.type + "\n");
    debugTextArea.verticalScrollPosition = debugTextArea.maxVerticalScrollPosition;
}

/* Handler function for the Button component instance. This function gets called
   whenever the button instance dispatches the click event. This function appends
   a string to the debugTextArea instance, and scrolls the text area to the last 
   line. Finally, the init function is reset to true. */
function clickHandler(event:MouseEvent):void {
    debugTextArea.appendText("[" + getTimer() + "ms] " + event.type + "\n");
    debugTextArea.verticalScrollPosition = debugTextArea.maxVerticalScrollPosition;
    init = true;
}
              
    

Result

Download the source files for this example:

using_button_component section11 example1.zip (ZIP, 472K)

Creating toggle buttons

A toggle button is a button that allows for two states, selected and unselected, similar to the behavior of the CheckBox component. This allows you to build applications that allow two different states for a button. This can be very useful if you had a data grid with several columns and wanted an easy way to allow users to toggle the visibility of each column.

When working with toggleable buttons, you'll often use the following properties and styles:

toggle property - A Boolean value that indicates whether a button can be toggled.
selected property - A Boolean value that indicates whether a toggle button is toggled in the on or off position.
selectedUpIcon style - Name of the class to use as the icon when the button is selected and the mouse button is up.
selectedOverIcon style - Name of the class to use as the icon when the button is selected and the mouse is over the component.
selectedDownIcon style - Name of the class to use as the icon when the button is selected and the mouse button is down.
selectedDisabledIcon style - Name of the class to use as the icon when the button is selected and disabled.
selectedUpSkin style - Name of the class to use as the skin for the background and border when a toggle button is selected and the mouse is not over the component.
selectedOverSkin style - Name of the class to use as the skin for the background and border when a toggle button is selected and the mouse is over the component.
selectedDownSkin style - Name of the class to use as the skin for the background and border when a toggle button is selected and the mouse button is down.
selectedDisabledSkin style - Name of the class to use as the skin for the background and border when a toggle button is selected and disabled.

Example

The following example creates a Button instance, sets its toggle property to true, and adds event listeners for the change and click events:

        // Import the required component classes.
import fl.controls.Button;
import fl.controls.TextArea;
import fl.events.ComponentEvent;

/* Create a new Button component instance, set the toggle property to true, and 
   add it to the display list. */
var myButton:Button = new Button();
myButton.toggle = true;
myButton.label = "toggle = true, selected = " + myButton.selected;
myButton.width = 200;
myButton.move(10, 10);
myButton.addEventListener(Event.CHANGE, changeHandler);
myButton.addEventListener(MouseEvent.CLICK, clickHandler);
addChild(myButton);

// Create a TextArea component instance, and add it to the display list.
var debugTextArea:TextArea = new TextArea();
debugTextArea.setSize(200, 100);
debugTextArea.move(10, 40);
addChild(debugTextArea);

/* Handler function for the Button component instance. This function sets the
   button's label to the value of the button's selected property, and updates 
   the text area instance with the type of event that was dispatched. */
function changeHandler(event:Event):void {
    myButton.label = "toggle = true, selected = " + myButton.selected;
    debugTextArea.appendText("[" + getTimer() + "ms] " + event.type + "\n");
    debugTextArea.verticalScrollPosition = debugTextArea.maxVerticalScrollPosition;
}

/* Handler function for the Button component instance. This function sets the
   button's label to the value of the button's selected property, and updates 
   the text area instance with the type of event that was dispatched. */
function clickHandler(event:MouseEvent):void {
    myButton.label = "toggle = true, selected = " + myButton.selected;
    debugTextArea.appendText("[" + getTimer() + "ms] " + event.type + "\n");
    debugTextArea.verticalScrollPosition = debugTextArea.maxVerticalScrollPosition;
}
            
    

Result

Download the source files for this example:

using_button_component section12 example1.zip (ZIP, 472K)

Example

The following example creates two toggleable buttons, flashButton and flexButton, and sets the Button instance's emphasized property based on whether the button is currently selected or not:

        // Import the required component classes.
import fl.controls.Button;

/* Create a new Button component instance, set the button's toggle, selected, 
   and emphasized properties, and add it to the display list. */
var flashButton:Button = new Button();
flashButton.label = "Flash";
flashButton.toggle = true;
flashButton.selected = true;
flashButton.emphasized = flashButton.selected;
flashButton.move(10, 10);
flashButton.addEventListener(MouseEvent.CLICK, clickHandler);
addChild(flashButton);

/* Create a new Button component instance, set the button's toggle, selected, 
   and emphasized properties, and add it to the display list. */
var flexButton:Button = new Button();
flexButton.label = "Flex";
flexButton.toggle = true;
flexButton.selected = false;
flexButton.emphasized = flexButton.selected;
flexButton.move(120, 10);
flexButton.addEventListener(MouseEvent.CLICK, clickHandler);
addChild(flexButton);

/* Handler function for the flashButton and flexButton instances. This function
   sets the emphasized properties for the target button based on the value of the 
   target button's selected property. */
function clickHandler(event:MouseEvent):void {
    var btn:Button = event.currentTarget as Button;
    btn.emphasized = btn.selected;
}
                
    

Result

Download the source files for this example:

using_button_component section12 example2.zip (ZIP, 390K)

For more information

For more information about this topic, see the "Button class" in ActionScript 3.0 Reference for the Adobe Flash Platform, and "Using the Button" in Using ActionScript 3.0 Components.

Related Flash Quick Starts

Using the Button component

by Peter deHaan

Content

Modified

Page tools

Requirements

User level

Required products

Creating an instance of the Button component using ActionScript

Example

Setting a Button component's label

Example

Resizing and positioning buttons

Example

Example

Detecting when a button is pressed

Example

Example

Enabling and disabling Button instances

Example

Setting button styles

Example

Setting text formats

Example

Example

Example

Embedding fonts

Example

Example

Creating emphasized buttons

Example

Example

Setting icons

Example

Example

Example

Example

Example

Creating auto-repeating buttons

Example

Creating toggle buttons

Example

Example

For more information

More Like This