Apache Flex 4.16.1 API Reference | All Packages | All Classes | Index | Frames No Frames |
DataGridAccImpl

Package | spark.accessibility
Class | public class DataGridAccImpl
Inheritance | DataGridAccImpl ListBaseAccImpl AccImpl flash.accessibility.AccessibilityImplementation

Language Version : | ActionScript 3.0

Product Version : | Flex 4

Runtime Versions : | Flash Player 10, AIR 1.5

This is the accessibility implementation class for spark.components.DataGrid.

When a Spark DataGrid is created, its `focusOwner` child object's `accessibilityImplementation` property is set to an instance of this class. The accessibility implementation is placed on this placeholder `focusOwner` object so that the DataGrid's accessibility implementation does not obscure the item editor's accessibility implementation. The DataGrid component itself does not have an accessibility implementation. This step is required as the current version of the Flash Player does not support multiple levels of MSAA objects. Item editors can be any component and need to be full MSAA objects. The item editor objects appear as sibling objects to the DataGrid in the MSAA tree structure. The accessibility implementation for each item editor is thus handled by the accessibility implementation associated with that component, such as `CheckBoxAccImpl` for a CheckBox. The item editor's accessibility implementation only exists when there is an item editor session, and there can only be one item editor active at one time; thus, there is one or zero instances of the item editor accessibility implementation active at any time.

Two methods are overwritten in the `DataGrid` class to properly handle focus among `DataGrid` and the `focusOwner` child of `DataGrid`. The `GridItemRenderer` class turns accessibility off for item renderers, as by default these will be handled as simple objects under the DataGrid accessibility implementation. While this limits how non-item editor components such as CheckBox, Panel, etc. can be used in DataGrids, it prevents these items from showing up as siblings to the DataGrid in the MSAA tree. Allowing all grid item renderers to show up as siblings to the DataGrid in the MSAA tree would be very confusing to users of screen readers as there would be no context or relationship. Developers can of course override this default behavior if desired to display these renderers with accessibility enabled.

The Flash Player then uses this class to allow MSAA clients such as screen readers to see and manipulate the DataGrid. See the mx.accessibility.AccImpl and flash.accessibility.AccessibilityImplementation classes for background information about accessibility implementation classes and MSAA.

The `DataGridAccImpl` extends the `ListBaseAccImpl` (as the `DataGrid` extends the `DataGridBase` which extends the `ListBase` class). The Spark `DataGridAccImpl` is most similar to the MX `AdvancedDataGridAccImpl` as the AdvancedDataGrid also supports single cell and row selection which the MX DataGrid did not.

Children

The MSAA children of a DataGrid are, in this order

- One child for each visible header cell, starting from the left. "Visible" here means not hidden by the developer (`column.visible=false`). The header for a column that is not marked invisible by the developer but which is scrolled off screen is considered "visible" here.
- In row selection mode, one child for each data row in the grid; OR
- In cell selection mode, one child for each cell in the grid, excluding cells in invisible (as just described) columns.

The number of children depends on the number of rows and columns in the `dataProvider`, not on the number of items currently displayed on screen.

Note that, unlike for `ListBase`, DataGrid child count does not reflect the number of data rows in the control. Assistive technology should therefore avoid using `AccChildCount` as a means of reporting row count.

This property is not handled by the DataGrid accessibility implementation for item editors as item editors manage themselves.

Role

The MSAA Role of a DataGrid is `ROLE_SYSTEM_LIST`.

The Role of each data row or cell in the DataGrid is `ROLE_SYSTEM_LISTITEM`.

The Role of each header cell in the DataGrid is `ROLE_SYSTEM_COLUMNHEADER`.

This property is not handled by the DataGrid accessibility implementation for item editors as item editors manage themselves.

Name

The MSAA Name of a DataGrid is, by default, an empty string. When wrapped in a `FormItem` element, the Name is the FormItem's label. To override this behavior, set the DataGrids's `accessibilityName` property. Setting the `accessibilityName` property will also apply the accessible name to the `focusOwner` child object of the DataGrid which represents the DataGrid.

The Name of each data row (when in row selection mode) is a string of the form "_column1Name_: _column1Value_, _column2Name_: _column2Value_, ..., _columnNName_: _columnNValue_, Row _m_ of _n_." Columns are separated from each other by commas, and column names and values are separated from each other by colons. Columns hidden by the developer are omitted entirely from the Name string. Example Name string: "Contact Name: Doug, Contact Phone: 555-1212, Contact Zip: 12345, row 3 of 7."

Note that "Row _m_ of _n_" is localized.

The Name of each data cell in column 1 (when in cell selection mode) is a string of the form "_columnName_: _columnValue_, Row _m_ of _n_." Example: "Contact Phone: 555-1212, Row 2 of 5." Subsequent columns use the same format but omit the "Row _m_ of _n_" portion.

Note that "Row _m_ of _n_" is localized.

The Name string for a column header (in cell or row selection mode) is normally the text of the header. Example: "Contact Phone." If the grid is sorted by the corresponding column however, the string "sorted" or "sorted descending" is appended to the column name, to indicate the sort and its direction. Example: "Contact Name sorted." For a multicolumn sort, level strings are also appended indicating each column's level in the set of sorting columns. For example, if a grid is sorted first by column 3 and then by column 2, and column 2 is sorted in descending order, column 3's name will end with "Sorted Level 1," and column 2's name will end with "Sorted descending level 2." The strings for indicating ascending sort, descending sort, and sort level are localized.

When the Name of the DataGrid or one of its items changes, a DataGrid dispatches the MSAA event `EVENT_OBJECT_NAMECHANGE` with the proper childID for a row or cell or 0 for itself.

If an accessibility name is not set for an item editor, one is set based on the column header name for the cell.

Description

The MSAA Description of a DataGrid is, by default, an empty string, but you can set the DataGrid's `accessibilityDescription` property.

The Description of each row, cell, or header is the empty string and can not be set by an AccImpl.

This property is not handled by the DataGrid accessibility implementation for item editors as item editors manage themselves.

State

The MSAA State of a DataGrid is a combination of:

- `STATE_SYSTEM_UNAVAILABLE` (when `enabled` is `false`)
- `STATE_SYSTEM_FOCUSABLE` (when `enabled` is `true`)
- `STATE_SYSTEM_FOCUSED` (when `enabled` is `true` and the DataGrid has focus)
- `STATE_SYSTEM_MULTISELECTABLE` (when `allowMultipleSelection` is true)

The State of a data row or cell is a combination of:

- `STATE_SYSTEM_FOCUSABLE`
- `STATE_SYSTEM_FOCUSED` (when focused)
- `STATE_SYSTEM_OFFSCREEN` (when the row or cell has scrolled offscreen)
- `STATE_SYSTEM_SELECTABLE`
- `STATE_SYSTEM_SELECTED` (when it is selected)

The State of a header cell is `STATE_SYSTEM_NORMAL`, since header cells may not receive focus or be selected. As currently implemented, header cells may not report `STATE_SYSTEM_OFFSCREEN` even if the grid itself is moved such that its headers are offscreen.

When the State of the DataGrid or one of its items changes, a DataGrid dispatches the MSAA event `EVENT_OBJECT_STATECHANGE` with the proper childID for the row or cell or 0 for itself.

This property is not handled by the DataGrid accessibility implementation for item editors as item editors manage themselves.

Value

DataGrids and their children (rows, cells, and headers) do not have MSAA Values.

Location

The MSAA Location of a DataGrid or a row, data cell, or header cell within it is its bounding rectangle. The Location of an item that is currently not displayed on screen is undefined.

This property is not handled by the DataGrid accessibility implementation for item editors as item editors manage themselves.

Default Action

A DataGrid does not have an MSAA DefaultAction. The MSAA DefaultAction for a row or cell is "Double Click" and for a header cell is "Click," and the corresponding localized string will be returned when the default action string is requested.

Performing the default action on a data row or cell will cause it to be focused and selected and may cause other behavior depending on cell/row type. Performing the default action on a header will cause the grid to be sorted by that column. Repeated default actions on the header will toggle the sort order between ascending and descending. At this writing, there is no way via the AccImpl to arrange for a multilevel sort on several columns at once.

This property is not handled by the DataGrid accessibility implementation for item editors as item editors manage themselves.

Focus

When there is no specific item (row or cell depending on selection mode) in focus within the grid, Focus returns 0 indicating that the grid itself has focus. This should only happen when the grid contains no data.

When a row (row selection mode) or cell (cell selection mode) has focus, Focus returns the childID of the focused item.

When a DataGrid receives focus, it dispatches the MSAA event `EVENT_OBJECT_FOCUS`. This event is also dispatched when focus moves among rows or cells within the grid.

A focus change event is fired on the item editor when it starts/appears. A focus change event is fired on the DataGrid when the item editor is saved or closed.

Selection

A DataGrid allows either a single row or cell or multiple rows or cells to be selected, depending on the `allowMultipleSelection` property. Selection returns an array of the integer childIDs of the selected items.

When an item is selected exclusively, it dispatches MSAA event `EVENT_OBJECT_SELECTION`. When a cell (cell selection mode) or row (row selection mode) is added to the current set of selections, the dispatched event is `EVENT_OBJECT_SELECTIONADD`. Similarly, if an item (cell or row) is removed from selection, the dispatched event is `EVENT_OBJECT_SELECTIONREMOVE`. If all selections are cleared (regardless of how many items were selected) or a select-all or select-region action is performed, the dispatched event is `EVENT_OBJECT_SELECTIONWITHIN`. Any selection operation not matching one of those listed above will dispatch `EVENT_OBJECT_SELECTION`.

This property is not handled by the DataGrid accessibility implementation for item editors as item editors manage themselves.

Select

The `accSelect` method implements requests made via MSAA for changes in selection and/or focus within the DataGrid. The AccImpl for the DataGrid supports the setting of focus to a DataGrid itself or to a data item or set of items (row or cell depending on selection mode) within it. Supported actions include setting focus, exclusively selecting one item, and adding and removing an item or set of items from selection, all as defined in the Microsoft Active Accessibility specification. At this writing, attempting to use `accSelect` to extend an already-selected multi-cell region in cell multiselection mode to include more rows and columns at once may yield different results than doing the same action with a mouse.

This property is not handled by the DataGrid accessibility implementation for item editors as item editors manage themselves.

Protected Properties
Hide Inherited Protected Properties
Show Inherited Protected Properties

| Property | Defined By
--- | --- | ---
|  | eventsToHandle : Array [read-only] All subclasses must override this function by returning an array of strings of the events to listen for. | AccImpl
|  | master : UIComponent A reference to the UIComponent instance that this AccImpl instance is making accessible. | AccImpl
|  | role : uint Accessibility role of the component being made accessible. | AccImpl

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | DataGridAccImpl(master:UIComponent) Constructor. | DataGridAccImpl
|  | enableAccessibility():void [static] Enables accessibility in the DataGrid class. | DataGridAccImpl
|  | getFormName(component:UIComponent):String [static] Method for supporting Form Accessibility. | AccImpl
|  | isAncestorDisabled(component:UIComponent):Boolean [static] Returns true if an ancestor of the component has enabled set to false. | AccImpl

Protected Methods
Show Inherited Protected Methods
Show Inherited Protected Methods

| Method | Defined By
--- | --- | ---
|  | eventHandler(event:Event):void Generic event handler. | AccImpl
|  | getName(childID:uint):String Returns the name of the accessible component. | AccImpl
|  | getState(childID:uint):uint Utility method to determine state of the accessible component. | AccImpl

Constructor Detail

DataGridAccImpl | () | Constructor

`public function DataGridAccImpl(master:UIComponent)`

Language Version : | ActionScript 3.0

Product Version : | Flex 4

Runtime Versions : | Flash Player 10, AIR 1.5

Constructor.

Parameters

| `master:UIComponent` — The UIComponent instance that this AccImpl instance is making accessible.

Method Detail

enableAccessibility | () | method

`public static function enableAccessibility():void`

Language Version : | ActionScript 3.0

Product Version : | Flex 4

Runtime Versions : | Flash Player 10, AIR 1.5

Enables accessibility in the DataGrid class.

This method is called by application startup code that is autogenerated by the MXML compiler. Afterwards, when instances of DataGrid are initialized, their `accessibilityImplementation` property will be set to an instance of this class.

Wed Nov 15 2017, 09:50 AM +01:00