IAccessible2 API: IAccessibleTable Interface Reference

This interface gives access to a two-dimensional table. More...

import "AccessibleTable.idl";

Inheritance diagram for IAccessibleTable:

Public Member Functions
HRESULT	accessibleAt ([in] long row,[in] long column,[out, retval] IUnknown **accessible)
	Returns the accessible object at the specified row and column in the table. This object could be an IAccessible or an IAccessible2. More...

HRESULT	caption ([out, retval] IUnknown **accessible)
	Returns the caption for the table. The returned object could be an IAccessible or an IAccessible2. More...

HRESULT	childIndex ([in] long rowIndex,[in] long columnIndex,[out, retval] long *cellIndex)
	Translates the given row and column indexes into the corresponding cell index. More...

HRESULT	columnDescription ([in] long column,[out, retval] BSTR *description)
	Returns the description text of the specified column in the table. More...

HRESULT	columnExtentAt ([in] long row,[in] long column,[out, retval] long *nColumnsSpanned)
	Returns the number of columns occupied by the accessible object at the specified row and column in the table. More...

HRESULT	columnHeader ([out] IAccessibleTable *accessibleTable,[out, retval] long startingRowIndex)
	Returns the column headers as an IAccessibleTable object. More...

HRESULT	columnIndex ([in] long cellIndex,[out, retval] long *columnIndex)
	Translates the given cell index into the corresponding column index. More...

HRESULT	nColumns ([out, retval] long *columnCount)
	Returns the total number of columns in table. More...

HRESULT	nRows ([out, retval] long *rowCount)
	Returns the total number of rows in table. More...

HRESULT	nSelectedChildren ([out, retval] long *cellCount)
	Returns the total number of selected cells. More...

HRESULT	nSelectedColumns ([out, retval] long *columnCount)
	Returns the total number of selected columns. More...

HRESULT	nSelectedRows ([out, retval] long *rowCount)
	Returns the total number of selected rows. More...

HRESULT	rowDescription ([in] long row,[out, retval] BSTR *description)
	Returns the description text of the specified row in the table. More...

HRESULT	rowExtentAt ([in] long row,[in] long column,[out, retval] long *nRowsSpanned)
	Returns the number of rows occupied by the accessible object at the specified row and column in the table. More...

HRESULT	rowHeader ([out] IAccessibleTable *accessibleTable,[out, retval] long startingColumnIndex)
	Returns the row headers as an IAccessibleTable object. More...

HRESULT	rowIndex ([in] long cellIndex,[out, retval] long *rowIndex)
	Translates the given cell index into a row index. More...

HRESULT	selectedChildren ([in] long maxChildren,[out, size_is(, maxChildren), length_is(,nChildren)] long children,[out, retval] long nChildren)
	Returns a list of cell indexes currently selected (0 based). More...

HRESULT	selectedColumns ([in] long maxColumns,[out, size_is(, maxColumns), length_is(,nColumns)] long columns,[out, retval] long nColumns)
	Returns a list of column indexes currently selected (0 based). More...

HRESULT	selectedRows ([in] long maxRows,[out, size_is(, maxRows), length_is(,nRows)] long rows,[out, retval] long nRows)
	Returns a list of row indexes currently selected (0 based). More...

HRESULT	summary ([out, retval] IUnknown **accessible)
	Returns the summary description of the table. The returned object could be an IAccessible or an IAccessible2. More...

HRESULT	isColumnSelected ([in] long column,[out, retval] boolean *isSelected)
	Returns a boolean value indicating whether the specified column is completely selected. More...

HRESULT	isRowSelected ([in] long row,[out, retval] boolean *isSelected)
	Returns a boolean value indicating whether the specified row is completely selected. More...

HRESULT	isSelected ([in] long row,[in] long column,[out, retval] boolean *isSelected)
	Returns a boolean value indicating whether the specified cell is selected. More...

HRESULT	selectRow ([in] long row)
	Selects a row and unselects all previously selected rows. More...

HRESULT	selectColumn ([in] long column)
	Selects a column and unselects all previously selected columns. More...

HRESULT	unselectRow ([in] long row)
	Unselects one row, leaving other selected rows selected (if any). More...

HRESULT	unselectColumn ([in] long column)
	Unselects one column, leaving other selected columns selected (if any). More...

HRESULT	rowColumnExtentsAtIndex ([in] long index,[out] long row,[out] long column,[out] long rowExtents,[out] long columnExtents,[out, retval] boolean *isSelected)
	Given a cell index, gets the row and column indexes and extents of a cell and whether or not it is selected. More...

HRESULT	modelChange ([out, retval] IA2TableModelChange *modelChange)
	Returns the type and extents describing how a table changed. More...

Detailed Description

This interface gives access to a two-dimensional table.

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 IAccessibleTable::rowIndex and IAccessibleTable::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 IAccessibleTable::nRows and IAccessibleTable::nColumns.

Note that newer implementations are now using IAccessibleTable2 and IAccessibleTableCell rather than this interface.

Member Function Documentation

HRESULT IAccessibleTable::accessibleAt	(	[in] long	row,
		[in] long	column,
		[out, retval] IUnknown **	accessible
	)

get

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

Parameters

[in]	row	The 0 based row index for which to retrieve the cell.
[in]	column	The 0 based column index for which to retrieve the cell.
[out]	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 values

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

HRESULT IAccessibleTable::caption ( [out, retval] IUnknown ** accessible )

get

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

Parameters

[out] accessible If the table has a caption then a reference to it is returned, else a NULL pointer is returned.

Return values

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

HRESULT IAccessibleTable::childIndex	(	[in] long	rowIndex,
		[in] long	columnIndex,
		[out, retval] long *	cellIndex
	)

get

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

Parameters

[in]	rowIndex	0 based row index for the cell.
[in]	columnIndex	0 based column index for the cell.
[out]	cellIndex	Returns the 0 based index of the cell at the specified row and column indexes.

Return values

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

Note: The returned value is not necessarily a child index of the immediate parent. In cases where the table cells are not direct children of the table the index is actually the cell index, i.e. conceptually it's an index into a one dimensional array of cells laid out in row order.

HRESULT IAccessibleTable::columnDescription	(	[in] long	column,
		[out, retval] BSTR *	description
	)

get

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

Parameters

[in]	column	The 0 based index of the column for which to retrieve the description.
[out]	description	Returns the description text of the specified column in the table if such a description exists. Otherwise a NULL pointer is returned.

Return values

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

HRESULT IAccessibleTable::columnExtentAt	(	[in] long	row,
		[in] long	column,
		[out, retval] long *	nColumnsSpanned
	)

get

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.

Parameters

[in]	row	0 based row index of the accessible for which to return the column extent.
[in]	column	0 based column index of the accessible for which to return the column extent.
[out]	nColumnsSpanned	Returns the 1 based column extent of the specified cell.

Return values

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

HRESULT IAccessibleTable::columnHeader	(	[out] IAccessibleTable **	accessibleTable,
		[out, retval] long *	startingRowIndex
	)

get

Returns the column headers as an IAccessibleTable object.

Content and size of the returned table are implementation dependent.

Parameters

[out]	accessibleTable	The column header
[out]	startingRowIndex	The 0 based row index where the header starts, usually 0.

Return values

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

HRESULT IAccessibleTable::columnIndex	(	[in] long	cellIndex,
		[out, retval] long *	columnIndex
	)

get

Translates the given cell index into the corresponding column index.

Parameters

[in]	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.
[out]	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 values

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

HRESULT IAccessibleTable::isColumnSelected	(	[in] long	column,
		[out, retval] boolean *	isSelected
	)

get

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

Parameters

[in]	column	0 based index of the column for which to determine whether it is selected.
[out]	isSelected	Returns TRUE if the specified column is selected completely and FALSE otherwise.

Return values

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

HRESULT IAccessibleTable::isRowSelected	(	[in] long	row,
		[out, retval] boolean *	isSelected
	)

get

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

Parameters

[in]	row	0 based index of the row for which to determine whether it is selected.
[out]	isSelected	Returns TRUE if the specified row is selected completely and FALSE otherwise.

Return values

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

HRESULT IAccessibleTable::isSelected	(	[in] long	row,
		[in] long	column,
		[out, retval] boolean *	isSelected
	)

get

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

Parameters

[in]	row	0 based index of the row for the cell to determine whether it is selected.
[in]	column	0 based index of the column for the cell to determine whether it is selected.
[out]	isSelected	Returns TRUE if the specified cell is selected and FALSE otherwise.

Return values

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

HRESULT IAccessibleTable::modelChange ( [out, retval] IA2TableModelChange * modelChange )

get

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.

Parameters

[out] modelChange A struct of (type(insert, delete, update), firstRow, lastRow, firstColumn, lastColumn).

Return values

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

HRESULT IAccessibleTable::nColumns ( [out, retval] long * columnCount )

get

Returns the total number of columns in table.

Parameters

[out] columnCount Number of columns in table (including columns outside the current viewport)

Return values

S_OK

HRESULT IAccessibleTable::nRows ( [out, retval] long * rowCount )

get

Returns the total number of rows in table.

Parameters

[out] rowCount Number of rows in table (including rows outside the current viewport)

Return values

S_OK

HRESULT IAccessibleTable::nSelectedChildren ( [out, retval] long * cellCount )

get

Returns the total number of selected cells.

Parameters

[out] cellCount Number of cells currently selected

Return values

S_OK

HRESULT IAccessibleTable::nSelectedColumns ( [out, retval] long * columnCount )

get

Returns the total number of selected columns.

Parameters

[out] columnCount Number of columns currently selected

Return values

S_OK

HRESULT IAccessibleTable::nSelectedRows ( [out, retval] long * rowCount )

get

Returns the total number of selected rows.

Parameters

[out] rowCount Number of rows currently selected

Return values

S_OK

HRESULT IAccessibleTable::rowColumnExtentsAtIndex	(	[in] long	index,
		[out] long *	row,
		[out] long *	column,
		[out] long *	rowExtents,
		[out] long *	columnExtents,
		[out, retval] boolean *	isSelected
	)

get

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.

Parameters

[in]	index	0 based index of this cell in the table.
[out]	row	0 based row index.
[out]	column	0 based column index.
[out]	rowExtents	Number of cells spanned by this cell in this row.
[out]	columnExtents	Number of cells spanned by this cell in this column.
[out]	isSelected	Indicates if the specified cell is selected.

Return values

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

HRESULT IAccessibleTable::rowDescription	(	[in] long	row,
		[out, retval] BSTR *	description
	)

get

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

Parameters

[in]	row	The 0 based index of the row for which to retrieve the description.
[out]	description	Returns the description text of the specified row in the table if such a description exists. Otherwise a NULL pointer is returned.

Return values

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

HRESULT IAccessibleTable::rowExtentAt	(	[in] long	row,
		[in] long	column,
		[out, retval] long *	nRowsSpanned
	)

get

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.

Parameters

[in]	row	0 based row index of the accessible for which to return the row extent.
[in]	column	0 based column index of the accessible for which to return the row extent.
[out]	nRowsSpanned	Returns the row extent of the specified cell.

Return values

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

HRESULT IAccessibleTable::rowHeader	(	[out] IAccessibleTable **	accessibleTable,
		[out, retval] long *	startingColumnIndex
	)

get

Returns the row headers as an IAccessibleTable object.

Content and size of the returned table are implementation dependent.

Parameters

[out]	accessibleTable	The row header.
[out]	startingColumnIndex	The 0 based column index where the header starts, usually 0.

Return values

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

HRESULT IAccessibleTable::rowIndex	(	[in] long	cellIndex,
		[out, retval] long *	rowIndex
	)

get

Translates the given cell index into a row index.

Parameters

[in]	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.
[out]	rowIndex	0 based row index

Return values

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

HRESULT IAccessibleTable::selectColumn ( [in] long column )

Selects a column and unselects all previously selected columns.

Parameters

[in] column 0 based index of the column to be selected.

Return values

S_OK
E_INVALIDARG	if bad [in] passed

HRESULT IAccessibleTable::selectedChildren	(	[in] long	maxChildren,
		[out, size_is(, maxChildren), length_is(,nChildren)] long *	children,
		[out, retval] long *	nChildren
	)

get

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

Parameters

[in]	maxChildren	This parameter is ignored. Refer to Special Consideration when using Arrays for more details.
[out]	children	An array of cell indexes of selected cells (each index is 0 based), allocated by the server. The client must free it with CoTaskMemFree.
[out]	nChildren	The number of cell indexes returned; the size of the returned array.

Return values

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

HRESULT IAccessibleTable::selectedColumns	(	[in] long	maxColumns,
		[out, size_is(, maxColumns), length_is(,nColumns)] long *	columns,
		[out, retval] long *	nColumns
	)

get

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

Parameters

[in]	maxColumns	This parameter is ignored. Refer to Special Consideration when using Arrays for more details.
[out]	columns	An array of column indexes of selected columns (each index is 0 based), allocated by the server. The client must free it with CoTaskMemFree.
[out]	nColumns	The number of column indexes returned; the size of the returned array.

Return values

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

HRESULT IAccessibleTable::selectedRows	(	[in] long	maxRows,
		[out, size_is(, maxRows), length_is(,nRows)] long *	rows,
		[out, retval] long *	nRows
	)

get

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

Parameters

[in]	maxRows	This parameter is ignored. Refer to Special Consideration when using Arrays for more details.
[out]	rows	An array of row indexes of selected rows (each index is 0 based), allocated by the server. The client must free it with CoTaskMemFree.
[out]	nRows	The number of row indexes returned; the size of the returned array.

Return values

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

HRESULT IAccessibleTable::selectRow ( [in] long row )

Selects a row and unselects all previously selected rows.

Parameters

[in] row 0 based index of the row to be selected.

Return values

S_OK
E_INVALIDARG	if bad [in] passed

HRESULT IAccessibleTable::summary ( [out, retval] IUnknown ** accessible )

get

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

Parameters

[out] 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 values

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

HRESULT IAccessibleTable::unselectColumn ( [in] long column )

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

Parameters

[in] column 0 based index of the column to be unselected.

Return values

S_OK
E_INVALIDARG	if bad [in] passed

HRESULT IAccessibleTable::unselectRow ( [in] long row )

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

Parameters

[in] row 0 based index of the row to be unselected.

Return values

S_OK
E_INVALIDARG	if bad [in] passed

The documentation for this interface was generated from the following file:

AccessibleTable.idl

Public Member Functions

Detailed Description

Member Function Documentation