AccessibleTable.idl (20460B)
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 }