1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/other-licenses/ia2/AccessibleTable.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,551 @@
1.4 +/*************************************************************************
1.5 + *
1.6 + * File Name (AccessibleTable.idl)
1.7 + *
1.8 + * IAccessible2 IDL Specification
1.9 + *
1.10 + * Copyright (c) 2007, 2013 Linux Foundation
1.11 + * Copyright (c) 2006 IBM Corporation
1.12 + * Copyright (c) 2000, 2006 Sun Microsystems, Inc.
1.13 + * All rights reserved.
1.14 + *
1.15 + *
1.16 + * Redistribution and use in source and binary forms, with or without
1.17 + * modification, are permitted provided that the following conditions
1.18 + * are met:
1.19 + *
1.20 + * 1. Redistributions of source code must retain the above copyright
1.21 + * notice, this list of conditions and the following disclaimer.
1.22 + *
1.23 + * 2. Redistributions in binary form must reproduce the above
1.24 + * copyright notice, this list of conditions and the following
1.25 + * disclaimer in the documentation and/or other materials
1.26 + * provided with the distribution.
1.27 + *
1.28 + * 3. Neither the name of the Linux Foundation nor the names of its
1.29 + * contributors may be used to endorse or promote products
1.30 + * derived from this software without specific prior written
1.31 + * permission.
1.32 + *
1.33 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
1.34 + * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
1.35 + * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
1.36 + * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
1.37 + * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
1.38 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1.39 + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
1.40 + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
1.41 + * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
1.42 + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
1.43 + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
1.44 + * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
1.45 + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.46 + *
1.47 + * This BSD License conforms to the Open Source Initiative "Simplified
1.48 + * BSD License" as published at:
1.49 + * http://www.opensource.org/licenses/bsd-license.php
1.50 + *
1.51 + * IAccessible2 is a trademark of the Linux Foundation. The IAccessible2
1.52 + * mark may be used in accordance with the Linux Foundation Trademark
1.53 + * Policy to indicate compliance with the IAccessible2 specification.
1.54 + *
1.55 + ************************************************************************/
1.56 +
1.57 +import "objidl.idl";
1.58 +import "oaidl.idl";
1.59 +import "oleacc.idl";
1.60 +import "Accessible2.idl";
1.61 +import "IA2CommonTypes.idl";
1.62 +
1.63 +/** @brief This interface gives access to a two-dimensional table.
1.64 +
1.65 + Typically all accessible objects that represent cells or cell-clusters of a table
1.66 + will be at the same time children of the table. In this case IAccessible2::indexInParent
1.67 + will return the child index which then can be used when calling IAccessibleTable::rowIndex
1.68 + and IAccessibleTable::columnIndex.
1.69 +
1.70 + However, in some cases that kind of implementation will not be possible. When
1.71 + the table cells are not direct children of a table, the object representing
1.72 + the cell can define a "table-cell-index" object attribute identifying the 0
1.73 + based table cell index. This object attribute is obtained by parsing the
1.74 + attribute string returned by IAccessible2::attributes. The "table-cell-index"
1.75 + attribute can be used just like a child index of the typical case. ATs should
1.76 + first test for the presence of the "table-cell-index" attribute and if it is not
1.77 + present then IAccessible2::indexInParent can be used as in the typical case
1.78 + where cells are direct children of the table.
1.79 +
1.80 + The range of valid coordinates for this interface are implementation dependent.
1.81 + However, that range includes at least the intervals from the from the first row
1.82 + or column with the index 0 up to the last (but not including) used row or column
1.83 + as returned by IAccessibleTable::nRows and IAccessibleTable::nColumns.
1.84 +
1.85 + Note that newer implementations are now using IAccessibleTable2 and IAccessibleTableCell
1.86 + rather than this interface.
1.87 +*/
1.88 +[object, uuid(35AD8070-C20C-4fb4-B094-F4F7275DD469)]
1.89 +interface IAccessibleTable : IUnknown
1.90 +{
1.91 +
1.92 + /** @brief Returns the accessible object at the specified row and column in
1.93 + the table. This object could be an IAccessible or an IAccessible2.
1.94 + @param [in] row
1.95 + The 0 based row index for which to retrieve the cell.
1.96 + @param [in] column
1.97 + The 0 based column index for which to retrieve the cell.
1.98 + @param [out] accessible
1.99 + If both row and column index are valid then the corresponding accessible
1.100 + object is returned that represents the requested cell regardless of whether
1.101 + the cell is currently visible (on the screen).
1.102 + @retval S_OK
1.103 + @retval E_INVALIDARG if bad [in] passed, [out] value is NULL
1.104 + */
1.105 + [propget] HRESULT accessibleAt
1.106 + (
1.107 + [in] long row,
1.108 + [in] long column,
1.109 + [out, retval] IUnknown **accessible
1.110 + );
1.111 +
1.112 + /** @brief Returns the caption for the table. The returned object could be
1.113 + an IAccessible or an IAccessible2.
1.114 + @param [out] accessible
1.115 + If the table has a caption then a reference to it is returned, else a NULL
1.116 + pointer is returned.
1.117 + @retval S_OK
1.118 + @retval S_FALSE if there is nothing to return, [out] value is NULL
1.119 + */
1.120 + [propget] HRESULT caption
1.121 + (
1.122 + [out, retval] IUnknown **accessible
1.123 + );
1.124 +
1.125 + /** @brief Translates the given row and column indexes into the corresponding cell index.
1.126 + @param [in] rowIndex
1.127 + 0 based row index for the cell.
1.128 + @param [in] columnIndex
1.129 + 0 based column index for the cell.
1.130 + @param [out] cellIndex
1.131 + Returns the 0 based index of the cell at the specified row and column indexes.
1.132 + @retval S_OK
1.133 + @retval E_INVALIDARG if bad [in] passed, [out] value is 0
1.134 + @note The returned value is not necessarily a child index of the immediate parent.
1.135 + In cases where the table cells are not direct children of the table the index
1.136 + is actually the cell index, i.e. conceptually it's an index into a one dimensional
1.137 + array of cells laid out in row order.
1.138 + */
1.139 + [propget] HRESULT childIndex
1.140 + (
1.141 + [in] long rowIndex,
1.142 + [in] long columnIndex,
1.143 + [out, retval] long *cellIndex
1.144 + );
1.145 +
1.146 + /** @brief Returns the description text of the specified column in the table.
1.147 + @param [in] column
1.148 + The 0 based index of the column for which to retrieve the description.
1.149 + @param [out] description
1.150 + Returns the description text of the specified column in the table if such a
1.151 + description exists. Otherwise a NULL pointer is returned.
1.152 + @retval S_OK
1.153 + @retval S_FALSE if there is nothing to return, [out] value is NULL
1.154 + @retval E_INVALIDARG if bad [in] passed, [out] value is NULL
1.155 + */
1.156 + [propget] HRESULT columnDescription
1.157 + (
1.158 + [in] long column,
1.159 + [out, retval] BSTR *description
1.160 + );
1.161 +
1.162 + /** @brief Returns the number of columns occupied by the accessible object
1.163 + at the specified row and column in the table.
1.164 +
1.165 + The result is greater than 1 if the specified cell spans multiple columns.
1.166 + @param [in] row
1.167 + 0 based row index of the accessible for which to return the column extent.
1.168 + @param [in] column
1.169 + 0 based column index of the accessible for which to return the column extent.
1.170 + @param [out] nColumnsSpanned
1.171 + Returns the 1 based column extent of the specified cell.
1.172 + @retval S_OK
1.173 + @retval E_INVALIDARG if bad [in] passed, [out] value is 0
1.174 + */
1.175 + [propget] HRESULT columnExtentAt
1.176 + (
1.177 + [in] long row,
1.178 + [in] long column,
1.179 + [out, retval] long *nColumnsSpanned
1.180 + );
1.181 +
1.182 + /** @brief Returns the column headers as an %IAccessibleTable object.
1.183 +
1.184 + Content and size of the returned table are implementation dependent.
1.185 + @param [out] accessibleTable
1.186 + The column header
1.187 + @param [out] startingRowIndex
1.188 + The 0 based row index where the header starts, usually 0.
1.189 + @retval S_OK
1.190 + @retval S_FALSE if there is no header, [out] values are NULL and 0 respectively
1.191 + */
1.192 + [propget] HRESULT columnHeader
1.193 + (
1.194 + [out] IAccessibleTable **accessibleTable,
1.195 + [out, retval] long *startingRowIndex
1.196 + );
1.197 +
1.198 + /** @brief Translates the given cell index into the corresponding column index.
1.199 + @param [in] cellIndex
1.200 + 0 based index of the cell in the parent or closest ancestor table. Typically this
1.201 + is the value returned from IAccessible2::indexInParent, but in the case where the
1.202 + table cells are not direct children of the table this is the cell index specified
1.203 + by the "table-cell-index" object attribute obtained from parsing the attributes
1.204 + string returned by calling IAccessible2::attributes on the cell object.
1.205 + @param [out] columnIndex
1.206 + Returns the 0 based column index of the cell of the specified child or the index of
1.207 + the first column if the child spans multiple columns.
1.208 + @retval S_OK
1.209 + @retval E_INVALIDARG if bad [in] passed, [out] value is 0
1.210 + */
1.211 + [propget] HRESULT columnIndex
1.212 + (
1.213 + [in] long cellIndex,
1.214 + [out, retval] long *columnIndex
1.215 + );
1.216 +
1.217 + /** @brief Returns the total number of columns in table
1.218 + @param [out] columnCount
1.219 + Number of columns in table (including columns outside the current viewport)
1.220 + @retval S_OK
1.221 + */
1.222 + [propget] HRESULT nColumns
1.223 + (
1.224 + [out, retval] long *columnCount
1.225 + );
1.226 +
1.227 + /** @brief Returns the total number of rows in table
1.228 + @param [out] rowCount
1.229 + Number of rows in table (including rows outside the current viewport)
1.230 + @retval S_OK
1.231 + */
1.232 + [propget] HRESULT nRows
1.233 + (
1.234 + [out, retval] long *rowCount
1.235 + );
1.236 +
1.237 + /** @brief Returns the total number of selected cells
1.238 + @param [out] cellCount
1.239 + Number of cells currently selected
1.240 + @retval S_OK
1.241 + */
1.242 + [propget] HRESULT nSelectedChildren
1.243 + (
1.244 + [out, retval] long *cellCount
1.245 + );
1.246 +
1.247 + /** @brief Returns the total number of selected columns
1.248 + @param [out] columnCount
1.249 + Number of columns currently selected
1.250 + @retval S_OK
1.251 + */
1.252 + [propget] HRESULT nSelectedColumns
1.253 + (
1.254 + [out, retval] long *columnCount
1.255 + );
1.256 +
1.257 + /** @brief Returns the total number of selected rows
1.258 + @param [out] rowCount
1.259 + Number of rows currently selected
1.260 + @retval S_OK
1.261 + */
1.262 + [propget] HRESULT nSelectedRows
1.263 + (
1.264 + [out, retval] long *rowCount
1.265 + );
1.266 +
1.267 + /** @brief Returns the description text of the specified row in the table.
1.268 + @param [in] row
1.269 + The 0 based index of the row for which to retrieve the description.
1.270 + @param [out] description
1.271 + Returns the description text of the specified row in the table if such a
1.272 + description exists. Otherwise a NULL pointer is returned.
1.273 + @retval S_OK
1.274 + @retval S_FALSE if there is nothing to return, [out] value is NULL
1.275 + @retval E_INVALIDARG if bad [in] passed, [out] value is NULL
1.276 + */
1.277 + [propget] HRESULT rowDescription
1.278 + (
1.279 + [in] long row,
1.280 + [out, retval] BSTR *description
1.281 + );
1.282 +
1.283 + /** @brief Returns the number of rows occupied by the accessible object
1.284 + at the specified row and column in the table.
1.285 +
1.286 + The result is greater than 1 if the specified cell spans multiple rows.
1.287 + @param [in] row
1.288 + 0 based row index of the accessible for which to return the row extent.
1.289 + @param [in] column
1.290 + 0 based column index of the accessible for which to return the row extent.
1.291 + @param [out] nRowsSpanned
1.292 + Returns the row extent of the specified cell.
1.293 + @retval S_OK
1.294 + @retval E_INVALIDARG if bad [in] passed, [out] value is 0
1.295 + */
1.296 + [propget] HRESULT rowExtentAt
1.297 + (
1.298 + [in] long row,
1.299 + [in] long column,
1.300 + [out, retval] long *nRowsSpanned
1.301 + );
1.302 +
1.303 + /** @brief Returns the row headers as an %IAccessibleTable object.
1.304 +
1.305 + Content and size of the returned table are implementation dependent.
1.306 + @param [out] accessibleTable
1.307 + The row header.
1.308 + @param [out] startingColumnIndex
1.309 + The 0 based column index where the header starts, usually 0.
1.310 + @retval S_OK
1.311 + @retval S_FALSE if there is no header, [out] values are NULL and 0 respectively
1.312 + */
1.313 + [propget] HRESULT rowHeader
1.314 + (
1.315 + [out] IAccessibleTable **accessibleTable,
1.316 + [out, retval] long *startingColumnIndex
1.317 + );
1.318 +
1.319 + /** @brief Translates the given cell index into a row index.
1.320 + @param [in] cellIndex
1.321 + 0 based index of the cell in the parent or closest ancestor table. Typically this
1.322 + is the value returned from IAccessible2::indexInParent, but in the case where the
1.323 + table cells are not direct children of the table this is the cell index specified
1.324 + by the "table-cell-index" object attribute obtained from parsing the attributes
1.325 + string returned by calling IAccessible2::attributes on the cell object.
1.326 + @param [out] rowIndex
1.327 + 0 based row index
1.328 + @retval S_OK
1.329 + @retval E_INVALIDARG if bad [in] passed, [out] value is 0
1.330 + */
1.331 + [propget] HRESULT rowIndex
1.332 + (
1.333 + [in] long cellIndex,
1.334 + [out, retval] long *rowIndex
1.335 + );
1.336 +
1.337 + /** @brief Returns a list of cell indexes currently selected (0 based).
1.338 + @param [in] maxChildren
1.339 + This parameter is ignored. Refer to @ref _arrayConsideration
1.340 + "Special Consideration when using Arrays" for more details.
1.341 + @param [out] children
1.342 + An array of cell indexes of selected cells (each index is 0 based),
1.343 + allocated by the server. The client must free it with CoTaskMemFree.
1.344 + @param [out] nChildren
1.345 + The number of cell indexes returned; the size of the returned array.
1.346 + @retval S_OK
1.347 + @retval S_FALSE if there are none, [out] values are NULL and 0 respectively
1.348 + */
1.349 + [propget] HRESULT selectedChildren
1.350 + (
1.351 + [in] long maxChildren,
1.352 + [out, size_is(,maxChildren), length_is(,*nChildren)] long **children,
1.353 + [out, retval] long *nChildren
1.354 + );
1.355 +
1.356 + /** @brief Returns a list of column indexes currently selected (0 based).
1.357 + @param [in] maxColumns
1.358 + This parameter is ignored. Refer to @ref _arrayConsideration
1.359 + "Special Consideration when using Arrays" for more details.
1.360 + @param [out] columns
1.361 + An array of column indexes of selected columns (each index is 0 based), allocated
1.362 + by the server. The client must free it with CoTaskMemFree.
1.363 + @param [out] nColumns
1.364 + The number of column indexes returned; the size of the returned array.
1.365 + @retval S_OK
1.366 + @retval S_FALSE if there are none, [out] values are NULL and 0 respectively
1.367 + */
1.368 + [propget] HRESULT selectedColumns
1.369 + (
1.370 + [in] long maxColumns,
1.371 + [out, size_is(,maxColumns), length_is(,*nColumns)] long **columns,
1.372 + [out, retval] long *nColumns
1.373 + );
1.374 +
1.375 + /** @brief Returns a list of row indexes currently selected (0 based).
1.376 + @param [in] maxRows
1.377 + This parameter is ignored. Refer to @ref _arrayConsideration
1.378 + "Special Consideration when using Arrays" for more details.
1.379 + @param [out] rows
1.380 + An array of row indexes of selected rows (each index is 0 based), allocated
1.381 + by the server. The client must free it with CoTaskMemFree.
1.382 + @param [out] nRows
1.383 + The number of row indexes returned; the size of the returned array.
1.384 + @retval S_OK
1.385 + @retval S_FALSE if there are none, [out] values are NULL and 0 respectively
1.386 + */
1.387 + [propget] HRESULT selectedRows
1.388 + (
1.389 + [in] long maxRows,
1.390 + [out, size_is(,maxRows), length_is(,*nRows)] long **rows,
1.391 + [out, retval] long *nRows
1.392 + );
1.393 +
1.394 + /** @brief Returns the summary description of the table. The returned object could be
1.395 + an IAccessible or an IAccessible2.
1.396 + @param [out] accessible
1.397 + Returns a reference to an implementation dependent accessible object
1.398 + representing the table's summary or a NULL pointer if the table
1.399 + does not support a summary.
1.400 + @retval S_OK
1.401 + @retval S_FALSE if there is nothing to return, [out] value is NULL
1.402 + */
1.403 + [propget] HRESULT summary
1.404 + (
1.405 + [out, retval] IUnknown **accessible
1.406 + );
1.407 +
1.408 + /** @brief Returns a boolean value indicating whether the specified column is
1.409 + completely selected.
1.410 + @param [in] column
1.411 + 0 based index of the column for which to determine whether it is selected.
1.412 + @param [out] isSelected
1.413 + Returns TRUE if the specified column is selected completely and FALSE otherwise.
1.414 + @retval S_OK
1.415 + @retval E_INVALIDARG if bad [in] passed, [out] value is FALSE
1.416 + */
1.417 + [propget] HRESULT isColumnSelected
1.418 + (
1.419 + [in] long column,
1.420 + [out, retval] boolean *isSelected
1.421 + );
1.422 +
1.423 + /** @brief Returns a boolean value indicating whether the specified row is completely
1.424 + selected.
1.425 + @param [in] row
1.426 + 0 based index of the row for which to determine whether it is selected.
1.427 + @param [out] isSelected
1.428 + Returns TRUE if the specified row is selected completely and FALSE otherwise.
1.429 + @retval S_OK
1.430 + @retval E_INVALIDARG if bad [in] passed, [out] value is FALSE
1.431 + */
1.432 + [propget] HRESULT isRowSelected
1.433 + (
1.434 + [in] long row,
1.435 + [out, retval] boolean *isSelected
1.436 + );
1.437 +
1.438 + /** @brief Returns a boolean value indicating whether the specified cell is selected.
1.439 + @param [in] row
1.440 + 0 based index of the row for the cell to determine whether it is selected.
1.441 + @param [in] column
1.442 + 0 based index of the column for the cell to determine whether it is selected.
1.443 + @param [out] isSelected
1.444 + Returns TRUE if the specified cell is selected and FALSE otherwise.
1.445 + @retval S_OK
1.446 + @retval E_INVALIDARG if bad [in] passed, [out] value is FALSE
1.447 + */
1.448 + [propget] HRESULT isSelected
1.449 + (
1.450 + [in] long row,
1.451 + [in] long column,
1.452 + [out, retval] boolean *isSelected
1.453 + );
1.454 +
1.455 + /** @brief Selects a row and unselects all previously selected rows.
1.456 + @param [in] row
1.457 + 0 based index of the row to be selected.
1.458 + @retval S_OK
1.459 + @retval E_INVALIDARG if bad [in] passed
1.460 + */
1.461 + HRESULT selectRow
1.462 + (
1.463 + [in] long row
1.464 + );
1.465 +
1.466 + /** @brief Selects a column and unselects all previously selected columns.
1.467 + @param [in] column
1.468 + 0 based index of the column to be selected.
1.469 + @retval S_OK
1.470 + @retval E_INVALIDARG if bad [in] passed
1.471 + */
1.472 + HRESULT selectColumn
1.473 + (
1.474 + [in] long column
1.475 + );
1.476 +
1.477 + /** @brief Unselects one row, leaving other selected rows selected (if any).
1.478 + @param [in] row
1.479 + 0 based index of the row to be unselected.
1.480 + @retval S_OK
1.481 + @retval E_INVALIDARG if bad [in] passed
1.482 + */
1.483 + HRESULT unselectRow
1.484 + (
1.485 + [in] long row
1.486 + );
1.487 +
1.488 + /** @brief Unselects one column, leaving other selected columns selected (if any).
1.489 + @param [in] column
1.490 + 0 based index of the column to be unselected.
1.491 + @retval S_OK
1.492 + @retval E_INVALIDARG if bad [in] passed
1.493 + */
1.494 + HRESULT unselectColumn
1.495 + (
1.496 + [in] long column
1.497 + );
1.498 +
1.499 + /** @brief Given a cell index, gets the row and column indexes and extents of a cell
1.500 + and whether or not it is selected.
1.501 +
1.502 + This is a convenience function. It is not mandatory to implement it.
1.503 + @param [in] index
1.504 + 0 based index of this cell in the table.
1.505 + @param [out] row
1.506 + 0 based row index.
1.507 + @param [out] column
1.508 + 0 based column index.
1.509 + @param [out] rowExtents
1.510 + Number of cells spanned by this cell in this row.
1.511 + @param [out] columnExtents
1.512 + Number of cells spanned by this cell in this column.
1.513 + @param [out] isSelected
1.514 + Indicates if the specified cell is selected.
1.515 + @retval S_OK
1.516 + @retval E_INVALIDARG if bad [in] passed, [out] values are 0s and FALSE respectively
1.517 + */
1.518 + [propget] HRESULT rowColumnExtentsAtIndex
1.519 + (
1.520 + [in] long index,
1.521 + [out] long *row,
1.522 + [out] long *column,
1.523 + [out] long *rowExtents,
1.524 + [out] long *columnExtents,
1.525 + [out, retval] boolean *isSelected
1.526 + );
1.527 +
1.528 + /** @brief Returns the type and extents describing how a table changed.
1.529 +
1.530 + Provided for use by the IA2_EVENT_TABLE_MODEL_CHANGED event handler.
1.531 +
1.532 + This data is only guaranteed to be valid while the thread notifying the event
1.533 + continues. Once the handler has returned, the validity of the data depends on
1.534 + how the server manages the life cycle of its objects. Also, note that the server
1.535 + may have different life cycle management strategies for controls depending on
1.536 + whether or not a control manages its children. Lists, trees, and tables can have
1.537 + a large number of children and thus it's possible that the child objects for those
1.538 + controls would only be created as needed. Servers should document their life cycle
1.539 + strategy as this will be of interest to assistive technology or script engines
1.540 + accessing data out of process or from other threads. Servers only need to save the
1.541 + most recent row and column values associated with the change and a scope of the
1.542 + entire application is adequate.
1.543 +
1.544 + @param [out] modelChange
1.545 + A struct of (type(insert, delete, update), firstRow, lastRow, firstColumn, lastColumn).
1.546 + @retval S_OK
1.547 + @retval S_FALSE if there is nothing to return, [out] value is NULL
1.548 + */
1.549 + [propget] HRESULT modelChange
1.550 + (
1.551 + [out, retval] IA2TableModelChange *modelChange
1.552 + );
1.553 +
1.554 +}
