other-licenses/ia2/AccessibleTable2.idl

   1 /*************************************************************************
   2  *
   3  *  File Name (AccessibleTable2.idl)
   4  *
   5  *  IAccessible2 IDL Specification
   6  *
   7  *  Copyright (c) Linux Foundation 2007, 2009
   8  *  Copyright (c) IBM Corp. 2006
   9  *  Copyright (c) Sun Microsystems, Inc. 2000, 2006
  10  *
  11  *  This library is free software; you can redistribute it and/or
  12  *  modify it under the terms of the GNU Lesser General Public
  13  *  License version 2.1, as published by the Free Software Foundation; either
  14  *  version 2.1 of the License, or (at your option) any later version.
  15  *
  16  *  This library is distributed in the hope that it will be useful,
  17  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  *  Lesser General Public License for more details.
  20  *
  21  *  You should have received a copy of the GNU Lesser General Public
  22  *  License along with this library; if not, write to the Free Software
  23  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  24  *
  25  ************************************************************************/
  26
  27 import "objidl.idl";
  28 import "oaidl.idl";
  29 import "oleacc.idl";
  30 import "Accessible2.idl";
  31 import "IA2CommonTypes.idl";
  32
  33 /** @brief This interface gives access to a two-dimensional table.
  34
  35  Please also refer to the IAccessibleTableCell interface.
  36
  37  If you want to support older applications you should also support the
  38   IAccessibleTable inteface.
  39 */
  40 [object, uuid(6167f295-06f0-4cdd-a1fa-02e25153d869)]
  41 interface IAccessibleTable2 : IUnknown
  42 {
  43
  44   /** @brief Returns the accessible object at the specified row and column in
  45     the table.  This object could be an IAccessible or an IAccessible2.
  46    @param [in] row
  47     The 0 based row index for which to retrieve the cell.
  48    @param [in] column
  49     The 0 based column index for which to retrieve the cell.
  50    @param [out] cell
  51     If both row and column index are valid then the corresponding accessible
  52     object is returned that represents the requested cell regardless of whether
  53     the cell is currently visible (on the screen).
  54    @retval S_OK
  55    @retval E_INVALIDARG if bad [in] passed, [out] value is NULL
  56   */
  57   [propget] HRESULT cellAt
  58     (
  59      [in] long row,
  60      [in] long column,
  61      [out, retval] IUnknown **cell
  62     );
  63
  64   /** @brief Returns the caption for the table.  The returned object could be
  65     an IAccessible or an IAccessible2.
  66    @param [out] accessible
  67     If the table has a caption then a reference to it is returned, else a NULL
  68     pointer is returned.
  69    @retval S_OK
  70    @retval S_FALSE if there is nothing to return, [out] value is NULL
  71   */
  72   [propget] HRESULT caption
  73     (
  74      [out, retval] IUnknown **accessible
  75     );
  76
  77   /** @brief Returns the description text of the specified column in the table.
  78    @param [in] column
  79     The 0 based index of the column for which to retrieve the description.
  80    @param [out] description
  81     Returns the description text of the specified column in the table if such a
  82     description exists.  Otherwise a NULL pointer is returned.
  83    @retval S_OK
  84    @retval S_FALSE if there is nothing to return, [out] value is NULL
  85    @retval E_INVALIDARG if bad [in] passed, [out] value is NULL
  86   */
  87   [propget] HRESULT columnDescription
  88     (
  89      [in] long column,
  90      [out, retval] BSTR *description
  91     );
  92
  93
  94   /** @brief Returns the total number of columns in table
  95    @param [out] columnCount
  96     Number of columns in table (including columns outside the current viewport)
  97    @retval S_OK
  98   */
  99   [propget] HRESULT nColumns
 100     (
 101      [out, retval] long *columnCount
 102     );
 103
 104   /** @brief Returns the total number of rows in table
 105    @param [out] rowCount
 106     Number of rows in table (including rows outside the current viewport)
 107    @retval S_OK
 108   */
 109   [propget] HRESULT nRows
 110     (
 111      [out, retval] long *rowCount
 112     );
 113
 114   /** @brief Returns the total number of selected cells
 115    @param [out] cellCount
 116     Number of cells currently selected
 117    @retval S_OK
 118   */
 119   [propget] HRESULT nSelectedCells
 120     (
 121      [out, retval] long *cellCount
 122     );
 123
 124   /** @brief Returns the total number of selected columns
 125    @param [out] columnCount
 126     Number of columns currently selected
 127    @retval S_OK
 128   */
 129   [propget] HRESULT nSelectedColumns
 130     (
 131      [out, retval] long *columnCount
 132     );
 133
 134   /** @brief Returns the total number of selected rows
 135    @param [out] rowCount
 136     Number of rows currently selected
 137    @retval S_OK
 138   */
 139   [propget] HRESULT nSelectedRows
 140     (
 141      [out, retval] long *rowCount
 142     );
 143
 144   /** @brief Returns the description text of the specified row in the table.
 145    @param [in] row
 146     The 0 based index of the row for which to retrieve the description.
 147    @param [out] description
 148     Returns the description text of the specified row in the table if such a
 149     description exists.  Otherwise a NULL pointer is returned.
 150    @retval S_OK
 151    @retval S_FALSE if there is nothing to return, [out] value is NULL
 152    @retval E_INVALIDARG if bad [in] passed, [out] value is NULL
 153   */
 154   [propget] HRESULT rowDescription
 155     (
 156      [in] long row,
 157      [out, retval] BSTR *description
 158     );
 159
 160   /** @brief Returns a list of accessibles currently selected.
 161    @param [out] cells
 162     Pointer to an array of references to selected accessibles.  The array is
 163     allocated by the server.  Free it with CoTaskMemFree.
 164    @param [out] nSelectedCells
 165     The number of accessibles returned; the size of the returned array.
 166    @retval S_OK
 167    @retval S_FALSE if there are none, [out] values are NULL and 0 respectively
 168   */
 169   [propget] HRESULT selectedCells
 170     (
 171      [out, size_is(,*nSelectedCells,)] IUnknown ***cells,
 172      [out, retval] long *nSelectedCells
 173     );
 174
 175   /** @brief Returns a list of column indexes currently selected (0 based).
 176    @param [out] selectedColumns
 177     A pointer to an array of column indexes of selected columns (each index is
 178     0 based).  The array is allocated by the server. Free it with CoTaskMemFree.
 179    @param [out] nColumns
 180     The number of column indexes returned; the size of the returned array.
 181    @retval S_OK
 182    @retval S_FALSE if there are none, [out] values are NULL and 0 respectively
 183   */
 184   [propget] HRESULT selectedColumns
 185     (
 186      [out, size_is(,*nColumns)] long **selectedColumns,
 187      [out, retval] long *nColumns
 188     );
 189
 190   /** @brief Returns a list of row indexes currently selected (0 based).
 191    @param [out] selectedRows
 192     An array of row indexes of selected rows (each index is 0 based), allocated
 193     by the server. Free it with CoTaskMemFree.
 194    @param [out] nRows
 195     The number of row indexes returned; the size of the returned array.
 196    @retval S_OK
 197    @retval S_FALSE if there are none, [out] values are NULL and 0 respectively
 198   */
 199   [propget] HRESULT selectedRows
 200     (
 201      [out, size_is(,*nRows)] long **selectedRows,
 202      [out, retval] long *nRows
 203     );
 204
 205   /** @brief Returns the summary description of the table.  The returned object could be
 206     an IAccessible or an IAccessible2.
 207    @param [out] accessible
 208     Returns a reference to an implementation dependent accessible object
 209     representing the table's summary or a NULL pointer if the table
 210     does not support a summary.
 211    @retval S_OK
 212    @retval S_FALSE if there is nothing to return, [out] value is NULL
 213   */
 214   [propget] HRESULT summary
 215     (
 216      [out, retval] IUnknown **accessible
 217     );
 218
 219   /** @brief Returns a boolean value indicating whether the specified column is
 220     completely selected.
 221    @param [in] column
 222     0 based index of the column for which to determine whether it is selected.
 223    @param [out] isSelected
 224     Returns TRUE if the specified column is selected completely and FALSE otherwise.
 225    @retval S_OK
 226    @retval E_INVALIDARG if bad [in] passed, [out] value is FALSE
 227   */
 228   [propget] HRESULT isColumnSelected
 229     (
 230      [in] long column,
 231      [out, retval] boolean *isSelected
 232     );
 233
 234   /** @brief Returns a boolean value indicating whether the specified row is completely
 235     selected.
 236    @param [in] row
 237     0 based index of the row for which to determine whether it is selected.
 238    @param [out] isSelected
 239     Returns TRUE if the specified row is selected completely and FALSE otherwise.
 240    @retval S_OK
 241    @retval E_INVALIDARG if bad [in] passed, [out] value is FALSE
 242   */
 243   [propget] HRESULT isRowSelected
 244     (
 245      [in] long row,
 246      [out, retval] boolean *isSelected
 247     );
 248
 249   /** @brief Selects a row and unselects all previously selected rows.
 250
 251    The behavior should mimic that of the application, but for those applications
 252     which do not have a means in the GUI to select a full row of cells the behavior
 253     should be as follows:  First any selected rows in the table are unselected.  Then
 254     the entire row of cells for the specified row is selected.  If any of the
 255     cells in the selected row span additional rows, the cells in those rows
 256     are also selected.
 257    @param [in] row
 258     0 based index of the row to be selected.
 259    @retval S_OK
 260    @retval E_INVALIDARG if bad [in] passed
 261   */
 262   HRESULT selectRow
 263     (
 264      [in] long row
 265     );
 266
 267   /** @brief Selects a column and unselects all previously selected columns.
 268
 269    The behavior should mimic that of the application, but for those applications
 270     which do not have a means in the GUI to select a full column of cells the behavior
 271     should be as follows:  First any selected columns in the table are unselected.  Then
 272     the entire column of cells for the specified column is selected.  If any of the
 273     cells in the selected column span additional columns, the cells in those columns
 274     are also selected.
 275    @param [in] column
 276     0 based index of the column to be selected.
 277    @retval S_OK
 278    @retval E_INVALIDARG if bad [in] passed
 279   */
 280   HRESULT selectColumn
 281     (
 282      [in] long column
 283     );
 284
 285   /** @brief Unselects one row, leaving other selected rows selected (if any).
 286
 287    The behavior should mimic that of the application, but for those applications
 288     which do not have a means in the GUI to unselect a full row of cells the
 289     behavior should be as follows:  The entire row of cells for the specified
 290     row is unselected.  If any of the cells in the selected row span additional
 291     rows, the cells in those rows are also unselected.
 292    @param [in] row
 293     0 based index of the row to be unselected.
 294    @retval S_OK
 295    @retval E_INVALIDARG if bad [in] passed
 296   */
 297   HRESULT unselectRow
 298     (
 299      [in] long row
 300     );
 301
 302   /** @brief Unselects one column, leaving other selected columns selected (if any).
 303
 304    The behavior should mimic that of the application, but for those applications
 305     which do not have a means in the GUI to unselect a full column of cells the
 306     behavior should be as follows:  The entire column of cells for the specified
 307     column is unselected.  If any of the cells in the selected column span additional
 308     columns, the cells in those columns are also unselected.
 309    @param [in] column
 310     0 based index of the column to be unselected.
 311    @retval S_OK
 312    @retval E_INVALIDARG if bad [in] passed
 313   */
 314   HRESULT unselectColumn
 315     (
 316      [in] long column
 317     );
 318
 319   /** @brief Returns the type and extents describing how a table changed.
 320
 321    Provided for use by the IA2_EVENT_TABLE_MODEL_CHANGED event handler.
 322
 323    This data is only guaranteed to be valid while the thread notifying the event
 324    continues. Once the handler has returned, the validity of the data depends on
 325    how the server manages the life cycle of its objects. Also, note that the server
 326    may have different life cycle management strategies for controls depending on
 327    whether or not a control manages its children. Lists, trees, and tables can have
 328    a large number of children and thus it's possible that the child objects for those
 329    controls would only be created as needed. Servers should document their life cycle
 330    strategy as this will be of interest to assistive technology or script engines
 331    accessing data out of process or from other threads. Servers only need to save the
 332    most recent row and column values associated with the change and a scope of the
 333    entire application is adequate.
 334
 335    @param [out] modelChange
 336     A struct of (type(insert, delete, update), firstRow, lastRow, firstColumn, lastColumn).
 337    @retval S_OK
 338    @retval S_FALSE if there is nothing to return, [out] value is NULL
 339   */
 340   [propget] HRESULT modelChange
 341     (
 342      [out, retval] IA2TableModelChange *modelChange
 343     );
 344
 345 }