other-licenses/ia2/AccessibleTable.idl

   1 /*************************************************************************
   2  *
   3  *  File Name (AccessibleTable.idl)
   4  *
   5  *  IAccessible2 IDL Specification
   6  *
   7  *  Copyright (c) IBM Corp. 2007
   8  *  Copyright (c) Sun Microsystems, Inc. 2000, 2006
   9  *
  10  *  This library is free software; you can redistribute it and/or
  11  *  modify it under the terms of the GNU Lesser General Public
  12  *  License version 2.1, as published by the Free Software Foundation; either
  13  *  version 2.1 of the License, or (at your option) any later version.
  14  *
  15  *  This library is distributed in the hope that it will be useful,
  16  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  *  Lesser General Public License for more details.
  19  *
  20  *  You should have received a copy of the GNU Lesser General Public
  21  *  License along with this library; if not, write to the Free Software
  22  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02110-1301  USA
  23  *
  24  ************************************************************************/
  25
  26 import "objidl.idl";
  27 import "oaidl.idl";
  28 import "oleacc.idl";
  29 import "Accessible2.idl";
  30
  31 /// Defines values which specify the kind of change made to a table
  32 enum IA2TableModelChangeType {
  33   IA2_TABLE_MODEL_CHANGE_INSERT,  // = 0;
  34   IA2_TABLE_MODEL_CHANGE_DELETE,
  35   IA2_TABLE_MODEL_CHANGE_UPDATE
  36 };
  37
  38 /// A structure defining the type of and extents of changes made to a table
  39 typedef struct {
  40   enum IA2TableModelChangeType type;    // insert, delete, update
  41   long firstRow;
  42   long lastRow;
  43   long firstColumn;
  44   long lastColumn;
  45 } IA2TableModelChange;
  46
  47 /** @brief This interface gives access to a two-dimensional table.
  48
  49  All accessible objects that represent cells or cell-clusters of a table have
  50   to be at the same time children of the table.  This is necessary to be able
  51   to convert row and column indices into child indices and vice versa with the
  52   methods IAccessibleTable::childIndex, IAccessibleTable::rowIndex, and
  53   IAccessibleTable::columnIndex.
  54
  55  The range of valid coordinates for this interface are implementation dependent.
  56   However, that range includes at least the intervals from the from the first row
  57   or column with the index 0 up to the last (but not including) used row or column
  58   as returned by IAccessibleTable::nRows and IAccessibleTable::nColumns.
  59 */
  60 [object, uuid(35AD8070-C20C-4fb4-B094-F4F7275DD469)]
  61 interface IAccessibleTable : IUnknown
  62 {
  63
  64   /** @brief Returns the accessible object at the specified row and column in
  65     the table.  This object could be an IAccessible or an IAccessible2.
  66    @param [in] row
  67     The row index for which to retrieve the cell.
  68    @param [in] column
  69     The column index for which to retrieve the cell.
  70    @param [out] accessible
  71     If both row and column index are valid then the corresponding accessible
  72     object is returned that represents the requested cell regardless of whether
  73     the cell is currently visible (on the screen).
  74   */
  75   [propget] HRESULT accessibleAt
  76     (
  77      [in] long row,
  78      [in] long column,
  79      [out, retval] IUnknown **accessible
  80     );
  81
  82   /** @brief Returns the caption for the table.  The returned object could be
  83     an IAccessible or an IAccessible2.
  84    @param [out] accessible
  85     If the table has a caption then a reference to it is returned, else a NULL
  86     pointer is returned.
  87   */
  88   [propget] HRESULT caption
  89     (
  90      [out, retval] IUnknown **accessible
  91     );
  92
  93   /** @brief Translates the given row and column indices into the corresponding child index.
  94    @param [in] rowIndex
  95     Index of the child of the table for which to return the row index.
  96    @param [in] columnIndex
  97     Index of the child of the table for which to return the column index.
  98    @param [out] childIndex
  99     Returns the row index of the cell of the specified child or the index of
 100     the first row if the child spans multiple rows.
 101   */
 102   [propget] HRESULT childIndex
 103         (
 104          [in] long rowIndex,
 105          [in] long columnIndex,
 106          [out, retval] long *childIndex
 107         );
 108
 109   /** @brief Returns the description text of the specified column in the table.
 110    @param [in] column
 111     The index of the column for which to retrieve the description.
 112    @param [out] description
 113     Returns the description text of the specified row in the table if such a
 114     description exists.  Otherwise a NULL pointer is returned.
 115   */
 116   [propget] HRESULT columnDescription
 117     (
 118      [in] long column,
 119      [out, retval] BSTR *description
 120     );
 121
 122   /** @brief Returns the number of columns occupied by the accessible object
 123     at the specified row and column in the table.
 124
 125    The result differs from 1 if the specified cell spans multiple columns.
 126    @param [in] row
 127     Row index of the accessible for which to return the column extent.
 128    @param [in] column
 129     Column index of the accessible for which to return the column extent.
 130    @param [out] nColumnsSpanned
 131     Returns the column extent of the specified cell.
 132   */
 133   [propget] HRESULT columnExtentAt
 134     (
 135      [in] long row,
 136      [in] long column,
 137      [out, retval] long *nColumnsSpanned
 138     );
 139
 140   /** @brief Returns the column headers as an IAccessibleTable object.
 141
 142    Content and size of the returned table are implementation dependent.
 143    @param [out] accessibleTable
 144     The column header
 145    @param [out] startingRowIndex
 146     The row index where the header starts, usually 0.
 147   */
 148   [propget] HRESULT columnHeader
 149     (
 150      [out] IAccessibleTable **accessibleTable,
 151          [out, retval] long *startingRowIndex
 152     );
 153
 154   /** @brief Translates the given child index into the corresponding column index.
 155    @param [in] childIndex
 156     Index of the child of the table for which to return the column index.
 157    @param [out] columnIndex
 158     Returns the column index of the cell of the specified child or the index of
 159     the first column if the child spans multiple columns.
 160   */
 161   [propget] HRESULT columnIndex
 162     (
 163          [in] long childIndex,
 164          [out, retval] long *columnIndex
 165         );
 166
 167   /** @brief Returns the total number of columns in table
 168    @param [out] columnCount
 169     Number of columns in table (including columns outside the current viewport)
 170   */
 171   [propget] HRESULT nColumns
 172     (
 173      [out, retval] long *columnCount
 174     );
 175
 176   /** @brief Returns the total number of rows in table
 177    @param [out] rowCount
 178     Number of rows in table (including rows outside the current viewport)
 179   */
 180   [propget] HRESULT nRows
 181     (
 182      [out, retval] long *rowCount
 183     );
 184
 185   /** @brief Returns the total number of selected children
 186    @param [out] childCount
 187     Number of children currently selected
 188   */
 189   [propget] HRESULT nSelectedChildren
 190     (
 191          [out, retval] long *childCount
 192         );
 193
 194   /** @brief Returns the total number of selected columns
 195    @param [out] columnCount
 196     Number of columns currently selected
 197   */
 198   [propget] HRESULT nSelectedColumns
 199     (
 200      [out, retval] long *columnCount
 201     );
 202
 203   /** @brief Returns the total number of selected rows
 204    @param [out] rowCount
 205     Number of rows currently selected
 206   */
 207   [propget] HRESULT nSelectedRows
 208     (
 209      [out, retval] long *rowCount
 210     );
 211
 212   /** @brief Returns the description text of the specified row in the table.
 213    @param [in] row
 214     The index of the row for which to retrieve the description.
 215    @param [out] description
 216     Returns the description text of the specified row in the table if such a
 217     description exists.  Otherwise a NULL pointer is returned.
 218   */
 219   [propget] HRESULT rowDescription
 220     (
 221      [in] long row,
 222      [out, retval] BSTR *description
 223     );
 224
 225   /** @brief Returns the number of rows occupied by the accessible oject
 226     at the specified row and column in the table.
 227
 228    The result differs from 1 if the specified cell spans multiple rows.
 229    @param [in] row
 230     Row index of the accessible for which to return the column extent.
 231    @param [in] column
 232     Column index of the accessible for which to return the column extent.
 233    @param [out] nRowsSpanned
 234     Returns the row extent of the specified cell.
 235   */
 236   [propget] HRESULT rowExtentAt
 237     (
 238      [in] long row,
 239      [in] long column,
 240      [out, retval] long *nRowsSpanned
 241     );
 242
 243   /** @brief Returns the row headers as an IAccessibleTable object.
 244
 245    Content and size of the returned table are implementation dependent.
 246    @param [out] accessibleTable
 247     The row header.
 248    @param [out] startingColumnIndex
 249     The column index where the header starts, usually 0.
 250   */
 251   [propget] HRESULT rowHeader
 252     (
 253      [out] IAccessibleTable **accessibleTable,
 254          [out, retval] long *startingColumnIndex
 255     );
 256
 257   /** @brief Translates the given child index into a row index.
 258    @param [in] childIndex
 259     Index in parent (0 based)
 260    @param [out] rowIndex
 261     Row index (0 based)
 262   */
 263   [propget] HRESULT rowIndex
 264     (
 265          [in] long childIndex,
 266          [out, retval] long *rowIndex
 267         );
 268
 269   /** @brief Returns a list of child indexes currently selected (0-based).
 270    @param [in] maxChildren
 271     Max children requested (possibly from IAccessibleTable::nSelectedChildren)
 272    @param [out] children
 273     array of indexes of selected children (each index is 0-based)
 274    @param [out] nChildren
 275     Length of array (not more than maxChildren)
 276   */
 277   [propget] HRESULT selectedChildren
 278     (
 279      [in] long maxChildren,
 280      [out, size_is(,maxChildren), length_is(,*nChildren)] long **children,
 281      [out, retval] long *nChildren
 282     );
 283
 284   /** @brief Returns a list of column indexes currently selected (0-based).
 285    @param [in] maxColumns
 286     Max rows requested (possibly from IAccessibleTable::nSelectedColumns)
 287    @param [out] columns
 288     array of indexes of selected columns (each index is 0-based)
 289    @param [out] nColumns
 290     Length of array (not more than maxColumns)
 291   */
 292   [propget] HRESULT selectedColumns
 293     (
 294      [in] long maxColumns,
 295      [out, size_is(,maxColumns), length_is(,*nColumns)] long **columns,
 296      [out, retval] long *nColumns
 297     );
 298
 299   /** @brief Returns a list of row indexes currently selected (0-based).
 300    @param [in] maxRows
 301     Max rows requested (possibly from IAccessibleTable::nSelectedRows)
 302    @param [out] rows
 303     array of indexes of selected rows (each index is 0-based)
 304    @param [out] nRows
 305     Length of array (not more than maxRows)
 306   */
 307   [propget] HRESULT selectedRows
 308     (
 309      [in] long maxRows,
 310      [out, size_is(,maxRows), length_is(,*nRows)] long **rows,
 311      [out, retval] long *nRows
 312     );
 313
 314   /** @brief Returns the summary description of the table.  The returned object could be
 315     an IAccessible or an IAccessible2.
 316    @param [out] accessible
 317     Returns a reference to an implementation dependent accessible object
 318     representing the table's summary or a NULL pointer if the table
 319     does not support a summary.
 320   */
 321   [propget] HRESULT summary
 322     (
 323      [out, retval] IUnknown **accessible
 324     );
 325
 326   /** @brief Returns a boolean value indicating whether the specified column is
 327     completely selected.
 328    @param [in] column
 329     Index of the column for which to determine whether it is selected.
 330    @param [out] isSelected
 331     Returns TRUE if the specified column is selected completely and FALSE otherwise.
 332   */
 333   [propget] HRESULT isColumnSelected
 334     (
 335      [in] long column,
 336      [out, retval] boolean *isSelected
 337     );
 338
 339   /** @brief Returns a boolean value indicating whether the specified row is completely
 340     selected.
 341    @param [in] row
 342     Index of the row for which to determine whether it is selected.
 343    @param [out] isSelected
 344     Returns TRUE if the specified row is selected completely and FALSE otherwise.
 345   */
 346   [propget] HRESULT isRowSelected
 347     (
 348      [in] long row,
 349      [out, retval] boolean *isSelected
 350     );
 351
 352   /** @brief Returns a boolean value indicating whether the specified cell is selected.
 353    @param [in] row
 354     Index of the row for the cell to determine whether it is selected.
 355    @param [in] column
 356     Index of the column for the cell to determine whether it is selected.
 357    @param [out] isSelected
 358     Returns TRUE if the specified cell is selected and FALSE otherwise.
 359   */
 360   [propget] HRESULT isSelected
 361     (
 362      [in] long row,
 363      [in] long column,
 364      [out, retval] boolean *isSelected
 365     );
 366
 367   /** @brief Selects a row and unselects all previously selected rows.
 368    @param [in] row
 369     Index of the row to be selected.
 370   */
 371   HRESULT selectRow
 372     (
 373      [in] long row
 374     );
 375
 376   /** @brief Selects a column and unselects all previously selected columns.
 377    @param [in] column
 378     Index of the column to be selected.
 379   */
 380   HRESULT selectColumn
 381     (
 382      [in] long column
 383     );
 384
 385   /** @brief Unselects one row, leaving other selected rows selected (if any).
 386    @param [in] row
 387     Index of the row to be selected.
 388   */
 389   HRESULT unselectRow
 390     (
 391      [in] long row
 392     );
 393
 394   /** @brief Unselects one column, leaving other selected columns selected (if any).
 395    @param [in] column
 396     Index of the column to be selected.
 397   */
 398   HRESULT unselectColumn
 399     (
 400      [in] long column
 401     );
 402
 403   /** @brief Given a child index, gets the row and column indexes and extents of a cell
 404     and whether or not it is selected.
 405
 406    This is a convenience function.  It is not mandatory to implement it.
 407    @param [in] index
 408     Index of this child in the parent.
 409    @param [out] row
 410     Row index.
 411    @param [out] column
 412     Column index.
 413    @param [out] rowExtents
 414     Number of cells spanned by this cell in this row.
 415    @param [out] columnExtents
 416     Number of cells spanned by this cell in this column.
 417    @param [out] isSelected
 418     Indicates if the specified cell is selected.
 419   */
 420   [propget] HRESULT rowColumnExtentsAtIndex
 421     (
 422          [in] long index,
 423          [out] long *row,
 424          [out] long *column,
 425          [out] long *rowExtents,
 426          [out] long *columnExtents,
 427          [out, retval] boolean *isSelected
 428         );
 429
 430   /** @brief Returns the type and extents describing how a table changed.
 431
 432     Provided for use by the IA2_EVENT_TABLE_MODEL_CHANGED event handler.
 433    @param [out] modelChange
 434     A struct of (type(insert, delete, update), firstRow, lastRow, firstColumn, lastColumn).
 435   */
 436   [propget] HRESULT modelChange
 437     (
 438          [out, retval] IA2TableModelChange *modelChange
 439     );
 440
 441 }