atspi-table

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

## Synopsis

                        AtspiTable;
    AtspiAccessible *   atspi_table_get_caption             (AtspiTable *obj,
                                                             GError **error);
    AtspiAccessible *   atspi_table_get_summary             (AtspiTable *obj,
                                                             GError **error);
    gint                atspi_table_get_n_rows              (AtspiTable *obj,
                                                             GError **error);
    gint                atspi_table_get_n_columns           (AtspiTable *obj,
                                                             GError **error);
    AtspiAccessible *   atspi_table_get_accessible_at       (AtspiTable *obj,
                                                             gint row,
                                                             gint column,
                                                             GError **error);
    gint                atspi_table_get_index_at            (AtspiTable *obj,
                                                             gint row,
                                                             gint column,
                                                             GError **error);
    gint                atspi_table_get_row_at_index        (AtspiTable *obj,
                                                             gint index,
                                                             GError **error);
    gint                atspi_table_get_column_at_index     (AtspiTable *obj,
                                                             gint index,
                                                             GError **error);
    gchar *             atspi_table_get_row_description     (AtspiTable *obj,
                                                             gint row,
                                                             GError **error);
    gchar *             atspi_table_get_column_description  (AtspiTable *obj,
                                                             gint column,
                                                             GError **error);
    gint                atspi_table_get_row_extent_at       (AtspiTable *obj,
                                                             gint row,
                                                             gint column,
                                                             GError **error);
    gint                atspi_table_get_column_extent_at    (AtspiTable *obj,
                                                             gint row,
                                                             gint column,
                                                             GError **error);
    AtspiAccessible *   atspi_table_get_row_header          (AtspiTable *obj,
                                                             gint row,
                                                             GError **error);
    AtspiAccessible *   atspi_table_get_column_header       (AtspiTable *obj,
                                                             gint column,
                                                             GError **error);
    gint                atspi_table_get_n_selected_rows     (AtspiTable *obj,
                                                             GError **error);
    GArray *            atspi_table_get_selected_rows       (AtspiTable *obj,
                                                             GError **error);
    GArray *            atspi_table_get_selected_columns    (AtspiTable *obj,
                                                             GError **error);
    gint                atspi_table_get_n_selected_columns  (AtspiTable *obj,
                                                             GError **error);
    gboolean            atspi_table_is_row_selected         (AtspiTable *obj,
                                                             gint row,
                                                             GError **error);
    gboolean            atspi_table_is_column_selected      (AtspiTable *obj,
                                                             gint column,
                                                             GError **error);
    gboolean            atspi_table_add_row_selection       (AtspiTable *obj,
                                                             gint row,
                                                             GError **error);
    gboolean            atspi_table_add_column_selection    (AtspiTable *obj,
                                                             gint column,
                                                             GError **error);
    gboolean            atspi_table_remove_row_selection    (AtspiTable *obj,
                                                             gint row,
                                                             GError **error);
    gboolean            atspi_table_remove_column_selection (AtspiTable *obj,
                                                             gint column,
                                                             GError **error);
    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);
    gboolean            atspi_table_is_selected             (AtspiTable *obj,
                                                             gint row,
                                                             gint column,
                                                             GError **error);

## 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.

## Details

### AtspiTable

    typedef struct _AtspiTable AtspiTable;

### atspi_table_get_caption ()

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

Gets an accessible representation of the caption for an AtspiTable.

`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.

`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.

`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.

`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.

`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

`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

`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

`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.

`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.

`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).

`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).

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.