idl/Accessibility_Table.idl

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2001 Sun Microsystems, Inc.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #include <Accessibility_Accessible.idl>
  24
  25 module Accessibility {
  26
  27 typedef sequence<long> LongSeq;
  28
  29   /**
  30    * An interface used by containers whose contained data is arranged in
  31    * a "tabular" (i.e.\ row-column) fashion.  Tables may resemble a two-dimensional
  32    * grid, as in a spreadsheet, or may feature objects which span multiple rows and/or
  33    * columns, but whose bounds are aligned on a row/column matrix.  Thus, the Table
  34    * interface may be used to represent "spreadsheets" as well as "frames".
  35    *
  36    * Objects within tables are children of the Table instance, and they may be referenced
  37    * either via a child index or via a row/column pair.
  38    * Their role may be ROLE_TABLE_CELL, but table 'cells' may have other roles as well.
  39    * These 'cells' may implement other interfaces, such as Text, Action, Image,
  40    * and Component, and should do so as appropriate to their onscreen representation
  41    * and/or behavior.
  42    */
  43  interface Table : Bonobo::Unknown {
  44    /**
  45     * The total number of rows in this table (including empty rows),
  46     * exclusive of any rows which are programmatically hidden.
  47     * Rows which are merely scrolled out of view are included.
  48     */
  49    readonly attribute long nRows;
  50    /**
  51     * The total number of columns in this table (including empty columns),
  52     * exclusive of columns which are programmatically hidden.
  53     * Columns which are scrolled out of view or clipped by the current
  54     * viewport are included.
  55     */
  56    readonly attribute long nColumns;
  57    /**
  58     * An Accessible which represents of a caption for a Table.
  59     **/
  60    readonly attribute Accessible caption;
  61    /**
  62     * An accessible object which summarizes the contents of a Table.
  63     * This object is frequently itself a Table instance, albeit a simplified one.
  64     */
  65    readonly attribute Accessible summary;
  66    /**
  67     * The number of rows currently selected.
  68     * A selected row is one in which all included cells are selected.
  69     * @note Not all tables support row selection.
  70     */
  71    readonly attribute long nSelectedRows;
  72    /**
  73     * The number of columns currently selected.
  74     * A selected column is one in which all included cells are selected.
  75     * @note Not all tables support column selection.
  76     */
  77    readonly attribute long nSelectedColumns;
  78    /**
  79     * Get the table cell at the specified row and column indices.
  80     * @note    To get the accessible object at a particular (x, y) screen coordinate,
  81     *          use Accessible::getAccessibleAtPoint ().
  82     *
  83     * @param row: the specified table row, zero-indexed.
  84     * @param column: the specified table column, zero-indexed.
  85     *
  86     * @returns an Accessible object representing the specified table cell.
  87     **/
  88    Accessible getAccessibleAt (in long row, in long column);
  89    /**
  90     * Get the 1-D child index corresponding to the specified 2-D row and column indices.
  91     * @note    To get the accessible object at a particular (x, y) screen coordinate,
  92     *          use Accessible::getAccessibleAtPoint.
  93     *
  94     * @param row: the specified table row, zero-indexed.
  95     * @param column: the specified table column, zero-indexed.
  96     *
  97     * @see getRowAtIndex, getColumnAtIndex
  98     *
  99     * @returns a long integer which serves as the index of a specified cell in the
 100     *          table, in a form usable by Accessible::getChildAtIndex.
 101     **/
 102    long getIndexAt (in long row, in long column);
 103    /**
 104     * Get the table row index occupied by the child at a particular 1-D child index.
 105     *
 106     * @param index: the specified child index, zero-indexed.
 107     *
 108     * @see getIndexAt(), getColumnAtIndex()
 109     *
 110     * @returns a long integer indicating the first row spanned by the child of a
 111     *          table, at the specified 1-D (zero-offset) \c index.
 112     **/
 113    long getRowAtIndex (in long index);
 114    /**
 115     * Get the table column index occupied by the child at a particular 1-D child index.
 116     *
 117     * @param index: the specified child index, zero-indexed.
 118     *
 119     * @see getIndexAt(), getRowAtIndex()
 120     *
 121     * @returns a long integer indicating the first column spanned by the child of a
 122     *          table, at the specified 1-D (zero-offset) \c index.
 123     **/
 124    long getColumnAtIndex (in long index);
 125    /**
 126     * Get a text description of a particular table row.  This differs from
 127     * AccessibleTable_getRowHeader, which returns an Accessible.
 128     * @param row: the specified table row, zero-indexed.
 129     *
 130     * @returns a UTF-8 string describing the specified table row, if available.
 131     **/
 132    string getRowDescription (in long row);
 133    /**
 134     * Get a text description of a particular table column.  This differs from
 135     * AccessibleTable_getColumnHeader, which returns an Accessible.
 136     * @param column: the specified table column, zero-indexed.
 137     *
 138     * @returns a UTF-8 string describing the specified table column, if available.
 139     **/
 140    string getColumnDescription (in long column);
 141    /**
 142     * Get the number of rows spanned by the table cell at the specific row and column.
 143     * (some tables can have cells which span multiple rows and/or columns).
 144     *
 145     * @param row: the specified table row, zero-indexed.
 146     * @param column: the specified table column, zero-indexed.
 147     *
 148     * @returns a long integer indicating the number of rows spanned by the specified cell.
 149     **/
 150    long getRowExtentAt (in long row, in long column);
 151    /**
 152     * Get the number of columns spanned by the table cell at the specific row and column.
 153     * (some tables can have cells which span multiple rows and/or columns).
 154     *
 155     * @param row: the specified table row, zero-indexed.
 156     * @param column: the specified table column, zero-indexed.
 157     *
 158     * @returns a long integer indicating the number of columns spanned by the
 159     * specified cell.
 160     **/
 161    long getColumnExtentAt (in long row, in long column);
 162    /**
 163     * Get the header associated with a table row, if available.  This differs from
 164     * getRowDescription, which returns a string.
 165     *
 166     * @param row: the specified table row, zero-indexed.
 167     *
 168     * @returns an Accessible representatin of the specified table row, if available.
 169     **/
 170    Accessible getRowHeader (in long row);
 171    /**
 172     * Get the header associated with a table column, if available, as an
 173     * instance of Accessible.  This differs from
 174     * getColumnDescription, which returns a string.
 175     *
 176     * @param column: the specified table column, zero-indexed.
 177     *
 178     * @returns an Accessible representatin of the specified table column, if available.
 179     **/
 180    Accessible getColumnHeader (in long column);
 181    /**
 182     * Obtain the indices of all rows which are currently selected.
 183     * @note Not all tables support row selection.
 184     *
 185     * @returns a sequence of integers comprising the indices of rows currently selected.
 186     **/
 187    LongSeq getSelectedRows ();
 188    /**
 189     * Obtain the indices of all columns which are currently selected.
 190     * @note Not all tables support column selection.
 191     *
 192     * @returns a sequence of integers comprising the indices of columns currently selected.
 193     **/
 194    LongSeq getSelectedColumns ();
 195    /**
 196     * Determine whether a table row is selected.
 197     * @note Not all tables support row selection.
 198     *
 199     * @param row: the row being queried.
 200     *
 201     * @returns \c True if the specified row is currently selected, \c False if not.
 202     **/
 203    boolean isRowSelected (in long row);
 204    /**
 205     * Determine whether a table column is selected.
 206     * @note Not all tables support column selection.
 207     *
 208     * @param column: the column being queried.
 209     *
 210     * @returns \c True if the specified column is currently selected, \c False if not.
 211     **/
 212    boolean isColumnSelected (in long column);
 213    /**
 214     * Determine whether the cell at a specific row and column is selected.
 215     * @param row a row occupied by the cell whose state is being queried.
 216     * @param column a column occupied by the cell whose state is being queried.
 217     *
 218     * @returns \c True if the specified cell is currently selected,
 219     * \c False if not.
 220     **/
 221    boolean isSelected (in long row, in long column);
 222    /**
 223     * Select the specified row, adding it to the current row selection,
 224     * if the table's selection model permits it.
 225     *
 226     * @param row
 227     * @note Possible reasons for addRowSelection to return \c False
 228     * include:
 229     * \li The table does not support Selection
 230     * \li The table row includes cells which do not have STATE_SELECTABLE
 231     * \li The table does not support selection by row
 232     * \li The table does not support selection of multiple rows, and
 233     * one row is already selected.
 234     * \li The table does not support non-contiguous selections (i.e.
 235     * does not include STATE_MULTISELECTABLE), and the specified row
 236     * would result in selection of non-contiguous rows.
 237     * \li The table does not support user-instigated selection.
 238     *
 239     * @returns \c True if the specified row was successfully selected,
 240     * \c False if not.
 241     **/
 242    boolean addRowSelection (in long row);
 243    /**
 244     * Select the specified column, adding it to the current column selection,
 245     * if the table's selection model permits it.
 246     *
 247     * @param column
 248     * @note Possible reasons for addColumnSelection to return \c False
 249     * include:
 250     * \li The table does not support Selection
 251     * \li The table column includes cells which do not have STATE_SELECTABLE
 252     * \li The table does not support selection by column
 253     * \li The table does not support selection of multiple columns, and
 254     * one column is already selected.
 255     * \li The table does not support non-contiguous selections (i.e.
 256     * does not include STATE_MULTISELECTABLE), and the specified column
 257     * would result in selection of non-contiguous columns.
 258     * \li The table does not support user-instigated selection.
 259     *
 260     * @returns \c True if the specified column was successfully selected,
 261     * \c False if not.
 262     **/
 263    boolean addColumnSelection (in long column);
 264    /**
 265     * Remove the specified row from current row selection,
 266     * if the table's selection model permits it.
 267     *
 268     * @param row
 269     * @note Possible reasons for removeRowSelection to return \c False
 270     * include:
 271     * \li The table does not support user-instigated Selection
 272     * \li The table has no selected rows or does not support deselection by row
 273     *
 274     * @returns \c True if the specified row was successfully de-selected,
 275     * \c False if not.
 276     **/
 277    boolean removeRowSelection (in long row);
 278    /**
 279     * Remove the specified column from current column selection,
 280     * if the table's selection model permits it.
 281     *
 282     * @param column
 283     * @note Possible reasons for removeColumnSelection to return \c False
 284     * include:
 285     * \li The table does not support user-instigated modification of
 286     * selection state
 287     * \li The table has no selected columns or does not support
 288     * deselection by column.
 289     *
 290     * @returns \c True if the specified column was successfully de-selected,
 291     * \c False if not.
 292     **/
 293    boolean removeColumnSelection (in long column);
 294    /**
 295     * Given a child index, determine the row and column indices and
 296     * extents, and whether the cell is currently selected.  If
 297     * the child at \c index is not a cell (for instance, if it is
 298     * a summary, caption, etc.), \c False is returned.
 299     *
 300     * @param index the index of the Table child whose row/column
 301     * extents are requested.
 302     * @param row back-filled with the first table row associated with
 303     * the cell with child index \c index.
 304     * @param col back-filled with the first table column associated
 305     * with the cell with child index \c index.
 306     * @param row_extents back-filled with the number of table rows
 307     * across which child \c i extends.
 308     * @param col_extents back-filled with the number of table columns
 309     * across which child \c i extends.
 310     * @param is_selected a boolean which is back-filled with \c True
 311     * if the child at index \c i corresponds to a selected table cell,
 312     * \c False otherwise.
 313     *
 314     * Example:
 315     * If the Table child at index '6' extends across columns 5 and 6 of
 316     * row 2 of a Table instance, and is currently selected, then
 317     * \code
 318     * retval = table::getRowColumnExtentsAtIndex (6, row, col,
 319     *                                             row_extents,
 320     *                                             col_extents,
 321     *                                             is_selected);
 322     * \endcode
 323     * will return True, and after the call
 324     * \c row, \c col, \c row_extents, \c col_extents,
 325     * and \c is_selected will contain \c 2, \c 5, \c 1, \c 2, and
 326     * \c True, respectively.
 327     *
 328     * @returns \c True if the index is associated with a valid table
 329     * cell, \c False if the index does not correspond to a cell.  If
 330     * \c False is returned, the values of the out parameters are
 331     * undefined.
 332     *
 333     * @since AT-SPI 1.7.0
 334     **/
 335     boolean getRowColumnExtentsAtIndex (in long index, out long row,
 336                                         out long col,
 337                                         out long row_extents,
 338                                         out long col_extents,
 339                                         out boolean is_selected);
 340     /** \cond
 341      * unImplemented:
 342      *
 343      * placeholders for future expansion.
 344      */
 345     void unImplemented ();
 346     void unImplemented2 ();
 347     void unImplemented3 ();
 348     void unImplemented4 ();
 349     void unImplemented5 ();
 350     void unImplemented6 ();
 351     void unImplemented7 ();
 352     /** \endcond */
 353   };
 354 };