summaryrefslogtreecommitdiff
path: root/other-licenses/ia2/AccessibleTable.idl
blob: 24df659e1a1cef39c119171c5a805da21f88fa3e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
/*************************************************************************
 *
 *  File Name (AccessibleTable.idl)
 * 
 *  IAccessible2 IDL Specification 
 * 
 *  Copyright (c) 2007, 2013 Linux Foundation 
 *  Copyright (c) 2006 IBM Corporation 
 *  Copyright (c) 2000, 2006 Sun Microsystems, Inc. 
 *  All rights reserved. 
 *   
 *   
 *  Redistribution and use in source and binary forms, with or without 
 *  modification, are permitted provided that the following conditions 
 *  are met: 
 *   
 *   1. Redistributions of source code must retain the above copyright 
 *      notice, this list of conditions and the following disclaimer. 
 *   
 *   2. Redistributions in binary form must reproduce the above 
 *      copyright notice, this list of conditions and the following 
 *      disclaimer in the documentation and/or other materials 
 *      provided with the distribution. 
 *
 *   3. Neither the name of the Linux Foundation nor the names of its 
 *      contributors may be used to endorse or promote products 
 *      derived from this software without specific prior written 
 *      permission. 
 *   
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND 
 *  CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, 
 *  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
 *  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
 *  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 
 *  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
 *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 
 *  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
 *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
 *  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
 *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 
 *  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 
 *  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
 *   
 *  This BSD License conforms to the Open Source Initiative "Simplified 
 *  BSD License" as published at: 
 *  http://www.opensource.org/licenses/bsd-license.php 
 *   
 *  IAccessible2 is a trademark of the Linux Foundation. The IAccessible2 
 *  mark may be used in accordance with the Linux Foundation Trademark 
 *  Policy to indicate compliance with the IAccessible2 specification. 
 * 
 ************************************************************************/ 

import "objidl.idl";
import "oaidl.idl";
import "oleacc.idl";
import "Accessible2.idl";
import "IA2CommonTypes.idl";

/** @brief This interface gives access to a two-dimensional table. 
       
 Typically all accessible objects that represent cells or cell-clusters of a table 
  will be at the same time children of the table.  In this case IAccessible2::indexInParent
  will return the child index which then can be used when calling IAccessibleTable::rowIndex
  and IAccessibleTable::columnIndex.

 However, in some cases that kind of implementation will not be possible.  When
  the table cells are not direct children of a table, the object representing
  the cell can define a "table-cell-index" object attribute identifying the 0 
  based table cell index.  This object attribute is obtained by parsing the
  attribute string returned by IAccessible2::attributes.  The "table-cell-index"
  attribute can be used just like a child index of the typical case.  ATs should 
  first test for the presence of the "table-cell-index" attribute and if it is not
  present then IAccessible2::indexInParent can be used as in the typical case
  where cells are direct children of the table.
              
 The range of valid coordinates for this interface are implementation dependent.  
  However, that range includes at least the intervals from the from the first row 
  or column with the index 0 up to the last (but not including) used row or column 
  as returned by IAccessibleTable::nRows and IAccessibleTable::nColumns.

 Note that newer implementations are now using IAccessibleTable2 and IAccessibleTableCell
  rather than this interface.
*/
[object, uuid(35AD8070-C20C-4fb4-B094-F4F7275DD469)]
interface IAccessibleTable : IUnknown
{

  /** @brief Returns the accessible object at the specified row and column in 
    the table.  This object could be an IAccessible or an IAccessible2.
   @param [in] row
    The 0 based row index for which to retrieve the cell.
   @param [in] column
    The 0 based column index for which to retrieve the cell.
   @param [out] accessible
    If both row and column index are valid then the corresponding accessible 
    object is returned that represents the requested cell regardless of whether 
    the cell is currently visible (on the screen).
   @retval S_OK
   @retval E_INVALIDARG if bad [in] passed, [out] value is NULL 
  */
  [propget] HRESULT accessibleAt
    (
     [in] long row, 
     [in] long column,
     [out, retval] IUnknown **accessible 
    );

  /** @brief Returns the caption for the table.  The returned object could be 
    an IAccessible or an IAccessible2.
   @param [out] accessible
    If the table has a caption then a reference to it is returned, else a NULL 
    pointer is returned.
   @retval S_OK
   @retval S_FALSE if there is nothing to return, [out] value is NULL 
  */
  [propget] HRESULT caption
    (
     [out, retval] IUnknown **accessible 
    );
	  
  /** @brief Translates the given row and column indexes into the corresponding cell index.
   @param [in] rowIndex
    0 based row index for the cell.
   @param [in] columnIndex
    0 based column index for the cell.
   @param [out] cellIndex
    Returns the 0 based index of the cell at the specified row and column indexes.
   @retval S_OK
   @retval E_INVALIDARG if bad [in] passed, [out] value is 0
   @note The returned value is not necessarily a child index of the immediate parent.
    In cases where the table cells are not direct children of the table the index 
    is actually the cell index, i.e. conceptually it's an index into a one dimensional
	array of cells laid out in row order.
  */
  [propget] HRESULT childIndex
	(
	 [in] long rowIndex,
	 [in] long columnIndex,
	 [out, retval] long *cellIndex
	);

  /** @brief Returns the description text of the specified column in the table.
   @param [in] column
    The 0 based index of the column for which to retrieve the description.
   @param [out] description
    Returns the description text of the specified column in the table if such a 
    description exists.  Otherwise a NULL pointer is returned.
   @retval S_OK
   @retval S_FALSE if there is nothing to return, [out] value is NULL 
   @retval E_INVALIDARG if bad [in] passed, [out] value is NULL
  */
  [propget] HRESULT columnDescription
    (
     [in] long column,
     [out, retval] BSTR *description
    );

  /** @brief Returns the number of columns occupied by the accessible object 
    at the specified row and column in the table.
        
   The result is greater than 1 if the specified cell spans multiple columns.
   @param [in] row
    0 based row index of the accessible for which to return the column extent.
   @param [in] column
    0 based column index of the accessible for which to return the column extent.
   @param [out] nColumnsSpanned
    Returns the 1 based column extent of the specified cell.
   @retval S_OK
   @retval E_INVALIDARG if bad [in] passed, [out] value is 0
  */
  [propget] HRESULT columnExtentAt
    (
     [in] long row,
     [in] long column,
     [out, retval] long *nColumnsSpanned 
    );

  /** @brief Returns the column headers as an %IAccessibleTable object.
        
   Content and size of the returned table are implementation dependent.
   @param [out] accessibleTable
    The column header
   @param [out] startingRowIndex
    The 0 based row index where the header starts, usually 0.
   @retval S_OK
   @retval S_FALSE if there is no header, [out] values are NULL and 0 respectively 
  */
  [propget] HRESULT columnHeader
    (
     [out] IAccessibleTable **accessibleTable,
	 [out, retval] long *startingRowIndex
    );

  /** @brief Translates the given cell index into the corresponding column index.
   @param [in] cellIndex
    0 based index of the cell in the parent or closest ancestor table.  Typically this
	is the value returned from IAccessible2::indexInParent, but in the case where the 
	table cells are not direct children of the table this is the cell index specified 
	by the "table-cell-index" object attribute obtained from parsing the attributes 
	string returned by calling IAccessible2::attributes on the cell object.
   @param [out] columnIndex
    Returns the 0 based column index of the cell of the specified child or the index of 
    the first column if the child spans multiple columns.
   @retval S_OK
   @retval E_INVALIDARG if bad [in] passed, [out] value is 0
  */
  [propget] HRESULT columnIndex
    (
	 [in] long cellIndex,
	 [out, retval] long *columnIndex
	);

  /** @brief Returns the total number of columns in table
   @param [out] columnCount
    Number of columns in table (including columns outside the current viewport)
   @retval S_OK
  */
  [propget] HRESULT nColumns
    (
     [out, retval] long *columnCount 
    );

  /** @brief Returns the total number of rows in table
   @param [out] rowCount
    Number of rows in table (including rows outside the current viewport)
   @retval S_OK
  */
  [propget] HRESULT nRows
    (
     [out, retval] long *rowCount 
    );

  /** @brief Returns the total number of selected cells
   @param [out] cellCount
    Number of cells currently selected
   @retval S_OK
  */
  [propget] HRESULT nSelectedChildren
    (
	 [out, retval] long *cellCount
	);

  /** @brief Returns the total number of selected columns
   @param [out] columnCount
    Number of columns currently selected
   @retval S_OK
  */
  [propget] HRESULT nSelectedColumns
    (
     [out, retval] long *columnCount 
    );

  /** @brief Returns the total number of selected rows
   @param [out] rowCount
    Number of rows currently selected
   @retval S_OK
  */
  [propget] HRESULT nSelectedRows
    (
     [out, retval] long *rowCount 
    );

  /** @brief Returns the description text of the specified row in the table.
   @param [in] row
    The 0 based index of the row for which to retrieve the description.
   @param [out] description
    Returns the description text of the specified row in the table if such a 
    description exists.  Otherwise a NULL pointer is returned.
   @retval S_OK
   @retval S_FALSE if there is nothing to return, [out] value is NULL 
   @retval E_INVALIDARG if bad [in] passed, [out] value is NULL
  */
  [propget] HRESULT rowDescription
    (
     [in] long row, 
     [out, retval] BSTR *description
    );

  /** @brief Returns the number of rows occupied by the accessible object 
    at the specified row and column in the table.
        
   The result is greater than 1 if the specified cell spans multiple rows.
   @param [in] row
    0 based row index of the accessible for which to return the row extent.
   @param [in] column
    0 based column index of the accessible for which to return the row extent.
   @param [out] nRowsSpanned
    Returns the row extent of the specified cell.
   @retval S_OK
   @retval E_INVALIDARG if bad [in] passed, [out] value is 0
  */
  [propget] HRESULT rowExtentAt
    (
     [in] long row,
     [in] long column,
     [out, retval] long *nRowsSpanned
    );

  /** @brief Returns the row headers as an %IAccessibleTable object.
        
   Content and size of the returned table are implementation dependent.
   @param [out] accessibleTable
    The row header.
   @param [out] startingColumnIndex
    The 0 based column index where the header starts, usually 0.
   @retval S_OK
   @retval S_FALSE if there is no header, [out] values are NULL and 0 respectively 
  */
  [propget] HRESULT rowHeader
    (
     [out] IAccessibleTable **accessibleTable,
	 [out, retval] long *startingColumnIndex
    );

  /** @brief Translates the given cell index into a row index.
   @param [in] cellIndex
    0 based index of the cell in the parent or closest ancestor table.  Typically this 
	is the value returned from IAccessible2::indexInParent, but in the case where the 
	table cells are not direct children of the table this is the cell index specified 
	by the "table-cell-index" object attribute obtained from parsing the attributes 
	string returned by calling IAccessible2::attributes on the cell object.
   @param [out] rowIndex
    0 based row index
   @retval S_OK
   @retval E_INVALIDARG if bad [in] passed, [out] value is 0
  */
  [propget] HRESULT rowIndex
    (
	 [in] long cellIndex,
	 [out, retval] long *rowIndex 
	);

  /** @brief Returns a list of cell indexes currently selected (0 based).
   @param [in] maxChildren
    This parameter is ignored. Refer to @ref _arrayConsideration
	"Special Consideration when using Arrays" for more details.
   @param [out] children
    An array of cell indexes of selected cells (each index is 0 based), 
	allocated by the server. The client must free it with CoTaskMemFree.
   @param [out] nChildren
    The number of cell indexes returned; the size of the returned array.
   @retval S_OK
   @retval S_FALSE if there are none, [out] values are NULL and 0 respectively 
  */
  [propget] HRESULT selectedChildren
    (
     [in] long maxChildren,
     [out, size_is(,maxChildren), length_is(,*nChildren)] long **children,
     [out, retval] long *nChildren
    );

  /** @brief Returns a list of column indexes currently selected (0 based).
   @param [in] maxColumns
    This parameter is ignored. Refer to @ref _arrayConsideration 
	"Special Consideration when using Arrays" for more details.
   @param [out] columns
	An array of column indexes of selected columns (each index is 0 based), allocated
	by the server. The client must free it with CoTaskMemFree.
   @param [out] nColumns
    The number of column indexes returned; the size of the returned array.
   @retval S_OK
   @retval S_FALSE if there are none, [out] values are NULL and 0 respectively 
  */
  [propget] HRESULT selectedColumns
    (
     [in] long maxColumns,
     [out, size_is(,maxColumns), length_is(,*nColumns)] long **columns,
     [out, retval] long *nColumns
    );

  /** @brief Returns a list of row indexes currently selected (0 based).
   @param [in] maxRows
    This parameter is ignored. Refer to @ref _arrayConsideration
	"Special Consideration when using Arrays" for more details.
   @param [out] rows
    An array of row indexes of selected rows (each index is 0 based), allocated
	by the server. The client must free it with CoTaskMemFree.
   @param [out] nRows
    The number of row indexes returned; the size of the returned array.
   @retval S_OK
   @retval S_FALSE if there are none, [out] values are NULL and 0 respectively 
  */
  [propget] HRESULT selectedRows
    (
     [in] long maxRows, 
     [out, size_is(,maxRows), length_is(,*nRows)] long **rows, 
     [out, retval] long *nRows 
    );

  /** @brief Returns the summary description of the table.  The returned object could be 
    an IAccessible or an IAccessible2.
   @param [out] accessible
    Returns a reference to an implementation dependent accessible object 
    representing the table's summary or a NULL pointer if the table 
    does not support a summary.
   @retval S_OK
   @retval S_FALSE if there is nothing to return, [out] value is NULL 
  */
  [propget] HRESULT summary
    (
     [out, retval] IUnknown **accessible 
    );

  /** @brief Returns a boolean value indicating whether the specified column is 
    completely selected.
   @param [in] column
    0 based index of the column for which to determine whether it is selected.
   @param [out] isSelected
    Returns TRUE if the specified column is selected completely and FALSE otherwise.
   @retval S_OK
   @retval E_INVALIDARG if bad [in] passed, [out] value is FALSE
  */
  [propget] HRESULT isColumnSelected
    (
     [in] long column,
     [out, retval] boolean *isSelected
    );

  /** @brief Returns a boolean value indicating whether the specified row is completely 
    selected.
   @param [in] row
    0 based index of the row for which to determine whether it is selected.
   @param [out] isSelected
    Returns TRUE if the specified row is selected completely and FALSE otherwise.
   @retval S_OK
   @retval E_INVALIDARG if bad [in] passed, [out] value is FALSE
  */
  [propget] HRESULT isRowSelected
    (
     [in] long row,
     [out, retval] boolean *isSelected
    );

  /** @brief Returns a boolean value indicating whether the specified cell is selected.
   @param [in] row
    0 based index of the row for the cell to determine whether it is selected.
   @param [in] column
    0 based index of the column for the cell to determine whether it is selected.
   @param [out] isSelected
    Returns TRUE if the specified cell is selected and FALSE otherwise.
   @retval S_OK
   @retval E_INVALIDARG if bad [in] passed, [out] value is FALSE
  */
  [propget] HRESULT isSelected
    (
     [in] long row,
     [in] long column,
     [out, retval] boolean *isSelected 
    );

  /** @brief Selects a row and unselects all previously selected rows.
   @param [in] row
    0 based index of the row to be selected.
   @retval S_OK
   @retval E_INVALIDARG if bad [in] passed
  */
  HRESULT selectRow
    (
     [in] long row 
    );

  /** @brief Selects a column and unselects all previously selected columns.
   @param [in] column
    0 based index of the column to be selected.
   @retval S_OK
   @retval E_INVALIDARG if bad [in] passed
  */
  HRESULT selectColumn
    (
     [in] long column
    );

  /** @brief Unselects one row, leaving other selected rows selected (if any).
   @param [in] row
    0 based index of the row to be unselected.
   @retval S_OK
   @retval E_INVALIDARG if bad [in] passed
  */
  HRESULT unselectRow
    (
     [in] long row
    );

  /** @brief Unselects one column, leaving other selected columns selected (if any).
   @param [in] column
    0 based index of the column to be unselected.
   @retval S_OK
   @retval E_INVALIDARG if bad [in] passed
  */
  HRESULT unselectColumn
    (
     [in] long column
    );
  
  /** @brief Given a cell index, gets the row and column indexes and extents of a cell 
    and whether or not it is selected.

   This is a convenience function.  It is not mandatory to implement it.
   @param [in] index
    0 based index of this cell in the table.
   @param [out] row
    0 based row index.
   @param [out] column
    0 based column index.
   @param [out] rowExtents
    Number of cells spanned by this cell in this row.
   @param [out] columnExtents
    Number of cells spanned by this cell in this column.
   @param [out] isSelected
    Indicates if the specified cell is selected.
   @retval S_OK
   @retval E_INVALIDARG if bad [in] passed, [out] values are 0s and FALSE respectively
  */
  [propget] HRESULT rowColumnExtentsAtIndex
    (
	 [in] long index, 
	 [out] long *row,  
	 [out] long *column,
	 [out] long *rowExtents,
	 [out] long *columnExtents,
	 [out, retval] boolean *isSelected
	);

  /** @brief Returns the type and extents describing how a table changed.
  
   Provided for use by the IA2_EVENT_TABLE_MODEL_CHANGED event handler.

   This data is only guaranteed to be valid while the thread notifying the event 
   continues. Once the handler has returned, the validity of the data depends on 
   how the server manages the life cycle of its objects. Also, note that the server 
   may have different life cycle management strategies for controls depending on 
   whether or not a control manages its children. Lists, trees, and tables can have 
   a large number of children and thus it's possible that the child objects for those 
   controls would only be created as needed. Servers should document their life cycle 
   strategy as this will be of interest to assistive technology or script engines 
   accessing data out of process or from other threads. Servers only need to save the 
   most recent row and column values associated with the change and a scope of the 
   entire application is adequate.

   @param [out] modelChange
    A struct of (type(insert, delete, update), firstRow, lastRow, firstColumn, lastColumn).
   @retval S_OK
   @retval S_FALSE if there is nothing to return, [out] value is NULL 
  */
  [propget] HRESULT modelChange
    (
	 [out, retval] IA2TableModelChange *modelChange
    );

}