other-licenses/ia2/AccessibleTable.idl@97036ab72558
other-licenses/ia2/AccessibleTable.idl
Tue, 06 Jan 2015 21:39:09 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Tue, 06 Jan 2015 21:39:09 +0100
- branch
- TOR_BUG_9701
- changeset 8
- 97036ab72558
- permissions
- -rw-r--r--
Conditionally force memory storage according to privacy.thirdparty.isolate;
This solves Tor bug #9701, complying with disk avoidance documented in
https://www.torproject.org/projects/torbrowser/design/#disk-avoidance.
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 ************************************************************************/
54 import "objidl.idl";
55 import "oaidl.idl";
56 import "oleacc.idl";
57 import "Accessible2.idl";
58 import "IA2CommonTypes.idl";
60 /** @brief This interface gives access to a two-dimensional table.
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.
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.
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.
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 {
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 );
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 );
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 );
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 );
159 /** @brief Returns the number of columns occupied by the accessible object
160 at the specified row and column in the table.
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 );
179 /** @brief Returns the column headers as an %IAccessibleTable object.
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 );
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 );
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 );
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 );
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 );
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 );
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 );
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 );
280 /** @brief Returns the number of rows occupied by the accessible object
281 at the specified row and column in the table.
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 );
300 /** @brief Returns the row headers as an %IAccessibleTable object.
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 );
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 );
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 );
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 );
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 );
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 );
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 );
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 );
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 );
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 );
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 );
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 );
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 );
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.
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 );
525 /** @brief Returns the type and extents describing how a table changed.
527 Provided for use by the IA2_EVENT_TABLE_MODEL_CHANGED event handler.
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.
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 );
551 }
