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

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.

---