/* * AT-SPI - Assistive Technology Service Provider Interface * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap) * * Copyright 2001 Sun Microsystems, Inc. * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public * License as published by the Free Software Foundation; either * version 2 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public * License along with this library; if not, write to the * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ #include module Accessibility { typedef sequence LongSeq; /** * An interface used by containers whose contained data is arranged in * a "tabular" (i.e.\ row-column) fashion. 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. Thus, the Table * interface may be used to represent "spreadsheets" as well as "frames". * * Objects within tables are children of the Table instance, and they may be referenced * either via a child index or via a row/column pair. * Their role may be ROLE_TABLE_CELL, but table 'cells' may have other roles as well. * These 'cells' may implement other interfaces, such as Text, Action, Image, * and Component, and should do so as appropriate to their onscreen representation * and/or behavior. */ interface Table : Bonobo::Unknown { /** * The total number of rows in this table (including empty rows), * exclusive of any rows which are programmatically hidden. * Rows which are merely scrolled out of view are included. */ readonly attribute long nRows; /** * The total number of columns in this table (including empty columns), * exclusive of columns which are programmatically hidden. * Columns which are scrolled out of view or clipped by the current * viewport are included. */ readonly attribute long nColumns; /** * An Accessible which represents of a caption for a Table. **/ readonly attribute Accessible caption; /** * An accessible object which summarizes the contents of a Table. * This object is frequently itself a Table instance, albeit a simplified one. */ readonly attribute Accessible summary; /** * The number of rows currently selected. * A selected row is one in which all included cells are selected. * @note Not all tables support row selection. */ readonly attribute long nSelectedRows; /** * The number of columns currently selected. * A selected column is one in which all included cells are selected. * @note Not all tables support column selection. */ readonly attribute long nSelectedColumns; /** * Get the table cell at the specified row and column indices. * @note To get the accessible object at a particular (x, y) screen coordinate, * use Accessible::getAccessibleAtPoint (). * * @param row: the specified table row, zero-indexed. * @param column: the specified table column, zero-indexed. * * @returns an Accessible object representing the specified table cell. **/ Accessible getAccessibleAt (in long row, in long column); /** * Get the 1-D child index corresponding to the specified 2-D row and column indices. * @note To get the accessible object at a particular (x, y) screen coordinate, * use Accessible::getAccessibleAtPoint. * * @param row: the specified table row, zero-indexed. * @param column: the specified table column, zero-indexed. * * @see getRowAtIndex, getColumnAtIndex * * @returns a long integer which serves as the index of a specified cell in the * table, in a form usable by Accessible::getChildAtIndex. **/ long getIndexAt (in long row, in long column); /** * Get the table row index occupied by the child at a particular 1-D child index. * * @param index: the specified child index, zero-indexed. * * @see getIndexAt(), getColumnAtIndex() * * @returns a long integer indicating the first row spanned by the child of a * table, at the specified 1-D (zero-offset) \c index. **/ long getRowAtIndex (in long index); /** * Get the table column index occupied by the child at a particular 1-D child index. * * @param index: the specified child index, zero-indexed. * * @see getIndexAt(), getRowAtIndex() * * @returns a long integer indicating the first column spanned by the child of a * table, at the specified 1-D (zero-offset) \c index. **/ long getColumnAtIndex (in long index); /** * Get a text description of a particular table row. This differs from * AccessibleTable_getRowHeader, which returns an Accessible. * @param row: the specified table row, zero-indexed. * * @returns a UTF-8 string describing the specified table row, if available. **/ string getRowDescription (in long row); /** * Get a text description of a particular table column. This differs from * AccessibleTable_getColumnHeader, which returns an Accessible. * @param column: the specified table column, zero-indexed. * * @returns a UTF-8 string describing the specified table column, if available. **/ string getColumnDescription (in long column); /** * Get 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). * * @param row: the specified table row, zero-indexed. * @param column: the specified table column, zero-indexed. * * @returns a long integer indicating the number of rows spanned by the specified cell. **/ long getRowExtentAt (in long row, in long column); /** * Get 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). * * @param row: the specified table row, zero-indexed. * @param column: the specified table column, zero-indexed. * * @returns a long integer indicating the number of columns spanned by the * specified cell. **/ long getColumnExtentAt (in long row, in long column); /** * Get the header associated with a table row, if available. This differs from * getRowDescription, which returns a string. * * @param row: the specified table row, zero-indexed. * * @returns an Accessible representatin of the specified table row, if available. **/ Accessible getRowHeader (in long row); /** * Get the header associated with a table column, if available, as an * instance of Accessible. This differs from * getColumnDescription, which returns a string. * * @param column: the specified table column, zero-indexed. * * @returns an Accessible representatin of the specified table column, if available. **/ Accessible getColumnHeader (in long column); /** * Obtain the indices of all rows which are currently selected. * @note Not all tables support row selection. * * @returns a sequence of integers comprising the indices of rows currently selected. **/ LongSeq getSelectedRows (); /** * Obtain the indices of all columns which are currently selected. * @note Not all tables support column selection. * * @returns a sequence of integers comprising the indices of columns currently selected. **/ LongSeq getSelectedColumns (); /** * Determine whether a table row is selected. * @note Not all tables support row selection. * * @param row: the row being queried. * * @returns \c True if the specified row is currently selected, \c False if not. **/ boolean isRowSelected (in long row); /** * Determine whether a table column is selected. * @note Not all tables support column selection. * * @param column: the column being queried. * * @returns \c True if the specified column is currently selected, \c False if not. **/ boolean isColumnSelected (in long column); /** * Determine whether the cell at a specific row and column is selected. * @param row a row occupied by the cell whose state is being queried. * @param column a column occupied by the cell whose state is being queried. * * @returns \c True if the specified cell is currently selected, * \c False if not. **/ boolean isSelected (in long row, in long column); /** * Select the specified row, adding it to the current row selection, * if the table's selection model permits it. * * @param row * @note Possible reasons for addRowSelection to return \c False * include: * \li The table does not support Selection * \li The table row includes cells which do not have STATE_SELECTABLE * \li The table does not support selection by row * \li The table does not support selection of multiple rows, and * one row is already selected. * \li The table does not support non-contiguous selections (i.e. * does not include STATE_MULTISELECTABLE), and the specified row * would result in selection of non-contiguous rows. * \li The table does not support user-instigated selection. * * @returns \c True if the specified row was successfully selected, * \c False if not. **/ boolean addRowSelection (in long row); /** * Select the specified column, adding it to the current column selection, * if the table's selection model permits it. * * @param column * @note Possible reasons for addColumnSelection to return \c False * include: * \li The table does not support Selection * \li The table column includes cells which do not have STATE_SELECTABLE * \li The table does not support selection by column * \li The table does not support selection of multiple columns, and * one column is already selected. * \li The table does not support non-contiguous selections (i.e. * does not include STATE_MULTISELECTABLE), and the specified column * would result in selection of non-contiguous columns. * \li The table does not support user-instigated selection. * * @returns \c True if the specified column was successfully selected, * \c False if not. **/ boolean addColumnSelection (in long column); /** * Remove the specified row from current row selection, * if the table's selection model permits it. * * @param row * @note Possible reasons for removeRowSelection to return \c False * include: * \li The table does not support user-instigated Selection * \li The table has no selected rows or does not support deselection by row * * @returns \c True if the specified row was successfully de-selected, * \c False if not. **/ boolean removeRowSelection (in long row); /** * Remove the specified column from current column selection, * if the table's selection model permits it. * * @param column * @note Possible reasons for removeColumnSelection to return \c False * include: * \li The table does not support user-instigated modification of * selection state * \li The table has no selected columns or does not support * deselection by column. * * @returns \c True if the specified column was successfully de-selected, * \c False if not. **/ boolean removeColumnSelection (in long column); /** * Given a child index, determine the row and column indices and * extents, and whether the cell is currently selected. If * the child at \c index is not a cell (for instance, if it is * a summary, caption, etc.), \c False is returned. * * @param index the index of the Table child whose row/column * extents are requested. * @param row back-filled with the first table row associated with * the cell with child index \c index. * @param col back-filled with the first table column associated * with the cell with child index \c index. * @param row_extents back-filled with the number of table rows * across which child \c i extends. * @param col_extents back-filled with the number of table columns * across which child \c i extends. * @param is_selected a boolean which is back-filled with \c True * if the child at index \c i corresponds to a selected table cell, * \c False otherwise. * * Example: * If the Table child at index '6' extends across columns 5 and 6 of * row 2 of a Table instance, and is currently selected, then * \code * retval = table::getRowColumnExtentsAtIndex (6, row, col, * row_extents, * col_extents, * is_selected); * \endcode * will return True, and after the call * \c row, \c col, \c row_extents, \c col_extents, * and \c is_selected will contain \c 2, \c 5, \c 1, \c 2, and * \c True, respectively. * * @returns \c True if the index is associated with a valid table * cell, \c False if the index does not correspond to a cell. If * \c False is returned, the values of the out parameters are * undefined. * * @since AT-SPI 1.7.0 **/ boolean getRowColumnExtentsAtIndex (in long index, out long row, out long col, out long row_extents, out long col_extents, out boolean is_selected); /** \cond * unImplemented: * * placeholders for future expansion. */ void unImplemented (); void unImplemented2 (); void unImplemented3 (); void unImplemented4 (); void unImplemented5 (); void unImplemented6 (); void unImplemented7 (); /** \endcond */ }; };