atspi-table: libatspi Reference Manual

atspi-table

atspi-table — An interface used by containers whose data is arranged in a tabular form.

Functions

AtspiAccessible *	atspi_table_get_caption ()
AtspiAccessible *	atspi_table_get_summary ()
gint	atspi_table_get_n_rows ()
gint	atspi_table_get_n_columns ()
AtspiAccessible *	atspi_table_get_accessible_at ()
gint	atspi_table_get_index_at ()
gint	atspi_table_get_row_at_index ()
gint	atspi_table_get_column_at_index ()
gchar *	atspi_table_get_row_description ()
gchar *	atspi_table_get_column_description ()
gint	atspi_table_get_row_extent_at ()
gint	atspi_table_get_column_extent_at ()
AtspiAccessible *	atspi_table_get_row_header ()
AtspiAccessible *	atspi_table_get_column_header ()
gint	atspi_table_get_n_selected_rows ()
GArray *	atspi_table_get_selected_rows ()
GArray *	atspi_table_get_selected_columns ()
gint	atspi_table_get_n_selected_columns ()
gboolean	atspi_table_is_row_selected ()
gboolean	atspi_table_is_column_selected ()
gboolean	atspi_table_add_row_selection ()
gboolean	atspi_table_add_column_selection ()
gboolean	atspi_table_remove_row_selection ()
gboolean	atspi_table_remove_column_selection ()
gboolean	atspi_table_get_row_column_extents_at_index ()
gboolean	atspi_table_is_selected ()

Types and Values

AtspiTable

Object Hierarchy

    GInterface
    ╰── AtspiTable

Known Implementations

AtspiTable is implemented by AtspiAccessible.

Description

An interface used by containers whose contained data is arranged in a tabular (i.e. row-column) form. Tables may resemble a two-dimensional grid, as in a spreadsheet, or may feature objects which span multiple rows and/or columns, but whose bounds are aligned on a row/column matrix. Objects within tables are children of the table object, and they may be referenced either via a child index or via a row/column pair. Table 'cells' may implement other interfaces, such as Text, Action, Image, and Component, and should do so as appropriate to their onscreen rresentation and/or behavior.

Functions

atspi_table_get_caption ()

AtspiAccessible *
atspi_table_get_caption (AtspiTable *obj,
                         GError **error);

Gets an accessible representation of the caption for an AtspiTable.

Parameters

obj

a pointer to the AtspiTable implementor on which to operate.

Returns

an AtspiAccessible object that serves as the table's caption.

[transfer full]

atspi_table_get_summary ()

AtspiAccessible *
atspi_table_get_summary (AtspiTable *obj,
                         GError **error);

Gets an accessible object which summarizes the contents of an AtspiTable.

Parameters

obj

a pointer to the AtspiTable implementor on which to operate.

Returns

an AtspiAccessible object that serves as the table's summary (often a reduced AtspiTable).

[transfer full]

atspi_table_get_n_rows ()

gint
atspi_table_get_n_rows (AtspiTable *obj,
                        GError **error);

Gets the number of rows in an AtspiTable, exclusive of any rows that are programmatically hidden, but inclusive of rows that may be outside of the current scrolling window or viewport.

Parameters

obj

a pointer to the AtspiTable implementor on which to operate.

Returns

a gint indicating the number of rows in the table.

atspi_table_get_n_columns ()

gint
atspi_table_get_n_columns (AtspiTable *obj,
                           GError **error);

Gets the number of columns in an AtspiTable, exclusive of any columns that are programmatically hidden, but inclusive of columns that may be outside of the current scrolling window or viewport.

Parameters

obj

a pointer to the AtspiTable implementor on which to operate.

Returns

a gint indicating the number of columns in the table.

atspi_table_get_accessible_at ()

AtspiAccessible *
atspi_table_get_accessible_at (AtspiTable *obj,
                               gint row,
                               gint column,
                               GError **error);

Gets the table cell at the specified row and column indices. To get the accessible object at a particular (x, y) screen coordinate, use atspi_component_get_accessible_at_point.

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
row	the specified table row, zero-indexed.
column	the specified table column, zero-indexed.

Returns

an AtspiAccessible object representing the specified table cell.

[transfer full]

atspi_table_get_index_at ()

gint
atspi_table_get_index_at (AtspiTable *obj,
                          gint row,
                          gint column,
                          GError **error);

Gets the 1-D child index corresponding to the specified 2-D row and column indices. To get the accessible object at a particular (x, y) screen coordinate, use atspi_component_get_accessible_at_point.

see atspi_table_get_row_at_index, atspi_table_get_column_at_index

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
row	the specified table row, zero-indexed.
column	the specified table column, zero-indexed.

Returns

a gint which serves as the index of a specified cell in the table, in a form usable by atspi_get_child_at_index.

atspi_table_get_row_at_index ()

gint
atspi_table_get_row_at_index (AtspiTable *obj,
                              gint index,
                              GError **error);

Gets the table row index occupied by the child at a particular 1-D child index.

see atspi_table_get_index_at, atspi_table_get_column_at_index

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
index	the specified child index, zero-indexed.

Returns

a gint indicating the first row spanned by the child of a table, at the specified 1-D (zero-offset) index .

atspi_table_get_column_at_index ()

gint
atspi_table_get_column_at_index (AtspiTable *obj,
                                 gint index,
                                 GError **error);

Gets the table column index occupied by the child at a particular 1-D child index.

see atspi_table_get_index_at, atspi_table_get_row_at_index

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
index	the specified child index, zero-indexed.

Returns

a gint indicating the first column spanned by the child of a table, at the specified 1-D (zero-offset) index .

atspi_table_get_row_description ()

gchar *
atspi_table_get_row_description (AtspiTable *obj,
                                 gint row,
                                 GError **error);

Gets a text description of a particular table row. This differs from atspi_table_get_row_header, which returns an AtspiAccessible.

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
row	the specified table row, zero-indexed.

Returns

a UTF-8 string describing the specified table row, if available.

atspi_table_get_column_description ()

gchar *
atspi_table_get_column_description (AtspiTable *obj,
                                    gint column,
                                    GError **error);

Gets a text description of a particular table column. This differs from atspi_table_get_column_header, which returns an Accessible.

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
column	the specified table column, zero-indexed.

Returns

a UTF-8 string describing the specified table column, if available.

atspi_table_get_row_extent_at ()

gint
atspi_table_get_row_extent_at (AtspiTable *obj,
                               gint row,
                               gint column,
                               GError **error);

Gets the number of rows spanned by the table cell at the specific row and column. (some tables can have cells which span multiple rows and/or columns).

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
row	the specified table row, zero-indexed.
column	the specified table column, zero-indexed.

Returns

a gint indicating the number of rows spanned by the specified cell.

atspi_table_get_column_extent_at ()

gint
atspi_table_get_column_extent_at (AtspiTable *obj,
                                  gint row,
                                  gint column,
                                  GError **error);

Gets the number of columns spanned by the table cell at the specific row and column (some tables can have cells which span multiple rows and/or columns).

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
row	the specified table row, zero-indexed.
column	the specified table column, zero-indexed.

Returns

a gint indicating the number of columns spanned by the specified cell.

atspi_table_get_row_header ()

AtspiAccessible *
atspi_table_get_row_header (AtspiTable *obj,
                            gint row,
                            GError **error);

Gets the header associated with a table row, if available. This differs from atspi_table_get_row_description, which returns a string.

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
row	the specified table row, zero-indexed.

Returns

an AtspiAccessible representation of the specified table row, if available.

[transfer full]

atspi_table_get_column_header ()

AtspiAccessible *
atspi_table_get_column_header (AtspiTable *obj,
                               gint column,
                               GError **error);

Gets the header associated with a table column, if available. This differs from atspi_table_get_column_description, which returns a string.

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
column	the specified table column, zero-indexed.

Returns

an AtspiAccessible representation of the specified table column, if available.

[transfer full]

atspi_table_get_n_selected_rows ()

gint
atspi_table_get_n_selected_rows (AtspiTable *obj,
                                 GError **error);

Query a table to find out how many rows are currently selected. Not all tables support row selection.

Parameters

obj

a pointer to the AtspiTable implementor on which to operate.

Returns

a gint indicating the number of rows currently selected.

atspi_table_get_selected_rows ()

GArray *
atspi_table_get_selected_rows (AtspiTable *obj,
                               GError **error);

Queries a table for a list of indices of rows which are currently selected.

Parameters

obj

a pointer to the AtspiTable implementor on which to operate.

Returns

an array of gint values, specifying which rows are currently selected.

[element-type gint][transfer full]

atspi_table_get_selected_columns ()

GArray *
atspi_table_get_selected_columns (AtspiTable *obj,
                                  GError **error);

Queries a table for a list of indices of columns which are currently selected.

Parameters

obj

a pointer to the AtspiTable implementor on which to operate.

Returns

an array of gint values, specifying which columns are currently selected.

[element-type gint][transfer full]

atspi_table_get_n_selected_columns ()

gint
atspi_table_get_n_selected_columns (AtspiTable *obj,
                                    GError **error);

Queries a table to find out how many columns are currently selected. Not all tables support column selection.

Parameters

obj

a pointer to the AtspiTable implementor on which to operate.

Returns

a gint indicating the number of columns currently selected.

atspi_table_is_row_selected ()

gboolean
atspi_table_is_row_selected (AtspiTable *obj,
                             gint row,
                             GError **error);

Determines whether a table row is selected. Not all tables support row selection.

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
row	the zero-indexed row number of the row being queried.

Returns

TRUE if the specified row is currently selected, FALSE if not.

atspi_table_is_column_selected ()

gboolean
atspi_table_is_column_selected (AtspiTable *obj,
                                gint column,
                                GError **error);

Determines whether specified table column is selected. Not all tables support column selection.

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
column	the zero-indexed column number of the column being queried.

Returns

TRUE if the specified column is currently selected, FALSE if not.

atspi_table_add_row_selection ()

gboolean
atspi_table_add_row_selection (AtspiTable *obj,
                               gint row,
                               GError **error);

Selects the specified row, adding it to the current row selection. Not all tables support row selection.

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
row	the zero-indexed row number of the row being selected.

Returns

TRUE if the specified row was successfully selected, FALSE if not.

atspi_table_add_column_selection ()

gboolean
atspi_table_add_column_selection (AtspiTable *obj,
                                  gint column,
                                  GError **error);

Selects the specified column, adding it to the current column selection. Not all tables support column selection.

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
column	the zero-indexed column number of the column being selected.

Returns

TRUE if the specified column was successfully selected, FALSE if not.

atspi_table_remove_row_selection ()

gboolean
atspi_table_remove_row_selection (AtspiTable *obj,
                                  gint row,
                                  GError **error);

De-selects the specified row, removing it from the current row selection. Not all tables support row selection.

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
row	the zero-indexed number of the row being de-selected.

Returns

TRUE if the specified row was successfully de-selected, FALSE if not.

atspi_table_remove_column_selection ()

gboolean
atspi_table_remove_column_selection (AtspiTable *obj,
                                     gint column,
                                     GError **error);

De-selects the specified column, removing it from the current column selection. Not all tables support column selection.

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
column	the zero-indexed column number of the column being de-selected.

Returns

TRUE if the specified column was successfully de-selected, FALSE if not.

atspi_table_get_row_column_extents_at_index ()

gboolean
atspi_table_get_row_column_extents_at_index
                               (AtspiTable *obj,
                                gint index,
                                gint *row,
                                gint *col,
                                gint *row_extents,
                                gint *col_extents,
                                gboolean *is_selected,
                                GError **error);

Given a child index, determines the row and column indices and extents, and whether the cell is currently selected. If the child at index is not a cell (for instance, if it is a summary, caption, etc.), FALSE is returned.

Example: If the AtspiTable child at index '6' extends across columns 5 and 6 of row 2 of an AtspiTable instance, and is currently selected, then

retval = atspi_table_get_row_column_extents_at_index (table, 6, row, col, row_extents, col_extents, is_selected);

will return TRUE, and after the call row, col, row_extents, col_extents, and is_selected will contain 2, 5, 1, 2, and TRUE, respectively.

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
index	the index of the AtspiTable child whose row/column extents are requested.
row	back-filled with the first table row associated with the cell with child index.	[out]
col	back-filled with the first table column associated with the cell with child index.	[out]
row_extents	back-filled with the number of table rows across which child i extends.	[out]
col_extents	back-filled with the number of table columns across which child i extends.	[out]
is_selected	a boolean which is back-filled with TRUE if the child at index i corresponds to a selected table cell, FALSE otherwise.	[out]

Returns

TRUE if the index is associated with a valid table cell, FALSE if the index does not correspond to a cell. If FALSE is returned, the values of the out parameters are undefined.

atspi_table_is_selected ()

gboolean
atspi_table_is_selected (AtspiTable *obj,
                         gint row,
                         gint column,
                         GError **error);

Determines whether the cell at a specific row and column is selected.

Parameters

obj	a pointer to the AtspiTable implementor on which to operate.
row	the zero-indexed row of the cell being queried.
column	the zero-indexed column of the cell being queried.

Returns

TRUE if the specified cell is currently selected, FALSE if not.

Types and Values

AtspiTable

typedef struct _AtspiTable AtspiTable;