other-licenses/ia2/AccessibleTable2.idl

   1 /*************************************************************************
   2  *
   3  *  File Name (AccessibleTable2.idl)
   4  *
   5  *  IAccessible2 IDL Specification
   6  *
   7  *  Copyright (c) 2007, 2012 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  Please also refer to the IAccessibleTableCell interface.
  63
  64  If you want to support older applications you should also support the
  65   IAccessibleTable inteface.
  66 */
  67 [object, uuid(6167f295-06f0-4cdd-a1fa-02e25153d869)]
  68 interface IAccessibleTable2 : IUnknown
  69 {
  70
  71   /** @brief Returns the accessible object at the specified row and column in
  72     the table.  This object could be an IAccessible or an IAccessible2.
  73    @param [in] row
  74     The 0 based row index for which to retrieve the cell.
  75    @param [in] column
  76     The 0 based column index for which to retrieve the cell.
  77    @param [out] cell
  78     If both row and column index are valid then the corresponding accessible
  79     object is returned that represents the requested cell regardless of whether
  80     the cell is currently visible (on the screen).
  81    @retval S_OK
  82    @retval E_INVALIDARG if bad [in] passed
  83   */
  84   [propget] HRESULT cellAt
  85     (
  86      [in] long row,
  87      [in] long column,
  88      [out, retval] IUnknown **cell
  89     );
  90
  91   /** @brief Returns the caption for the table.  The returned object could be
  92     an IAccessible or an IAccessible2.
  93    @param [out] accessible
  94     If the table has a caption then a reference to it is returned, else a NULL
  95     pointer is returned.
  96    @retval S_OK
  97    @retval S_FALSE if there is nothing to return, [out] value is NULL
  98    @deprecated use a describedBy relation
  99   */
 100   [propget] HRESULT caption
 101     (
 102      [out, retval] IUnknown **accessible
 103     );
 104
 105   /** @brief Returns the description text of the specified column in the table.
 106    @param [in] column
 107     The 0 based index of the column for which to retrieve the description.
 108    @param [out] description
 109     Returns the description text of the specified column in the table if such a
 110     description exists.  Otherwise a NULL pointer is returned.
 111    @retval S_OK
 112    @retval S_FALSE if there is nothing to return, [out] value is NULL
 113    @retval E_INVALIDARG if bad [in] passed
 114   */
 115   [propget] HRESULT columnDescription
 116     (
 117      [in] long column,
 118      [out, retval] BSTR *description
 119     );
 120
 121
 122   /** @brief Returns the total number of columns in table
 123    @param [out] columnCount
 124     Number of columns in table (including columns outside the current viewport)
 125    @retval S_OK
 126   */
 127   [propget] HRESULT nColumns
 128     (
 129      [out, retval] long *columnCount
 130     );
 131
 132   /** @brief Returns the total number of rows in table
 133    @param [out] rowCount
 134     Number of rows in table (including rows outside the current viewport)
 135    @retval S_OK
 136   */
 137   [propget] HRESULT nRows
 138     (
 139      [out, retval] long *rowCount
 140     );
 141
 142   /** @brief Returns the total number of selected cells
 143    @param [out] cellCount
 144     Number of cells currently selected
 145    @retval S_OK
 146   */
 147   [propget] HRESULT nSelectedCells
 148     (
 149      [out, retval] long *cellCount
 150     );
 151
 152   /** @brief Returns the total number of selected columns
 153    @param [out] columnCount
 154     Number of columns currently selected
 155    @retval S_OK
 156   */
 157   [propget] HRESULT nSelectedColumns
 158     (
 159      [out, retval] long *columnCount
 160     );
 161
 162   /** @brief Returns the total number of selected rows
 163    @param [out] rowCount
 164     Number of rows currently selected
 165    @retval S_OK
 166   */
 167   [propget] HRESULT nSelectedRows
 168     (
 169      [out, retval] long *rowCount
 170     );
 171
 172   /** @brief Returns the description text of the specified row in the table.
 173    @param [in] row
 174     The 0 based index of the row for which to retrieve the description.
 175    @param [out] description
 176     Returns the description text of the specified row in the table if such a
 177     description exists.  Otherwise a NULL pointer is returned.
 178    @retval S_OK
 179    @retval S_FALSE if there is nothing to return, [out] value is NULL
 180    @retval E_INVALIDARG if bad [in] passed
 181   */
 182   [propget] HRESULT rowDescription
 183     (
 184      [in] long row,
 185      [out, retval] BSTR *description
 186     );
 187
 188   /** @brief Returns a list of accessibles currently selected.
 189    @param [out] cells
 190     Pointer to an array of references to selected accessibles.  The array is
 191     allocated by the server with CoTaskMemAlloc and freed by the client with
 192     CoTaskMemFree.
 193    @param [out] nSelectedCells
 194     The number of accessibles returned; the size of the returned array.
 195    @retval S_OK
 196    @retval S_FALSE if there are none, [out] values are NULL and 0 respectively
 197   */
 198   [propget] HRESULT selectedCells
 199     (
 200      [out, size_is(,*nSelectedCells)] IUnknown ***cells,
 201      [out, retval] long *nSelectedCells
 202     );
 203
 204   /** @brief Returns a list of column indexes currently selected (0 based).
 205    @param [out] selectedColumns
 206     A pointer to an array of column indexes of selected columns (each index is
 207     0 based).  The array is allocated by the server with CoTaskMemAlloc and
 208     freed by the client with CoTaskMemFree.
 209    @param [out] nColumns
 210     The number of column indexes returned; the size of the returned array.
 211    @retval S_OK
 212    @retval S_FALSE if there are none, [out] values are NULL and 0 respectively
 213   */
 214   [propget] HRESULT selectedColumns
 215     (
 216      [out, size_is(,*nColumns)] long **selectedColumns,
 217      [out, retval] long *nColumns
 218     );
 219
 220   /** @brief Returns a list of row indexes currently selected (0 based).
 221    @param [out] selectedRows
 222     An array of row indexes of selected rows (each index is 0 based).  The array
 223     is allocated by the server with CoTaskMemAlloc and freed by the client with
 224     CoTaskMemFree.
 225    @param [out] nRows
 226     The number of row indexes returned; the size of the returned array.
 227    @retval S_OK
 228    @retval S_FALSE if there are none, [out] values are NULL and 0 respectively
 229   */
 230   [propget] HRESULT selectedRows
 231     (
 232      [out, size_is(,*nRows)] long **selectedRows,
 233      [out, retval] long *nRows
 234     );
 235
 236   /** @brief Returns the summary description of the table.  The returned object could be
 237     an IAccessible or an IAccessible2.
 238    @param [out] accessible
 239     Returns a reference to an implementation dependent accessible object
 240     representing the table's summary or a NULL pointer if the table
 241     does not support a summary.
 242    @retval S_OK
 243    @retval S_FALSE if there is nothing to return, [out] value is NULL
 244    @deprecated Use the labeledBy relation
 245   */
 246   [propget] HRESULT summary
 247     (
 248      [out, retval] IUnknown **accessible
 249     );
 250
 251   /** @brief Returns a boolean value indicating whether the specified column is
 252     completely selected.
 253    @param [in] column
 254     0 based index of the column for which to determine whether it is selected.
 255    @param [out] isSelected
 256     Returns TRUE if the specified column is selected completely and FALSE otherwise.
 257    @retval S_OK
 258    @retval E_INVALIDARG if bad [in] passed
 259   */
 260   [propget] HRESULT isColumnSelected
 261     (
 262      [in] long column,
 263      [out, retval] boolean *isSelected
 264     );
 265
 266   /** @brief Returns a boolean value indicating whether the specified row is completely
 267     selected.
 268    @param [in] row
 269     0 based index of the row for which to determine whether it is selected.
 270    @param [out] isSelected
 271     Returns TRUE if the specified row is selected completely and FALSE otherwise.
 272    @retval S_OK
 273    @retval E_INVALIDARG if bad [in] passed
 274   */
 275   [propget] HRESULT isRowSelected
 276     (
 277      [in] long row,
 278      [out, retval] boolean *isSelected
 279     );
 280
 281   /** @brief Selects a row and unselects all previously selected rows.
 282
 283    The behavior should mimic that of the application, but for those applications
 284     which do not have a means in the GUI to select a full row of cells the behavior
 285     should be as follows:  First any selected rows in the table are unselected.  Then
 286     the entire row of cells for the specified row is selected.  If any of the
 287     cells in the selected row span additional rows, the cells in those rows
 288     are also selected.
 289    @param [in] row
 290     0 based index of the row to be selected.
 291    @retval S_OK
 292    @retval E_INVALIDARG if bad [in] passed
 293   */
 294   HRESULT selectRow
 295     (
 296      [in] long row
 297     );
 298
 299   /** @brief Selects a column and unselects all previously selected columns.
 300
 301    The behavior should mimic that of the application, but for those applications
 302     which do not have a means in the GUI to select a full column of cells the behavior
 303     should be as follows:  First any selected columns in the table are unselected.  Then
 304     the entire column of cells for the specified column is selected.  If any of the
 305     cells in the selected column span additional columns, the cells in those columns
 306     are also selected.
 307    @param [in] column
 308     0 based index of the column to be selected.
 309    @retval S_OK
 310    @retval E_INVALIDARG if bad [in] passed
 311   */
 312   HRESULT selectColumn
 313     (
 314      [in] long column
 315     );
 316
 317   /** @brief Unselects one row, leaving other selected rows selected (if any).
 318
 319    The behavior should mimic that of the application, but for those applications
 320     which do not have a means in the GUI to unselect a full row of cells the
 321     behavior should be as follows:  The entire row of cells for the specified
 322     row is unselected.  If any of the cells in the selected row span additional
 323     rows, the cells in those rows are also unselected.
 324    @param [in] row
 325     0 based index of the row to be unselected.
 326    @retval S_OK
 327    @retval E_INVALIDARG if bad [in] passed
 328   */
 329   HRESULT unselectRow
 330     (
 331      [in] long row
 332     );
 333
 334   /** @brief Unselects one column, leaving other selected columns selected (if any).
 335
 336    The behavior should mimic that of the application, but for those applications
 337     which do not have a means in the GUI to unselect a full column of cells the
 338     behavior should be as follows:  The entire column of cells for the specified
 339     column is unselected.  If any of the cells in the selected column span additional
 340     columns, the cells in those columns are also unselected.
 341    @param [in] column
 342     0 based index of the column to be unselected.
 343    @retval S_OK
 344    @retval E_INVALIDARG if bad [in] passed
 345   */
 346   HRESULT unselectColumn
 347     (
 348      [in] long column
 349     );
 350
 351   /** @brief Returns the type and extents describing how a table changed.
 352
 353    Provided for use by the IA2_EVENT_TABLE_MODEL_CHANGED event handler.
 354
 355    This data is only guaranteed to be valid while the thread notifying the event
 356    continues. Once the handler has returned, the validity of the data depends on
 357    how the server manages the life cycle of its objects. Also, note that the server
 358    may have different life cycle management strategies for controls depending on
 359    whether or not a control manages its children. Lists, trees, and tables can have
 360    a large number of children and thus it's possible that the child objects for those
 361    controls would only be created as needed. Servers should document their life cycle
 362    strategy as this will be of interest to assistive technology or script engines
 363    accessing data out of process or from other threads. Servers only need to save the
 364    most recent row and column values associated with the change and a scope of the
 365    entire application is adequate.
 366
 367    @param [out] modelChange
 368     A struct of (type(insert, delete, update), firstRow, lastRow, firstColumn, lastColumn).
 369    @retval S_OK
 370    @retval S_FALSE if there is nothing to return, [out] value is NULL
 371   */
 372   [propget] HRESULT modelChange
 373     (
 374      [out, retval] IA2TableModelChange *modelChange
 375     );
 376
 377 }