home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / share / idl / at-spi-1.0 / Accessibility_Table.idl < prev    next >
Encoding:
Text File  |  2006-08-22  |  14.1 KB  |  355 lines
  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. };
  355.