other-licenses/ia2/AccessibleTable.idl

   1 /*************************************************************************
   2  *
   3  *  File Name (AccessibleTable.idl)
   4  *
   5  *  IAccessible2 IDL Specification
   6  *
   7  *  Copyright (c) 2007, 2013 Linux Foundation
   8  *  Copyright (c) 2006 IBM Corporation
   9  *  Copyright (c) 2000, 2006 Sun Microsystems, Inc.
  10  *  All rights reserved.
  11  *
  12  *
  13  *  Redistribution and use in source and binary forms, with or without
  14  *  modification, are permitted provided that the following conditions
  15  *  are met:
  16  *
  17  *   1. Redistributions of source code must retain the above copyright
  18  *      notice, this list of conditions and the following disclaimer.
  19  *
  20  *   2. Redistributions in binary form must reproduce the above
  21  *      copyright notice, this list of conditions and the following
  22  *      disclaimer in the documentation and/or other materials
  23  *      provided with the distribution.
  24  *
  25  *   3. Neither the name of the Linux Foundation nor the names of its
  26  *      contributors may be used to endorse or promote products
  27  *      derived from this software without specific prior written
  28  *      permission.
  29  *
  30  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
  31  *  CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
  32  *  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  33  *  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  34  *  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
  35  *  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  36  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  37  *  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  38  *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  39  *  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  40  *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  41  *  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  42  *  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  43  *
  44  *  This BSD License conforms to the Open Source Initiative "Simplified
  45  *  BSD License" as published at:
  46  *  http://www.opensource.org/licenses/bsd-license.php
  47  *
  48  *  IAccessible2 is a trademark of the Linux Foundation. The IAccessible2
  49  *  mark may be used in accordance with the Linux Foundation Trademark
  50  *  Policy to indicate compliance with the IAccessible2 specification.
  51  *
  52  ************************************************************************/
  53
  54 import "objidl.idl";
  55 import "oaidl.idl";
  56 import "oleacc.idl";
  57 import "Accessible2.idl";
  58 import "IA2CommonTypes.idl";
  59
  60 /** @brief This interface gives access to a two-dimensional table.
  61
  62  Typically all accessible objects that represent cells or cell-clusters of a table
  63   will be at the same time children of the table.  In this case IAccessible2::indexInParent
  64   will return the child index which then can be used when calling IAccessibleTable::rowIndex
  65   and IAccessibleTable::columnIndex.
  66
  67  However, in some cases that kind of implementation will not be possible.  When
  68   the table cells are not direct children of a table, the object representing
  69   the cell can define a "table-cell-index" object attribute identifying the 0
  70   based table cell index.  This object attribute is obtained by parsing the
  71   attribute string returned by IAccessible2::attributes.  The "table-cell-index"
  72   attribute can be used just like a child index of the typical case.  ATs should
  73   first test for the presence of the "table-cell-index" attribute and if it is not
  74   present then IAccessible2::indexInParent can be used as in the typical case
  75   where cells are direct children of the table.
  76
  77  The range of valid coordinates for this interface are implementation dependent.
  78   However, that range includes at least the intervals from the from the first row
  79   or column with the index 0 up to the last (but not including) used row or column
  80   as returned by IAccessibleTable::nRows and IAccessibleTable::nColumns.
  81
  82  Note that newer implementations are now using IAccessibleTable2 and IAccessibleTableCell
  83   rather than this interface.
  84 */
  85 [object, uuid(35AD8070-C20C-4fb4-B094-F4F7275DD469)]
  86 interface IAccessibleTable : IUnknown
  87 {
  88
  89   /** @brief Returns the accessible object at the specified row and column in
  90     the table.  This object could be an IAccessible or an IAccessible2.
  91    @param [in] row
  92     The 0 based row index for which to retrieve the cell.
  93    @param [in] column
  94     The 0 based column index for which to retrieve the cell.
  95    @param [out] accessible
  96     If both row and column index are valid then the corresponding accessible
  97     object is returned that represents the requested cell regardless of whether
  98     the cell is currently visible (on the screen).
  99    @retval S_OK
 100    @retval E_INVALIDARG if bad [in] passed, [out] value is NULL
 101   */
 102   [propget] HRESULT accessibleAt
 103     (
 104      [in] long row,
 105      [in] long column,
 106      [out, retval] IUnknown **accessible
 107     );
 108
 109   /** @brief Returns the caption for the table.  The returned object could be
 110     an IAccessible or an IAccessible2.
 111    @param [out] accessible
 112     If the table has a caption then a reference to it is returned, else a NULL
 113     pointer is returned.
 114    @retval S_OK
 115    @retval S_FALSE if there is nothing to return, [out] value is NULL
 116   */
 117   [propget] HRESULT caption
 118     (
 119      [out, retval] IUnknown **accessible
 120     );
 121
 122   /** @brief Translates the given row and column indexes into the corresponding cell index.
 123    @param [in] rowIndex
 124     0 based row index for the cell.
 125    @param [in] columnIndex
 126     0 based column index for the cell.
 127    @param [out] cellIndex
 128     Returns the 0 based index of the cell at the specified row and column indexes.
 129    @retval S_OK
 130    @retval E_INVALIDARG if bad [in] passed, [out] value is 0
 131    @note The returned value is not necessarily a child index of the immediate parent.
 132     In cases where the table cells are not direct children of the table the index
 133     is actually the cell index, i.e. conceptually it's an index into a one dimensional
 134         array of cells laid out in row order.
 135   */
 136   [propget] HRESULT childIndex
 137         (
 138          [in] long rowIndex,
 139          [in] long columnIndex,
 140          [out, retval] long *cellIndex
 141         );
 142
 143   /** @brief Returns the description text of the specified column in the table.
 144    @param [in] column
 145     The 0 based index of the column for which to retrieve the description.
 146    @param [out] description
 147     Returns the description text of the specified column in the table if such a
 148     description exists.  Otherwise a NULL pointer is returned.
 149    @retval S_OK
 150    @retval S_FALSE if there is nothing to return, [out] value is NULL
 151    @retval E_INVALIDARG if bad [in] passed, [out] value is NULL
 152   */
 153   [propget] HRESULT columnDescription
 154     (
 155      [in] long column,
 156      [out, retval] BSTR *description
 157     );
 158
 159   /** @brief Returns the number of columns occupied by the accessible object
 160     at the specified row and column in the table.
 161
 162    The result is greater than 1 if the specified cell spans multiple columns.
 163    @param [in] row
 164     0 based row index of the accessible for which to return the column extent.
 165    @param [in] column
 166     0 based column index of the accessible for which to return the column extent.
 167    @param [out] nColumnsSpanned
 168     Returns the 1 based column extent of the specified cell.
 169    @retval S_OK
 170    @retval E_INVALIDARG if bad [in] passed, [out] value is 0
 171   */
 172   [propget] HRESULT columnExtentAt
 173     (
 174      [in] long row,
 175      [in] long column,
 176      [out, retval] long *nColumnsSpanned
 177     );
 178
 179   /** @brief Returns the column headers as an %IAccessibleTable object.
 180
 181    Content and size of the returned table are implementation dependent.
 182    @param [out] accessibleTable
 183     The column header
 184    @param [out] startingRowIndex
 185     The 0 based row index where the header starts, usually 0.
 186    @retval S_OK
 187    @retval S_FALSE if there is no header, [out] values are NULL and 0 respectively
 188   */
 189   [propget] HRESULT columnHeader
 190     (
 191      [out] IAccessibleTable **accessibleTable,
 192          [out, retval] long *startingRowIndex
 193     );
 194
 195   /** @brief Translates the given cell index into the corresponding column index.
 196    @param [in] cellIndex
 197     0 based index of the cell in the parent or closest ancestor table.  Typically this
 198         is the value returned from IAccessible2::indexInParent, but in the case where the
 199         table cells are not direct children of the table this is the cell index specified
 200         by the "table-cell-index" object attribute obtained from parsing the attributes
 201         string returned by calling IAccessible2::attributes on the cell object.
 202    @param [out] columnIndex
 203     Returns the 0 based column index of the cell of the specified child or the index of
 204     the first column if the child spans multiple columns.
 205    @retval S_OK
 206    @retval E_INVALIDARG if bad [in] passed, [out] value is 0
 207   */
 208   [propget] HRESULT columnIndex
 209     (
 210          [in] long cellIndex,
 211          [out, retval] long *columnIndex
 212         );
 213
 214   /** @brief Returns the total number of columns in table
 215    @param [out] columnCount
 216     Number of columns in table (including columns outside the current viewport)
 217    @retval S_OK
 218   */
 219   [propget] HRESULT nColumns
 220     (
 221      [out, retval] long *columnCount
 222     );
 223
 224   /** @brief Returns the total number of rows in table
 225    @param [out] rowCount
 226     Number of rows in table (including rows outside the current viewport)
 227    @retval S_OK
 228   */
 229   [propget] HRESULT nRows
 230     (
 231      [out, retval] long *rowCount
 232     );
 233
 234   /** @brief Returns the total number of selected cells
 235    @param [out] cellCount
 236     Number of cells currently selected
 237    @retval S_OK
 238   */
 239   [propget] HRESULT nSelectedChildren
 240     (
 241          [out, retval] long *cellCount
 242         );
 243
 244   /** @brief Returns the total number of selected columns
 245    @param [out] columnCount
 246     Number of columns currently selected
 247    @retval S_OK
 248   */
 249   [propget] HRESULT nSelectedColumns
 250     (
 251      [out, retval] long *columnCount
 252     );
 253
 254   /** @brief Returns the total number of selected rows
 255    @param [out] rowCount
 256     Number of rows currently selected
 257    @retval S_OK
 258   */
 259   [propget] HRESULT nSelectedRows
 260     (
 261      [out, retval] long *rowCount
 262     );
 263
 264   /** @brief Returns the description text of the specified row in the table.
 265    @param [in] row
 266     The 0 based index of the row for which to retrieve the description.
 267    @param [out] description
 268     Returns the description text of the specified row in the table if such a
 269     description exists.  Otherwise a NULL pointer is returned.
 270    @retval S_OK
 271    @retval S_FALSE if there is nothing to return, [out] value is NULL
 272    @retval E_INVALIDARG if bad [in] passed, [out] value is NULL
 273   */
 274   [propget] HRESULT rowDescription
 275     (
 276      [in] long row,
 277      [out, retval] BSTR *description
 278     );
 279
 280   /** @brief Returns the number of rows occupied by the accessible object
 281     at the specified row and column in the table.
 282
 283    The result is greater than 1 if the specified cell spans multiple rows.
 284    @param [in] row
 285     0 based row index of the accessible for which to return the row extent.
 286    @param [in] column
 287     0 based column index of the accessible for which to return the row extent.
 288    @param [out] nRowsSpanned
 289     Returns the row extent of the specified cell.
 290    @retval S_OK
 291    @retval E_INVALIDARG if bad [in] passed, [out] value is 0
 292   */
 293   [propget] HRESULT rowExtentAt
 294     (
 295      [in] long row,
 296      [in] long column,
 297      [out, retval] long *nRowsSpanned
 298     );
 299
 300   /** @brief Returns the row headers as an %IAccessibleTable object.
 301
 302    Content and size of the returned table are implementation dependent.
 303    @param [out] accessibleTable
 304     The row header.
 305    @param [out] startingColumnIndex
 306     The 0 based column index where the header starts, usually 0.
 307    @retval S_OK
 308    @retval S_FALSE if there is no header, [out] values are NULL and 0 respectively
 309   */
 310   [propget] HRESULT rowHeader
 311     (
 312      [out] IAccessibleTable **accessibleTable,
 313          [out, retval] long *startingColumnIndex
 314     );
 315
 316   /** @brief Translates the given cell index into a row index.
 317    @param [in] cellIndex
 318     0 based index of the cell in the parent or closest ancestor table.  Typically this
 319         is the value returned from IAccessible2::indexInParent, but in the case where the
 320         table cells are not direct children of the table this is the cell index specified
 321         by the "table-cell-index" object attribute obtained from parsing the attributes
 322         string returned by calling IAccessible2::attributes on the cell object.
 323    @param [out] rowIndex
 324     0 based row index
 325    @retval S_OK
 326    @retval E_INVALIDARG if bad [in] passed, [out] value is 0
 327   */
 328   [propget] HRESULT rowIndex
 329     (
 330          [in] long cellIndex,
 331          [out, retval] long *rowIndex
 332         );
 333
 334   /** @brief Returns a list of cell indexes currently selected (0 based).
 335    @param [in] maxChildren
 336     This parameter is ignored. Refer to @ref _arrayConsideration
 337         "Special Consideration when using Arrays" for more details.
 338    @param [out] children
 339     An array of cell indexes of selected cells (each index is 0 based),
 340         allocated by the server. The client must free it with CoTaskMemFree.
 341    @param [out] nChildren
 342     The number of cell indexes returned; the size of the returned array.
 343    @retval S_OK
 344    @retval S_FALSE if there are none, [out] values are NULL and 0 respectively
 345   */
 346   [propget] HRESULT selectedChildren
 347     (
 348      [in] long maxChildren,
 349      [out, size_is(,maxChildren), length_is(,*nChildren)] long **children,
 350      [out, retval] long *nChildren
 351     );
 352
 353   /** @brief Returns a list of column indexes currently selected (0 based).
 354    @param [in] maxColumns
 355     This parameter is ignored. Refer to @ref _arrayConsideration
 356         "Special Consideration when using Arrays" for more details.
 357    @param [out] columns
 358         An array of column indexes of selected columns (each index is 0 based), allocated
 359         by the server. The client must free it with CoTaskMemFree.
 360    @param [out] nColumns
 361     The number of column indexes returned; the size of the returned array.
 362    @retval S_OK
 363    @retval S_FALSE if there are none, [out] values are NULL and 0 respectively
 364   */
 365   [propget] HRESULT selectedColumns
 366     (
 367      [in] long maxColumns,
 368      [out, size_is(,maxColumns), length_is(,*nColumns)] long **columns,
 369      [out, retval] long *nColumns
 370     );
 371
 372   /** @brief Returns a list of row indexes currently selected (0 based).
 373    @param [in] maxRows
 374     This parameter is ignored. Refer to @ref _arrayConsideration
 375         "Special Consideration when using Arrays" for more details.
 376    @param [out] rows
 377     An array of row indexes of selected rows (each index is 0 based), allocated
 378         by the server. The client must free it with CoTaskMemFree.
 379    @param [out] nRows
 380     The number of row indexes returned; the size of the returned array.
 381    @retval S_OK
 382    @retval S_FALSE if there are none, [out] values are NULL and 0 respectively
 383   */
 384   [propget] HRESULT selectedRows
 385     (
 386      [in] long maxRows,
 387      [out, size_is(,maxRows), length_is(,*nRows)] long **rows,
 388      [out, retval] long *nRows
 389     );
 390
 391   /** @brief Returns the summary description of the table.  The returned object could be
 392     an IAccessible or an IAccessible2.
 393    @param [out] accessible
 394     Returns a reference to an implementation dependent accessible object
 395     representing the table's summary or a NULL pointer if the table
 396     does not support a summary.
 397    @retval S_OK
 398    @retval S_FALSE if there is nothing to return, [out] value is NULL
 399   */
 400   [propget] HRESULT summary
 401     (
 402      [out, retval] IUnknown **accessible
 403     );
 404
 405   /** @brief Returns a boolean value indicating whether the specified column is
 406     completely selected.
 407    @param [in] column
 408     0 based index of the column for which to determine whether it is selected.
 409    @param [out] isSelected
 410     Returns TRUE if the specified column is selected completely and FALSE otherwise.
 411    @retval S_OK
 412    @retval E_INVALIDARG if bad [in] passed, [out] value is FALSE
 413   */
 414   [propget] HRESULT isColumnSelected
 415     (
 416      [in] long column,
 417      [out, retval] boolean *isSelected
 418     );
 419
 420   /** @brief Returns a boolean value indicating whether the specified row is completely
 421     selected.
 422    @param [in] row
 423     0 based index of the row for which to determine whether it is selected.
 424    @param [out] isSelected
 425     Returns TRUE if the specified row is selected completely and FALSE otherwise.
 426    @retval S_OK
 427    @retval E_INVALIDARG if bad [in] passed, [out] value is FALSE
 428   */
 429   [propget] HRESULT isRowSelected
 430     (
 431      [in] long row,
 432      [out, retval] boolean *isSelected
 433     );
 434
 435   /** @brief Returns a boolean value indicating whether the specified cell is selected.
 436    @param [in] row
 437     0 based index of the row for the cell to determine whether it is selected.
 438    @param [in] column
 439     0 based index of the column for the cell to determine whether it is selected.
 440    @param [out] isSelected
 441     Returns TRUE if the specified cell is selected and FALSE otherwise.
 442    @retval S_OK
 443    @retval E_INVALIDARG if bad [in] passed, [out] value is FALSE
 444   */
 445   [propget] HRESULT isSelected
 446     (
 447      [in] long row,
 448      [in] long column,
 449      [out, retval] boolean *isSelected
 450     );
 451
 452   /** @brief Selects a row and unselects all previously selected rows.
 453    @param [in] row
 454     0 based index of the row to be selected.
 455    @retval S_OK
 456    @retval E_INVALIDARG if bad [in] passed
 457   */
 458   HRESULT selectRow
 459     (
 460      [in] long row
 461     );
 462
 463   /** @brief Selects a column and unselects all previously selected columns.
 464    @param [in] column
 465     0 based index of the column to be selected.
 466    @retval S_OK
 467    @retval E_INVALIDARG if bad [in] passed
 468   */
 469   HRESULT selectColumn
 470     (
 471      [in] long column
 472     );
 473
 474   /** @brief Unselects one row, leaving other selected rows selected (if any).
 475    @param [in] row
 476     0 based index of the row to be unselected.
 477    @retval S_OK
 478    @retval E_INVALIDARG if bad [in] passed
 479   */
 480   HRESULT unselectRow
 481     (
 482      [in] long row
 483     );
 484
 485   /** @brief Unselects one column, leaving other selected columns selected (if any).
 486    @param [in] column
 487     0 based index of the column to be unselected.
 488    @retval S_OK
 489    @retval E_INVALIDARG if bad [in] passed
 490   */
 491   HRESULT unselectColumn
 492     (
 493      [in] long column
 494     );
 495
 496   /** @brief Given a cell index, gets the row and column indexes and extents of a cell
 497     and whether or not it is selected.
 498
 499    This is a convenience function.  It is not mandatory to implement it.
 500    @param [in] index
 501     0 based index of this cell in the table.
 502    @param [out] row
 503     0 based row index.
 504    @param [out] column
 505     0 based column index.
 506    @param [out] rowExtents
 507     Number of cells spanned by this cell in this row.
 508    @param [out] columnExtents
 509     Number of cells spanned by this cell in this column.
 510    @param [out] isSelected
 511     Indicates if the specified cell is selected.
 512    @retval S_OK
 513    @retval E_INVALIDARG if bad [in] passed, [out] values are 0s and FALSE respectively
 514   */
 515   [propget] HRESULT rowColumnExtentsAtIndex
 516     (
 517          [in] long index,
 518          [out] long *row,
 519          [out] long *column,
 520          [out] long *rowExtents,
 521          [out] long *columnExtents,
 522          [out, retval] boolean *isSelected
 523         );
 524
 525   /** @brief Returns the type and extents describing how a table changed.
 526
 527    Provided for use by the IA2_EVENT_TABLE_MODEL_CHANGED event handler.
 528
 529    This data is only guaranteed to be valid while the thread notifying the event
 530    continues. Once the handler has returned, the validity of the data depends on
 531    how the server manages the life cycle of its objects. Also, note that the server
 532    may have different life cycle management strategies for controls depending on
 533    whether or not a control manages its children. Lists, trees, and tables can have
 534    a large number of children and thus it's possible that the child objects for those
 535    controls would only be created as needed. Servers should document their life cycle
 536    strategy as this will be of interest to assistive technology or script engines
 537    accessing data out of process or from other threads. Servers only need to save the
 538    most recent row and column values associated with the change and a scope of the
 539    entire application is adequate.
 540
 541    @param [out] modelChange
 542     A struct of (type(insert, delete, update), firstRow, lastRow, firstColumn, lastColumn).
 543    @retval S_OK
 544    @retval S_FALSE if there is nothing to return, [out] value is NULL
 545   */
 546   [propget] HRESULT modelChange
 547     (
 548          [out, retval] IA2TableModelChange *modelChange
 549     );
 550
 551 }