1 /*************************************************************************
3 * File Name (AccessibleTable2.idl)
5 * IAccessible2 IDL Specification
7 * Copyright (c) Linux Foundation 2007, 2009
8 * Copyright (c) IBM Corp. 2006
9 * Copyright (c) Sun Microsystems, Inc. 2000, 2006
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.
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.
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
25 ************************************************************************/
30 import
"Accessible2.idl";
31 import
"IA2CommonTypes.idl";
33 /** @brief This interface gives access to a two-dimensional table.
35 Please also refer to the IAccessibleTableCell interface.
37 If you want to support older applications you should also support the
38 IAccessibleTable inteface.
40 [object, uuid(6167f295
-06f0
-4cdd
-a1fa
-02e25153d869
)]
41 interface IAccessibleTable2
: IUnknown
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.
47 The 0 based row index for which to retrieve the cell.
49 The 0 based column index for which to retrieve the 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).
55 @retval E_INVALIDARG if bad [in] passed, [out] value is NULL
57 [propget] HRESULT cellAt
61 [out, retval] IUnknown
**cell
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
70 @retval S_FALSE if there is nothing to return, [out] value is NULL
72 [propget] HRESULT caption
74 [out, retval] IUnknown
**accessible
77 /** @brief Returns the description text of the specified column in the table.
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.
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
87 [propget] HRESULT columnDescription
90 [out, retval] BSTR *description
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)
99 [propget] HRESULT nColumns
101 [out, retval] long *columnCount
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)
109 [propget] HRESULT nRows
111 [out, retval] long *rowCount
114 /** @brief Returns the total number of selected cells
115 @param [out] cellCount
116 Number of cells currently selected
119 [propget] HRESULT nSelectedCells
121 [out, retval] long *cellCount
124 /** @brief Returns the total number of selected columns
125 @param [out] columnCount
126 Number of columns currently selected
129 [propget] HRESULT nSelectedColumns
131 [out, retval] long *columnCount
134 /** @brief Returns the total number of selected rows
135 @param [out] rowCount
136 Number of rows currently selected
139 [propget] HRESULT nSelectedRows
141 [out, retval] long *rowCount
144 /** @brief Returns the description text of the specified row in the table.
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.
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
154 [propget] HRESULT rowDescription
157 [out, retval] BSTR *description
160 /** @brief Returns a list of accessibles currently selected.
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.
167 @retval S_FALSE if there are none, [out] values are NULL and 0 respectively
169 [propget] HRESULT selectedCells
171 [out, size_is(,*nSelectedCells
,)] IUnknown
***cells
,
172 [out, retval] long *nSelectedCells
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.
182 @retval S_FALSE if there are none, [out] values are NULL and 0 respectively
184 [propget] HRESULT selectedColumns
186 [out, size_is(,*nColumns
)] long **selectedColumns
,
187 [out, retval] long *nColumns
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.
195 The number of row indexes returned; the size of the returned array.
197 @retval S_FALSE if there are none, [out] values are NULL and 0 respectively
199 [propget] HRESULT selectedRows
201 [out, size_is(,*nRows
)] long **selectedRows
,
202 [out, retval] long *nRows
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.
212 @retval S_FALSE if there is nothing to return, [out] value is NULL
214 [propget] HRESULT summary
216 [out, retval] IUnknown
**accessible
219 /** @brief Returns a boolean value indicating whether the specified column is
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.
226 @retval E_INVALIDARG if bad [in] passed, [out] value is FALSE
228 [propget] HRESULT isColumnSelected
231 [out, retval] boolean *isSelected
234 /** @brief Returns a boolean value indicating whether the specified row is completely
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.
241 @retval E_INVALIDARG if bad [in] passed, [out] value is FALSE
243 [propget] HRESULT isRowSelected
246 [out, retval] boolean *isSelected
249 /** @brief Selects a row and unselects all previously selected rows.
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
258 0 based index of the row to be selected.
260 @retval E_INVALIDARG if bad [in] passed
267 /** @brief Selects a column and unselects all previously selected columns.
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
276 0 based index of the column to be selected.
278 @retval E_INVALIDARG if bad [in] passed
285 /** @brief Unselects one row, leaving other selected rows selected (if any).
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.
293 0 based index of the row to be unselected.
295 @retval E_INVALIDARG if bad [in] passed
302 /** @brief Unselects one column, leaving other selected columns selected (if any).
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.
310 0 based index of the column to be unselected.
312 @retval E_INVALIDARG if bad [in] passed
314 HRESULT unselectColumn
319 /** @brief Returns the type and extents describing how a table changed.
321 Provided for use by the IA2_EVENT_TABLE_MODEL_CHANGED event handler.
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.
335 @param [out] modelChange
336 A struct of (type(insert, delete, update), firstRow, lastRow, firstColumn, lastColumn).
338 @retval S_FALSE if there is nothing to return, [out] value is NULL
340 [propget] HRESULT modelChange
342 [out, retval] IA2TableModelChange
*modelChange