# Labeling a form control by setting its accessible name

ID: FLASH25

Technology: flash

Type: Technique

## When to Use

- Adobe Flash Professional version MX and higher
- Adobe Flex

## Description

The objective of this technique is to provide an accessible name to the built in form components provided by Flash. Some components, such as radio buttons, checkboxes and buttons, have their own `label` property. For other components, the developer needs to specify the component's label text as accessible name. This can be either be achieved through the Accessibility panel (for components placed on the stage during authoring) or through scripting (for components that are dynamically created at runtime).

ActionScript 2

In ActionScript 2 the accessible name needs to be set on a component's `_accProps` property. This property must be an object. If the property has not been set yet, the developer needs to create a custom object and assign it to the `_accProps` property. The object itself can have several accessibility related properties, one of them being `_accProps.name`, which specifies the accessible name. When an `_accProps` property is updated, the developer must call Accessibility.UpdateProperties() for the changes to take effect. Before calling Accessibility.UpdateProperties(), it is recommended to check the System.capabilities.hasAccessibility flag. this will prevent an error on environments that do not support MSAA.

ActionScript 2 provides the following accessible components:

- SimpleButton
- CheckBox
- RadioButton
- Label
- TextInput
- TextArea
- ComboBox
- ListBox
- Window
- Alert
- DataGrid

ActionScript 3

In ActionScript 3 the accessible name needs to be set on a component's `accessibilityProperties` property. This property must be an instance of `flash.accessibility.AccessibilityProperties`. If the property has not been set yet, the developer needs to create the a new `AccessibilityProperties` instance and assign it to the `accessibilityProperties` property. The object itself can have several accessibility related properties, one of them being `accessibilityProperties.name` which specifies the accessible name. When an `accessibilityProperties property` is updated, the developer must call flash.accessibility.Accessibility.UpdateProperties() for the changes to take effect. Before calling Accessibility.UpdateProperties(), it is recommended to check the flash.system.capabilities.hasAccessibility flag. this will prevent an error on environments that do not support MSAA.

ActionScript 3 provides the following accessible components.

- Button
- CheckBox
- ComboBox
- List
- RadioButton
- TileList

## Examples

### Setting a component's accessible name using the Accessibility panel

To add and label a component control, follow these steps:

1. From the 'Components' panel, drag the component on to the stage, or use scripting to create a new instance.
2. With the newly created component instance selected, enter its label text in the Accessibility Panel's Name field.

### Setting the accessible name through ActionScript 2.0

The code example below shows how a ListBox component is created and assigned an accessible name.

    mx.accessibility.ListAccImpl.enableAccessibility();

    this.createClassObject(mx.controls.List, "my_list", 1);
    my_list.addItem({label: "R. Davis", data: 1});
    my_list.addItem({label: "V. Mann", data: 2});
    my_list.addItem({label: "L. Heart", data: 3});
    my_list.addItem({label: "P. Hill", data: dt4});
    my_list.addItem({label: "D. Gribble", data: 5});
    my_list.move(10, 10);

    if (System.capabilities.hasAccessibility) {
      my_list._accProps = new Object();
      my_list._accProps.name = "Staff Members";
      Accessibility.updateProperties();
    }

This result can be viewed in the working version of Setting the accessible name through ActionScript 2.0. The source of Setting the accessible name through ActionScript 2.0 is available.

### Setting the accessible name through ActionScript 3.0

The code example below shows how a ListBox component is created and assigned an accessible name.

    import fl.controls.List;
    import fl.accessibility.ListAccImpl;
    import flash.system.Capabilities;
    import flash.accessibility.*;

    ListAccImpl.enableAccessibility();
    var my_list:List = new List();
    my_list.addItem({label:"R. Davis", data:1});
    my_list.addItem({label:"V. Mann", data:2});
    my_list.addItem({label:"L. Heart", data:3});
    my_list.addItem({label:"P. Hill", data:4});
    my_list.addItem({label:"D. Gribble", data:5});
    my_list.x = my_list.y = 10;

    if (Capabilities.hasAccessibility) {
      var accProps:AccessibilityProperties = new AccessibilityProperties();
      accProps.name = "Staff Members";
      my_list.accessibilityProperties = accProps;
      Accessibility.updateProperties();
    }
    addChild(my_list);

This result can be viewed in the working version of Setting the accessible name through ActionScript 3.0. The source of Setting the accessible name through ActionScript 3.0 is available.

## Tests

### Procedure

For Flash movies that contain form components, confirm that either:

1. The selected component's label text is specified in the Accessibility Panel's "name" field.
2. In ActionScript 2.0: Scripting is used to dynamically set the component's `_accProps.name` property
3. In ActionScript 3.0: Scripting is used to dynamically set the component's `accessibilityProperties.name` property

### Expected Results

One of the above is true

## Related Techniques

- G94