xml/org.freedesktop.atspi.Table.xml

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