X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=idl%2FAccessibility_Table.idl;h=a995ba31a8573ee995dd5c56ea679b39a19e2271;hb=f346af9d38b2a69945543e38e1109ddb8131c886;hp=66e0301c4e2d7c81f37e456d37c55cf51278e402;hpb=3af8a4e874f524c212a01e4469db1c8043f1427f;p=platform%2Fcore%2Fuifw%2Fat-spi2-atk.git diff --git a/idl/Accessibility_Table.idl b/idl/Accessibility_Table.idl index 66e0301..a995ba3 100644 --- a/idl/Accessibility_Table.idl +++ b/idl/Accessibility_Table.idl @@ -26,34 +26,318 @@ 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. @@ -65,6 +349,6 @@ typedef sequence LongSeq; void unImplemented5 (); void unImplemented6 (); void unImplemented7 (); - void unImplemented8 (); + /** \endcond */ }; };