xml/org.freedesktop.atspi.Table.xml

   1 <node name="/node" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   2
   3 <tp:title>AT-SPI - Assistive Technology Service Provider Interface </tp:title>
   4 <tp:copyright>Copyright 2008 Novell, Inc.</tp:copyright>
   5 <tp:copyright>Copyright 2001 Sun Microsystems, Inc.</tp:copyright>
   6 <tp:license xmlns="http://www.w3.org/1999/xhtml">
   7   <p>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.</p>
  11
  12   <p>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.</p>
  16
  17   <p>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.</p>
  21 </tp:license>
  22 <interface name="org.freedesktop.atspi.Table">
  23   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  24     <p>An interface used by containers whose contained data is arranged in
  25       a &quot;tabular&quot; (i.e.\ row-column) fashion.  Tables may resemble a two-dimensional
  26       grid, as in a spreadsheet, or may feature objects which span multiple rows and/or
  27       columns, but whose bounds are aligned on a row/column matrix.  Thus, the Table
  28       interface may be used to represent &quot;spreadsheets&quot; as well as &quot;frames&quot;.  </p>
  29
  30     <p>Objects within tables are children of the Table instance, and they may be referenced
  31       either via a child index or via a row/column pair.
  32       Their role may be ROLE_TABLE_CELL, but table 'cells' may have other roles as well.
  33       These 'cells' may implement other interfaces, such as Text, Action, Image,
  34       and Component, and should do so as appropriate to their onscreen representation
  35       and/or behavior.</p>
  36   </tp:docstring>
  37   <tp:property name="nRows" type="i" access="read">
  38   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  39     <p>The total number of rows in this table (including empty rows),
  40       exclusive of any rows which are programmatically hidden.
  41       Rows which are merely scrolled out of view are included.</p>
  42   </tp:docstring>
  43   </tp:property>
  44   <tp:property name="nColumns" type="i" access="read">
  45   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  46     <p>The total number of columns in this table (including empty columns),
  47       exclusive of columns which are programmatically hidden.
  48       Columns which are scrolled out of view or clipped by the current
  49       viewport are included. </p>
  50   </tp:docstring>
  51   </tp:property>
  52   <tp:property name="caption" type="o" access="read">
  53   <tp:docstring>
  54     An Accessible which represents of a caption for a Table.
  55   </tp:docstring>
  56   </tp:property>
  57   <tp:property name="summary" type="o" access="read">
  58   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  59     <p>An accessible object which summarizes the contents of a Table.
  60       This object is frequently itself a Table instance, albeit a simplified one.</p>
  61   </tp:docstring>
  62   </tp:property>
  63   <tp:property name="nSelectedRows" type="i" access="read">
  64   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  65     <p>The number of rows currently selected.
  66       A selected row is one in which all included cells are selected.
  67       @note Not all tables support row selection.</p>
  68   </tp:docstring>
  69   </tp:property>
  70   <tp:property name="nSelectedColumns" type="i" access="read">
  71   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  72     <p>The number of columns currently selected.
  73       A selected column is one in which all included cells are selected.
  74       @note Not all tables support column selection.</p>
  75   </tp:docstring>
  76   </tp:property>
  77   <method name="getAccessibleAt">
  78     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  79       <p>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 ().    </p>
  82     </tp:docstring>
  83     <arg direction="in" name="row" type="i">
  84     <tp:docstring>
  85       the specified table row, zero-indexed.
  86     </tp:docstring>
  87     </arg>
  88     <arg direction="in" name="column" type="i">
  89     <tp:docstring>
  90       the specified table column, zero-indexed.
  91     </tp:docstring>
  92     </arg>
  93     <arg direction="out" type="o" tp:type="Accessible">
  94     <tp:docstring>
  95       an Accessible object representing the specified table cell.
  96     </tp:docstring>
  97     </arg>
  98   </method>
  99   <method name="getIndexAt">
 100     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 101       <p>Get the 1-D child index corresponding to the specified 2-D row and column indices.
 102         @note    To get the accessible object at a particular (x, y) screen coordinate,
 103         use Accessible::getAccessibleAtPoint.    </p>
 104     </tp:docstring>
 105     <arg direction="in" name="row" type="i">
 106     <tp:docstring>
 107       the specified table row, zero-indexed.
 108     </tp:docstring>
 109     </arg>
 110     <arg direction="in" name="column" type="i">
 111     <tp:docstring>
 112       the specified table column, zero-indexed.@see getRowAtIndex, getColumnAtIndex
 113     </tp:docstring>
 114     </arg>
 115     <arg direction="out" type="i">
 116     <tp:docstring>
 117       a long integer which serves as the index of a specified cell in thetable, in a form usable by Accessible::getChildAtIndex.
 118     </tp:docstring>
 119     </arg>
 120   </method>
 121   <method name="getRowAtIndex">
 122     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 123       <p>Get the table row index occupied by the child at a particular 1-D child index.    </p>
 124     </tp:docstring>
 125     <arg direction="in" name="index" type="i">
 126     <tp:docstring>
 127       the specified child index, zero-indexed.@see getIndexAt(), getColumnAtIndex()
 128     </tp:docstring>
 129     </arg>
 130     <arg direction="out" type="i">
 131     <tp:docstring>
 132       a long integer indicating the first row spanned by the child of atable, at the specified 1-D (zero-offset) \c index.
 133     </tp:docstring>
 134     </arg>
 135   </method>
 136   <method name="getColumnAtIndex">
 137     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 138       <p>Get the table column index occupied by the child at a particular 1-D child index.    </p>
 139     </tp:docstring>
 140     <arg direction="in" name="index" type="i">
 141     <tp:docstring>
 142       the specified child index, zero-indexed.@see getIndexAt(), getRowAtIndex()
 143     </tp:docstring>
 144     </arg>
 145     <arg direction="out" type="i">
 146     <tp:docstring>
 147       a long integer indicating the first column spanned by the child of atable, at the specified 1-D (zero-offset) \c index.
 148     </tp:docstring>
 149     </arg>
 150   </method>
 151   <method name="getRowDescription">
 152     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 153       <p>Get a text description of a particular table row.  This differs from
 154         AccessibleTable_getRowHeader, which returns an Accessible.</p>
 155     </tp:docstring>
 156     <arg direction="in" name="row" type="i">
 157     <tp:docstring>
 158       the specified table row, zero-indexed.
 159     </tp:docstring>
 160     </arg>
 161     <arg direction="out" type="s">
 162     <tp:docstring>
 163       a UTF-8 string describing the specified table row, if available.
 164     </tp:docstring>
 165     </arg>
 166   </method>
 167   <method name="getColumnDescription">
 168     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 169       <p>Get a text description of a particular table column.  This differs from
 170         AccessibleTable_getColumnHeader, which returns an Accessible.</p>
 171     </tp:docstring>
 172     <arg direction="in" name="column" type="i">
 173     <tp:docstring>
 174       the specified table column, zero-indexed.
 175     </tp:docstring>
 176     </arg>
 177     <arg direction="out" type="s">
 178     <tp:docstring>
 179       a UTF-8 string describing the specified table column, if available.
 180     </tp:docstring>
 181     </arg>
 182   </method>
 183   <method name="getRowExtentAt">
 184     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 185       <p>Get the number of rows spanned by the table cell at the specific row and column.
 186         (some tables can have cells which span multiple rows and/or columns).    </p>
 187     </tp:docstring>
 188     <arg direction="in" name="row" type="i">
 189     <tp:docstring>
 190       the specified table row, zero-indexed.
 191     </tp:docstring>
 192     </arg>
 193     <arg direction="in" name="column" type="i">
 194     <tp:docstring>
 195       the specified table column, zero-indexed.
 196     </tp:docstring>
 197     </arg>
 198     <arg direction="out" type="i">
 199     <tp:docstring>
 200       a long integer indicating the number of rows spanned by the specified cell.
 201     </tp:docstring>
 202     </arg>
 203   </method>
 204   <method name="getColumnExtentAt">
 205     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 206       <p>Get the number of columns spanned by the table cell at the specific row and column.
 207         (some tables can have cells which span multiple rows and/or columns).    </p>
 208     </tp:docstring>
 209     <arg direction="in" name="row" type="i">
 210     <tp:docstring>
 211       the specified table row, zero-indexed.
 212     </tp:docstring>
 213     </arg>
 214     <arg direction="in" name="column" type="i">
 215     <tp:docstring>
 216       the specified table column, zero-indexed.
 217     </tp:docstring>
 218     </arg>
 219     <arg direction="out" type="i">
 220     <tp:docstring>
 221       a long integer indicating the number of columns spanned by the specified cell.
 222     </tp:docstring>
 223     </arg>
 224   </method>
 225   <method name="getRowHeader">
 226     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 227       <p>Get the header associated with a table row, if available.  This differs from
 228         getRowDescription, which returns a string.    </p>
 229     </tp:docstring>
 230     <arg direction="in" name="row" type="i">
 231     <tp:docstring>
 232       the specified table row, zero-indexed.
 233     </tp:docstring>
 234     </arg>
 235     <arg direction="out" type="o" tp:type="Accessible">
 236     <tp:docstring>
 237       an Accessible representatin of the specified table row, if available.
 238     </tp:docstring>
 239     </arg>
 240   </method>
 241   <method name="getColumnHeader">
 242     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 243       <p>Get the header associated with a table column, if available, as an
 244         instance of Accessible.  This differs from
 245         getColumnDescription, which returns a string.    </p>
 246     </tp:docstring>
 247     <arg direction="in" name="column" type="i">
 248     <tp:docstring>
 249       the specified table column, zero-indexed.
 250     </tp:docstring>
 251     </arg>
 252     <arg direction="out" type="o" tp:type="Accessible">
 253     <tp:docstring>
 254       an Accessible representatin of the specified table column, if available.
 255     </tp:docstring>
 256     </arg>
 257   </method>
 258   <method name="getSelectedRows">
 259     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 260       <p>Obtain the indices of all rows which are currently selected.
 261         @note Not all tables support row selection.    </p>
 262     </tp:docstring>
 263     <arg direction="out" type="ai" tp:type="LongSeq">
 264     <tp:docstring>
 265       a sequence of integers comprising the indices of rows currently selected.
 266     </tp:docstring>
 267     </arg>
 268   </method>
 269   <method name="getSelectedColumns">
 270     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 271       <p>Obtain the indices of all columns which are currently selected.
 272         @note Not all tables support column selection.    </p>
 273     </tp:docstring>
 274     <arg direction="out" type="ai" tp:type="LongSeq">
 275     <tp:docstring>
 276       a sequence of integers comprising the indices of columns currently selected.
 277     </tp:docstring>
 278     </arg>
 279   </method>
 280   <method name="isRowSelected">
 281     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 282       <p>Determine whether a table row is selected.
 283         @note Not all tables support row selection.    </p>
 284     </tp:docstring>
 285     <arg direction="in" name="row" type="i">
 286     <tp:docstring>
 287       the row being queried.
 288     </tp:docstring>
 289     </arg>
 290     <arg direction="out" type="b" tp:type="boolean">
 291     <tp:docstring>
 292       \c True if the specified row is currently selected, \c False if not.
 293     </tp:docstring>
 294     </arg>
 295   </method>
 296   <method name="isColumnSelected">
 297     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 298       <p>Determine whether a table column is selected.
 299         @note Not all tables support column selection.    </p>
 300     </tp:docstring>
 301     <arg direction="in" name="column" type="i">
 302     <tp:docstring>
 303       the column being queried.
 304     </tp:docstring>
 305     </arg>
 306     <arg direction="out" type="b" tp:type="boolean">
 307     <tp:docstring>
 308       \c True if the specified column is currently selected, \c False if not.
 309     </tp:docstring>
 310     </arg>
 311   </method>
 312   <method name="isSelected">
 313     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 314       <p>Determine whether the cell at a specific row and column is selected.
 315         @param row a row occupied by the cell whose state is being queried.
 316         @param column a column occupied by the cell whose state is being queried.    </p>
 317     </tp:docstring>
 318     <arg direction="in" name="row" type="i"/>
 319     <arg direction="in" name="column" type="i"/>
 320     <arg direction="out" type="b" tp:type="boolean">
 321     <tp:docstring>
 322       \c True if the specified cell is currently selected, \c False if not.
 323     </tp:docstring>
 324     </arg>
 325   </method>
 326   <method name="addRowSelection">
 327     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 328       <p>Select the specified row, adding it to the current row selection,
 329         if the table's selection model permits it.    </p>
 330
 331       <p>@param row
 332         @note Possible reasons for addRowSelection to return \c False
 333         include:
 334         \li The table does not support Selection
 335         \li The table row includes cells which do not have STATE_SELECTABLE
 336         \li The table does not support selection by row
 337         \li The table does not support selection of multiple rows, and
 338         one row is already selected.
 339         \li The table does not support non-contiguous selections (i.e.
 340         does not include STATE_MULTISELECTABLE), and the specified row
 341         would result in selection of non-contiguous rows.
 342         \li The table does not support user-instigated selection.    </p>
 343     </tp:docstring>
 344     <arg direction="in" name="row" type="i"/>
 345     <arg direction="out" type="b" tp:type="boolean">
 346     <tp:docstring>
 347       \c True if the specified row was successfully selected, \c False if not.
 348     </tp:docstring>
 349     </arg>
 350   </method>
 351   <method name="addColumnSelection">
 352     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 353       <p>Select the specified column, adding it to the current column selection,
 354         if the table's selection model permits it.    </p>
 355
 356       <p>@param column
 357         @note Possible reasons for addColumnSelection to return \c False
 358         include:
 359         \li The table does not support Selection
 360         \li The table column includes cells which do not have STATE_SELECTABLE
 361         \li The table does not support selection by column
 362         \li The table does not support selection of multiple columns, and
 363         one column is already selected.
 364         \li The table does not support non-contiguous selections (i.e.
 365         does not include STATE_MULTISELECTABLE), and the specified column
 366         would result in selection of non-contiguous columns.
 367         \li The table does not support user-instigated selection.    </p>
 368     </tp:docstring>
 369     <arg direction="in" name="column" type="i"/>
 370     <arg direction="out" type="b" tp:type="boolean">
 371     <tp:docstring>
 372       \c True if the specified column was successfully selected, \c False if not.
 373     </tp:docstring>
 374     </arg>
 375   </method>
 376   <method name="removeRowSelection">
 377     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 378       <p>Remove the specified row from current row selection,
 379         if the table's selection model permits it.    </p>
 380
 381       <p>@param row
 382         @note Possible reasons for removeRowSelection to return \c False
 383         include:
 384         \li The table does not support user-instigated Selection
 385         \li The table has no selected rows or does not support deselection by row    </p>
 386     </tp:docstring>
 387     <arg direction="in" name="row" type="i"/>
 388     <arg direction="out" type="b" tp:type="boolean">
 389     <tp:docstring>
 390       \c True if the specified row was successfully de-selected, \c False if not.
 391     </tp:docstring>
 392     </arg>
 393   </method>
 394   <method name="removeColumnSelection">
 395     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 396       <p>Remove the specified column from current column selection,
 397         if the table's selection model permits it.    </p>
 398
 399       <p>@param column
 400         @note Possible reasons for removeColumnSelection to return \c False
 401         include:
 402         \li The table does not support user-instigated modification of
 403         selection state
 404         \li The table has no selected columns or does not support
 405         deselection by column.    </p>
 406     </tp:docstring>
 407     <arg direction="in" name="column" type="i"/>
 408     <arg direction="out" type="b" tp:type="boolean">
 409     <tp:docstring>
 410       \c True if the specified column was successfully de-selected, \c False if not.
 411     </tp:docstring>
 412     </arg>
 413   </method>
 414   <method name="getRowColumnExtentsAtIndex">
 415     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 416       <p>Given a child index, determine the row and column indices and
 417         extents, and whether the cell is currently selected.  If
 418         the child at \c index is not a cell (for instance, if it is
 419         a summary, caption, etc.), \c False is returned.    </p>
 420
 421       <p>@param index the index of the Table child whose row/column
 422         extents are requested.
 423         @param row back-filled with the first table row associated with
 424         the cell with child index \c index.
 425         @param col back-filled with the first table column associated
 426         with the cell with child index \c index.
 427         @param row_extents back-filled with the number of table rows
 428         across which child \c i extends.
 429         @param col_extents back-filled with the number of table columns
 430         across which child \c i extends.
 431         @param is_selected a boolean which is back-filled with \c True
 432         if the child at index \c i corresponds to a selected table cell,
 433         \c False otherwise.    </p>
 434
 435       <p>Example:
 436         If the Table child at index '6' extends across columns 5 and 6 of
 437         row 2 of a Table instance, and is currently selected, then
 438         \code
 439         retval = table::getRowColumnExtentsAtIndex (6, row, col,
 440         row_extents,
 441         col_extents,
 442         is_selected);
 443         \endcode
 444         will return True, and after the call
 445         \c row, \c col, \c row_extents, \c col_extents,
 446         and \c is_selected will contain \c 2, \c 5, \c 1, \c 2, and
 447         \c True, respectively.    </p>
 448     </tp:docstring>
 449     <arg direction="in" name="index" type="i"/>
 450     <arg direction="out" name="row" type="i"/>
 451     <arg direction="out" name="col" type="i"/>
 452     <arg direction="out" name="row_extents" type="i"/>
 453     <arg direction="out" name="col_extents" type="i"/>
 454     <arg direction="out" name="is_selected" type="b" tp:type="boolean"/>
 455     <arg direction="out" type="b" tp:type="boolean">
 456     <tp:docstring>
 457       \c True if the index is associated with a valid tablecell, \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
 458     </tp:docstring>
 459     </arg>
 460   </method>
 461   <method name="unImplemented">
 462     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 463       <p>\cond
 464         unImplemented:    </p>
 465
 466       <p>placeholders for future expansion.</p>
 467     </tp:docstring>
 468   </method>
 469   <method name="unImplemented2">
 470   </method>
 471   <method name="unImplemented3">
 472   </method>
 473   <method name="unImplemented4">
 474   </method>
 475   <method name="unImplemented5">
 476   </method>
 477   <method name="unImplemented6">
 478   </method>
 479   <method name="unImplemented7">
 480   </method>
 481 </interface>
 482 </node>