AccessibleTable2.idl (13878B)
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 }