IAccessibleTable

by 2 contributors:

This interface gives access to a two-dimensional table.
1.0
28
Introduced
Gecko 1.9
Inherits from: IUnknown Last changed in Gecko 1.9 (Firefox 3)

Typically all accessible objects that represent cells or cell-clusters of a table will be at the same time children of the table. In this case IAccessible2.indexInParent() will return the child index which then can be used when calling rowIndex() and columnIndex(). However, in some cases that kind of implementation will not be possible. When the table cells are not direct children of a table, the object representing the cell can define a "table-cell-index" object attribute identifying the 0 based table cell index. This object attribute is obtained by parsing the attribute string returned by IAccessible2.attributes(). The "table-cell-index" attribute can be used just like a child index of the typical case. ATs should first test for the presence of the "table-cell-index" attribute and if it is not present then IAccessible2.indexInParent() can be used as in the typical case where cells are direct children of the table. The range of valid coordinates for this interface are implementation dependent. However, that range includes at least the intervals from the from the first row or column with the index 0 up to the last (but not including) used row or column as returned by nRows() and nColumns().

Method overview

[propget] HRESULT accessibleAt([in] long row, [in] long column, [out] IUnknown accessible );
[propget] HRESULT caption([out] IUnknown accessible );
[propget] HRESULT childIndex([in] long rowIndex, [in] long columnIndex, [out] long cellIndex );
[propget] HRESULT columnDescription([in] long column, [out] BSTR description );
[propget] HRESULT columnExtentAt([in] long row, [in] long column, [out] long nColumnsSpanned );
[propget] HRESULT columnHeader([out] IAccessibleTable accessibleTable, [out] long startingRowIndex );
[propget] HRESULT columnIndex([in] long cellIndex, [out] long columnIndex );
[propget] HRESULT isColumnSelected([in] long column, [out] boolean isSelected );
[propget] HRESULT isRowSelected([in] long row, [out] boolean isSelected );
[propget] HRESULT isSelected([in] long row, [in] long column, [out] boolean isSelected );
[propget] HRESULT modelChange([out] IA2TableModelChange modelChange );
[propget] HRESULT nColumns([out] long columnCount );
[propget] HRESULT nRows([out] long rowCount );
[propget] HRESULT nSelectedChildren([out] long cellCount );
[propget] HRESULT nSelectedColumns([out] long columnCount );
[propget] HRESULT nSelectedRows([out] long rowCount );
[propget] HRESULT rowColumnExtentsAtIndex([in] long index, [out] long row, [out] long column, [out] long rowExtents, [out] long columnExtents, [out] boolean isSelected );
[propget] HRESULT rowDescription([in] long row, [out] BSTR description );
[propget] HRESULT rowExtentAt([in] long row, [in] long column, [out] long nRowsSpanned );
[propget] HRESULT rowHeader([out] IAccessibleTable accessibleTable, [out] long startingColumnIndex );
[propget] HRESULT rowIndex([in] long cellIndex, [out] long rowIndex );
HRESULT selectColumn([in] long column );
[propget] HRESULT selectedChildren([in] long maxChildren, [out, size_is(,maxChildren), length_is(, nChildren)] long children, [out] long nChildren );
[propget] HRESULT selectedColumns([in] long maxColumns, [out, size_is(,maxColumns), length_is(, nColumns)] long columns, [out] long nColumns );
[propget] HRESULT selectedRows([in] long maxRows, [out, size_is(,maxRows), length_is(, nRows)] long rows, [out] long nRows );
HRESULT selectRow([in] long row );
[propget] HRESULT summary([out] IUnknown accessible );
HRESULT unselectColumn([in] long column );
HRESULT unselectRow([in] long row );

Methods

accessibleAt()

Returns the accessible object at the specified row and column in the table. This object could be an IAccessible or an IAccessible2.

[propget] HRESULT accessibleAt(
  [in] long row,
  [in] long column,
  [out] IUnknown accessible 
);
Parameters
row
The 0 based row index for which to retrieve the cell.
column
The 0 based column index for which to retrieve the cell.
accessible
If both row and column index are valid then the corresponding accessible object is returned that represents the requested cell regardless of whether the cell is currently visible (on the screen).
Return value

E_INVALIDARG if bad [in] passed, [out] value is null. S_OK.

caption()

Returns the caption for the table. The returned object could be an IAccessible or an IAccessible2.

[propget] HRESULT caption(
  [out] IUnknown accessible 
);
Parameters
accessible
If the table has a caption then a reference to it is returned, else a null pointer is returned.
Return value

S_FALSE if there is nothing to return, [out] value is null. S_OK.

childIndex()

Translates the given row and column indexes into the corresponding cell index.

[propget] HRESULT childIndex(
  [in] long rowIndex,
  [in] long columnIndex,
  [out] long cellIndex 
);
Parameters
rowIndex
0 based row index for the cell.
columnIndex
0 based column index for the cell.
cellIndex
Returns the 0 based index of the cell at the specified row and column indexes.
Return value

E_INVALIDARG if bad [in] passed, [out] value is 0. S_OK.

columnDescription()

Returns the description text of the specified column in the table.

[propget] HRESULT columnDescription(
  [in] long column,
  [out] BSTR description 
);
Parameters
column
The 0 based index of the column for which to retrieve the description.
description
Returns the description text of the specified column in the table if such a description exists. Otherwise a null pointer is returned.
Return value

E_INVALIDARG if bad [in] passed, [out] value is null. S_FALSE if there is nothing to return, [out] value is null. S_OK.

columnExtentAt()

Returns the number of columns occupied by the accessible object at the specified row and column in the table. The result is greater than 1 if the specified cell spans multiple columns.

[propget] HRESULT columnExtentAt(
  [in] long row,
  [in] long column,
  [out] long nColumnsSpanned 
);
Parameters
row
0 based row index of the accessible for which to return the column extent.
column
0 based column index of the accessible for which to return the column extent.
nColumnsSpanned
Returns the 1 based column extent of the specified cell.
Return value

E_INVALIDARG if bad [in] passed, [out] value is 0. S_OK.

columnHeader()

Returns the column headers as an IAccessibleTable object. Content and size of the returned table are implementation dependent.

[propget] HRESULT columnHeader(
  [out] IAccessibleTable accessibleTable,
  [out] long startingRowIndex 
);
Parameters
accessibleTable
The column header.
startingRowIndex
The 0 based row index where the header starts, usually 0.
Return value

S_FALSE if there is no header, [out] values are null and 0 respectively. S_OK.

columnIndex()

Translates the given cell index into the corresponding column index.

[propget] HRESULT columnIndex(
  [in] long cellIndex,
  [out] long columnIndex 
);
Parameters
cellIndex
0 based index of the cell in the parent or closest ancestor table. Typically this is the value returned from IAccessible2.indexInParent(), but in the case where the table cells are not direct children of the table this is the cell index specified by the "table-cell-index" object attribute obtained from parsing the attributes string returned by calling IAccessible2.attributes() on the cell object.
columnIndex
Returns the 0 based column index of the cell of the specified child or the index of the first column if the child spans multiple columns.
Return value

E_INVALIDARG if bad [in] passed, [out] value is 0. S_OK.

isColumnSelected()

Returns a boolean value indicating whether the specified column is completely selected.

[propget] HRESULT isColumnSelected(
  [in] long column,
  [out] boolean isSelected 
);
Parameters
column
0 based index of the column for which to determine whether it is selected.
isSelected
Returns true if the specified column is selected completely and false otherwise.
Return value

E_INVALIDARG if bad [in] passed, [out] value is false. S_OK.

isRowSelected()

Returns a boolean value indicating whether the specified row is completely selected.

[propget] HRESULT isRowSelected(
  [in] long row,
  [out] boolean isSelected 
);
Parameters
row
0 based index of the row for which to determine whether it is selected.
isSelected
Returns true if the specified row is selected completely and false otherwise.
Return value

E_INVALIDARG if bad [in] passed, [out] value is false. S_OK.

isSelected()

Returns a boolean value indicating whether the specified cell is selected.

[propget] HRESULT isSelected(
  [in] long row,
  [in] long column,
  [out] boolean isSelected 
);
Parameters
row
0 based index of the row for the cell to determine whether it is selected.
column
0 based index of the column for the cell to determine whether it is selected.
isSelected
Returns true if the specified cell is selected and false otherwise.
Return value

E_INVALIDARG if bad [in] passed, [out] value is false. S_OK.

modelChange()

Returns the type and extents describing how a table changed. Provided for use by the IA2_EVENT_TABLE_MODEL_CHANGED event handler. This data is only guaranteed to be valid while the thread notifying the event continues. Once the handler has returned, the validity of the data depends on how the server manages the life cycle of its objects. Also, note that the server may have different life cycle management strategies for controls depending on whether or not a control manages its children. Lists, trees, and tables can have a large number of children and thus it's possible that the child objects for those controls would only be created as needed. Servers should document their life cycle strategy as this will be of interest to assistive technology or script engines accessing data out of process or from other threads. Servers only need to save the most recent row and column values associated with the change and a scope of the entire application is adequate.

[propget] HRESULT modelChange(
  [out] IA2TableModelChange modelChange 
);
Parameters
modelChange
A struct of (type(insert, delete, update), firstRow, lastRow, firstColumn, lastColumn).
Return value

S_FALSE if there is nothing to return, [out] value is null. S_OK.

nColumns()

Returns the total number of columns in table.

[propget] HRESULT nColumns(
  [out] long columnCount 
);
Parameters
columnCount
Number of columns in table (including columns outside the current viewport)
Return value

S_OK.

nRows()

Returns the total number of rows in table.

[propget] HRESULT nRows(
  [out] long rowCount 
);
Parameters
rowCount
Number of rows in table (including rows outside the current viewport)
Return value

S_OK.

nSelectedChildren()

Returns the total number of selected cells.

[propget] HRESULT nSelectedChildren(
  [out] long cellCount 
);
Parameters
cellCount
Number of cells currently selected.
Return value

S_OK.

nSelectedColumns()

Returns the total number of selected columns.

[propget] HRESULT nSelectedColumns(
  [out] long columnCount 
);
Parameters
columnCount
Number of columns currently selected.
Return value

S_OK.

nSelectedRows()

Returns the total number of selected rows.

[propget] HRESULT nSelectedRows(
  [out] long rowCount 
);
Parameters
rowCount
Number of rows currently selected.
Return value

S_OK.

rowColumnExtentsAtIndex()

Given a cell index, gets the row and column indexes and extents of a cell and whether or not it is selected. This is a convenience function. It is not mandatory to implement it.

[propget] HRESULT rowColumnExtentsAtIndex(
  [in] long index,
  [out] long row,
  [out] long column,
  [out] long rowExtents,
  [out] long columnExtents,
  [out] boolean isSelected 
);
Parameters
index
0 based index of this cell in the table.
row
0 based row index.
column
0 based column index.
rowExtents
Number of cells spanned by this cell in this row.
columnExtents
Number of cells spanned by this cell in this column.
isSelected
Indicates if the specified cell is selected.
Return value

E_INVALIDARG if bad [in] passed, [out] values are 0s and false respectively. S_OK.

rowDescription()

Returns the description text of the specified row in the table.

[propget] HRESULT rowDescription(
  [in] long row,
  [out] BSTR description 
);
Parameters
row
The 0 based index of the row for which to retrieve the description.
description
Returns the description text of the specified row in the table if such a description exists. Otherwise a null pointer is returned.
Return value

E_INVALIDARG if bad [in] passed, [out] value is null. S_FALSE if there is nothing to return, [out] value is null. S_OK.

rowExtentAt()

Returns the number of rows occupied by the accessible object at the specified row and column in the table. The result is greater than 1 if the specified cell spans multiple rows.

[propget] HRESULT rowExtentAt(
  [in] long row,
  [in] long column,
  [out] long nRowsSpanned 
);
Parameters
row
0 based row index of the accessible for which to return the row extent.
column
0 based column index of the accessible for which to return the row extent.
nRowsSpanned
Returns the row extent of the specified cell.
Return value

E_INVALIDARG if bad [in] passed, [out] value is 0. S_OK.

rowHeader()

Returns the row headers as an IAccessibleTable object. Content and size of the returned table are implementation dependent.

[propget] HRESULT rowHeader(
  [out] IAccessibleTable accessibleTable,
  [out] long startingColumnIndex 
);
Parameters
accessibleTable
The row header.
startingColumnIndex
The 0 based column index where the header starts, usually 0.
Return value

S_FALSE if there is no header, [out] values are null and 0 respectively. S_OK.

rowIndex()

Translates the given cell index into a row index.

[propget] HRESULT rowIndex(
  [in] long cellIndex,
  [out] long rowIndex 
);
Parameters
cellIndex
0 based index of the cell in the parent or closest ancestor table. Typically this is the value returned from IAccessible2.indexInParent(), but in the case where the table cells are not direct children of the table this is the cell index specified by the "table-cell-index" object attribute obtained from parsing the attributes string returned by calling IAccessible2.attributes() on the cell object.
rowIndex
0 based row index.
Return value

E_INVALIDARG if bad [in] passed, [out] value is 0. S_OK.

selectColumn()

Selects a column and unselects all previously selected columns.

HRESULT selectColumn(
  [in] long column 
);
Parameters
column
0 based index of the column to be selected.
Return value

E_INVALIDARG if bad [in] passed. S_OK.

selectedChildren()

Returns a list of cell indexes currently selected (0 based).

[propget] HRESULT selectedChildren(
  [in] long maxChildren,
  [out, size_is(,maxChildren), length_is(, nChildren)] long children,
  [out] long nChildren 
);
Parameters
maxChildren
This parameter is ignored. Refer to @ref _arrayConsideration "Special Consideration when using Arrays" for more details.
children
An array of cell indexes of selected cells (each index is 0 based), allocated by the server. Free it with CoTaskMemFree.
nChildren
The number of cell indexes returned; the size of the returned array.
Return value

S_FALSE if there are none, [out] values are null and 0 respectively. S_OK.

selectedColumns()

Returns a list of column indexes currently selected (0 based).

[propget] HRESULT selectedColumns(
  [in] long maxColumns,
  [out, size_is(,maxColumns), length_is(, nColumns)] long columns,
  [out] long nColumns 
);
Parameters
maxColumns
This parameter is ignored. Refer to @ref _arrayConsideration "Special Consideration when using Arrays" for more details.
columns
An array of column indexes of selected columns (each index is 0 based), allocated by the server. Free it with CoTaskMemFree.
nColumns
The number of column indexes returned; the size of the returned array.
Return value

S_FALSE if there are none, [out] values are null and 0 respectively. S_OK.

selectedRows()

Returns a list of row indexes currently selected (0 based).

[propget] HRESULT selectedRows(
  [in] long maxRows,
  [out, size_is(,maxRows), length_is(, nRows)] long rows,
  [out] long nRows 
);
Parameters
maxRows
This parameter is ignored. Refer to @ref _arrayConsideration "Special Consideration when using Arrays" for more details.
rows
An array of row indexes of selected rows (each index is 0 based), allocated by the server. Free it with CoTaskMemFree.
nRows
The number of row indexes returned; the size of the returned array.
Return value

S_FALSE if there are none, [out] values are null and 0 respectively. S_OK.

selectRow()

Selects a row and unselects all previously selected rows.

HRESULT selectRow(
  [in] long row 
);
Parameters
row
0 based index of the row to be selected.
Return value

E_INVALIDARG if bad [in] passed. S_OK.

summary()

Returns the summary description of the table. The returned object could be an IAccessible or an IAccessible2.

[propget] HRESULT summary(
  [out] IUnknown accessible 
);
Parameters
accessible
Returns a reference to an implementation dependent accessible object representing the table's summary or a null pointer if the table does not support a summary.
Return value

S_FALSE if there is nothing to return, [out] value is null. S_OK.

unselectColumn()

Unselects one column, leaving other selected columns selected (if any).

HRESULT unselectColumn(
  [in] long column 
);
Parameters
column
0 based index of the column to be unselected.
Return value

E_INVALIDARG if bad [in] passed. S_OK.

unselectRow()

Unselects one row, leaving other selected rows selected (if any).

HRESULT unselectRow(
  [in] long row 
);
Parameters
row
0 based index of the row to be unselected.
Return value

E_INVALIDARG if bad [in] passed. S_OK.

See also

Document Tags and Contributors

Contributors to this page: Sheppy, trevorh
Last updated by: Sheppy,