michael@0: /************************************************************************* michael@0: * michael@0: * File Name (AccessibleTable2.idl) michael@0: * michael@0: * IAccessible2 IDL Specification michael@0: * michael@0: * Copyright (c) 2007, 2012 Linux Foundation michael@0: * Copyright (c) 2006 IBM Corporation michael@0: * Copyright (c) 2000, 2006 Sun Microsystems, Inc. michael@0: * All rights reserved. michael@0: * michael@0: * michael@0: * Redistribution and use in source and binary forms, with or without michael@0: * modification, are permitted provided that the following conditions michael@0: * are met: michael@0: * michael@0: * 1. Redistributions of source code must retain the above copyright michael@0: * notice, this list of conditions and the following disclaimer. michael@0: * michael@0: * 2. Redistributions in binary form must reproduce the above michael@0: * copyright notice, this list of conditions and the following michael@0: * disclaimer in the documentation and/or other materials michael@0: * provided with the distribution. michael@0: * michael@0: * 3. Neither the name of the Linux Foundation nor the names of its michael@0: * contributors may be used to endorse or promote products michael@0: * derived from this software without specific prior written michael@0: * permission. michael@0: * michael@0: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND michael@0: * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, michael@0: * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF michael@0: * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE michael@0: * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR michael@0: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, michael@0: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT michael@0: * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; michael@0: * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) michael@0: * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN michael@0: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR michael@0: * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, michael@0: * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. michael@0: * michael@0: * This BSD License conforms to the Open Source Initiative "Simplified michael@0: * BSD License" as published at: michael@0: * http://www.opensource.org/licenses/bsd-license.php michael@0: * michael@0: * IAccessible2 is a trademark of the Linux Foundation. The IAccessible2 michael@0: * mark may be used in accordance with the Linux Foundation Trademark michael@0: * Policy to indicate compliance with the IAccessible2 specification. michael@0: * michael@0: ************************************************************************/ michael@0: michael@0: import "objidl.idl"; michael@0: import "oaidl.idl"; michael@0: import "oleacc.idl"; michael@0: import "Accessible2.idl"; michael@0: import "IA2CommonTypes.idl"; michael@0: michael@0: /** @brief This interface gives access to a two-dimensional table. michael@0: michael@0: Please also refer to the IAccessibleTableCell interface. michael@0: michael@0: If you want to support older applications you should also support the michael@0: IAccessibleTable inteface. michael@0: */ michael@0: [object, uuid(6167f295-06f0-4cdd-a1fa-02e25153d869)] michael@0: interface IAccessibleTable2 : IUnknown michael@0: { michael@0: michael@0: /** @brief Returns the accessible object at the specified row and column in michael@0: the table. This object could be an IAccessible or an IAccessible2. michael@0: @param [in] row michael@0: The 0 based row index for which to retrieve the cell. michael@0: @param [in] column michael@0: The 0 based column index for which to retrieve the cell. michael@0: @param [out] cell michael@0: If both row and column index are valid then the corresponding accessible michael@0: object is returned that represents the requested cell regardless of whether michael@0: the cell is currently visible (on the screen). michael@0: @retval S_OK michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: [propget] HRESULT cellAt michael@0: ( michael@0: [in] long row, michael@0: [in] long column, michael@0: [out, retval] IUnknown **cell michael@0: ); michael@0: michael@0: /** @brief Returns the caption for the table. The returned object could be michael@0: an IAccessible or an IAccessible2. michael@0: @param [out] accessible michael@0: If the table has a caption then a reference to it is returned, else a NULL michael@0: pointer is returned. michael@0: @retval S_OK michael@0: @retval S_FALSE if there is nothing to return, [out] value is NULL michael@0: @deprecated use a describedBy relation michael@0: */ michael@0: [propget] HRESULT caption michael@0: ( michael@0: [out, retval] IUnknown **accessible michael@0: ); michael@0: michael@0: /** @brief Returns the description text of the specified column in the table. michael@0: @param [in] column michael@0: The 0 based index of the column for which to retrieve the description. michael@0: @param [out] description michael@0: Returns the description text of the specified column in the table if such a michael@0: description exists. Otherwise a NULL pointer is returned. michael@0: @retval S_OK michael@0: @retval S_FALSE if there is nothing to return, [out] value is NULL michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: [propget] HRESULT columnDescription michael@0: ( michael@0: [in] long column, michael@0: [out, retval] BSTR *description michael@0: ); michael@0: michael@0: michael@0: /** @brief Returns the total number of columns in table michael@0: @param [out] columnCount michael@0: Number of columns in table (including columns outside the current viewport) michael@0: @retval S_OK michael@0: */ michael@0: [propget] HRESULT nColumns michael@0: ( michael@0: [out, retval] long *columnCount michael@0: ); michael@0: michael@0: /** @brief Returns the total number of rows in table michael@0: @param [out] rowCount michael@0: Number of rows in table (including rows outside the current viewport) michael@0: @retval S_OK michael@0: */ michael@0: [propget] HRESULT nRows michael@0: ( michael@0: [out, retval] long *rowCount michael@0: ); michael@0: michael@0: /** @brief Returns the total number of selected cells michael@0: @param [out] cellCount michael@0: Number of cells currently selected michael@0: @retval S_OK michael@0: */ michael@0: [propget] HRESULT nSelectedCells michael@0: ( michael@0: [out, retval] long *cellCount michael@0: ); michael@0: michael@0: /** @brief Returns the total number of selected columns michael@0: @param [out] columnCount michael@0: Number of columns currently selected michael@0: @retval S_OK michael@0: */ michael@0: [propget] HRESULT nSelectedColumns michael@0: ( michael@0: [out, retval] long *columnCount michael@0: ); michael@0: michael@0: /** @brief Returns the total number of selected rows michael@0: @param [out] rowCount michael@0: Number of rows currently selected michael@0: @retval S_OK michael@0: */ michael@0: [propget] HRESULT nSelectedRows michael@0: ( michael@0: [out, retval] long *rowCount michael@0: ); michael@0: michael@0: /** @brief Returns the description text of the specified row in the table. michael@0: @param [in] row michael@0: The 0 based index of the row for which to retrieve the description. michael@0: @param [out] description michael@0: Returns the description text of the specified row in the table if such a michael@0: description exists. Otherwise a NULL pointer is returned. michael@0: @retval S_OK michael@0: @retval S_FALSE if there is nothing to return, [out] value is NULL michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: [propget] HRESULT rowDescription michael@0: ( michael@0: [in] long row, michael@0: [out, retval] BSTR *description michael@0: ); michael@0: michael@0: /** @brief Returns a list of accessibles currently selected. michael@0: @param [out] cells michael@0: Pointer to an array of references to selected accessibles. The array is michael@0: allocated by the server with CoTaskMemAlloc and freed by the client with michael@0: CoTaskMemFree. michael@0: @param [out] nSelectedCells michael@0: The number of accessibles returned; the size of the returned array. michael@0: @retval S_OK michael@0: @retval S_FALSE if there are none, [out] values are NULL and 0 respectively michael@0: */ michael@0: [propget] HRESULT selectedCells michael@0: ( michael@0: [out, size_is(,*nSelectedCells)] IUnknown ***cells, michael@0: [out, retval] long *nSelectedCells michael@0: ); michael@0: michael@0: /** @brief Returns a list of column indexes currently selected (0 based). michael@0: @param [out] selectedColumns michael@0: A pointer to an array of column indexes of selected columns (each index is michael@0: 0 based). The array is allocated by the server with CoTaskMemAlloc and michael@0: freed by the client with CoTaskMemFree. michael@0: @param [out] nColumns michael@0: The number of column indexes returned; the size of the returned array. michael@0: @retval S_OK michael@0: @retval S_FALSE if there are none, [out] values are NULL and 0 respectively michael@0: */ michael@0: [propget] HRESULT selectedColumns michael@0: ( michael@0: [out, size_is(,*nColumns)] long **selectedColumns, michael@0: [out, retval] long *nColumns michael@0: ); michael@0: michael@0: /** @brief Returns a list of row indexes currently selected (0 based). michael@0: @param [out] selectedRows michael@0: An array of row indexes of selected rows (each index is 0 based). The array michael@0: is allocated by the server with CoTaskMemAlloc and freed by the client with michael@0: CoTaskMemFree. michael@0: @param [out] nRows michael@0: The number of row indexes returned; the size of the returned array. michael@0: @retval S_OK michael@0: @retval S_FALSE if there are none, [out] values are NULL and 0 respectively michael@0: */ michael@0: [propget] HRESULT selectedRows michael@0: ( michael@0: [out, size_is(,*nRows)] long **selectedRows, michael@0: [out, retval] long *nRows michael@0: ); michael@0: michael@0: /** @brief Returns the summary description of the table. The returned object could be michael@0: an IAccessible or an IAccessible2. michael@0: @param [out] accessible michael@0: Returns a reference to an implementation dependent accessible object michael@0: representing the table's summary or a NULL pointer if the table michael@0: does not support a summary. michael@0: @retval S_OK michael@0: @retval S_FALSE if there is nothing to return, [out] value is NULL michael@0: @deprecated Use the labeledBy relation michael@0: */ michael@0: [propget] HRESULT summary michael@0: ( michael@0: [out, retval] IUnknown **accessible michael@0: ); michael@0: michael@0: /** @brief Returns a boolean value indicating whether the specified column is michael@0: completely selected. michael@0: @param [in] column michael@0: 0 based index of the column for which to determine whether it is selected. michael@0: @param [out] isSelected michael@0: Returns TRUE if the specified column is selected completely and FALSE otherwise. michael@0: @retval S_OK michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: [propget] HRESULT isColumnSelected michael@0: ( michael@0: [in] long column, michael@0: [out, retval] boolean *isSelected michael@0: ); michael@0: michael@0: /** @brief Returns a boolean value indicating whether the specified row is completely michael@0: selected. michael@0: @param [in] row michael@0: 0 based index of the row for which to determine whether it is selected. michael@0: @param [out] isSelected michael@0: Returns TRUE if the specified row is selected completely and FALSE otherwise. michael@0: @retval S_OK michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: [propget] HRESULT isRowSelected michael@0: ( michael@0: [in] long row, michael@0: [out, retval] boolean *isSelected michael@0: ); michael@0: michael@0: /** @brief Selects a row and unselects all previously selected rows. michael@0: michael@0: The behavior should mimic that of the application, but for those applications michael@0: which do not have a means in the GUI to select a full row of cells the behavior michael@0: should be as follows: First any selected rows in the table are unselected. Then michael@0: the entire row of cells for the specified row is selected. If any of the michael@0: cells in the selected row span additional rows, the cells in those rows michael@0: are also selected. michael@0: @param [in] row michael@0: 0 based index of the row to be selected. michael@0: @retval S_OK michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: HRESULT selectRow michael@0: ( michael@0: [in] long row michael@0: ); michael@0: michael@0: /** @brief Selects a column and unselects all previously selected columns. michael@0: michael@0: The behavior should mimic that of the application, but for those applications michael@0: which do not have a means in the GUI to select a full column of cells the behavior michael@0: should be as follows: First any selected columns in the table are unselected. Then michael@0: the entire column of cells for the specified column is selected. If any of the michael@0: cells in the selected column span additional columns, the cells in those columns michael@0: are also selected. michael@0: @param [in] column michael@0: 0 based index of the column to be selected. michael@0: @retval S_OK michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: HRESULT selectColumn michael@0: ( michael@0: [in] long column michael@0: ); michael@0: michael@0: /** @brief Unselects one row, leaving other selected rows selected (if any). michael@0: michael@0: The behavior should mimic that of the application, but for those applications michael@0: which do not have a means in the GUI to unselect a full row of cells the michael@0: behavior should be as follows: The entire row of cells for the specified michael@0: row is unselected. If any of the cells in the selected row span additional michael@0: rows, the cells in those rows are also unselected. michael@0: @param [in] row michael@0: 0 based index of the row to be unselected. michael@0: @retval S_OK michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: HRESULT unselectRow michael@0: ( michael@0: [in] long row michael@0: ); michael@0: michael@0: /** @brief Unselects one column, leaving other selected columns selected (if any). michael@0: michael@0: The behavior should mimic that of the application, but for those applications michael@0: which do not have a means in the GUI to unselect a full column of cells the michael@0: behavior should be as follows: The entire column of cells for the specified michael@0: column is unselected. If any of the cells in the selected column span additional michael@0: columns, the cells in those columns are also unselected. michael@0: @param [in] column michael@0: 0 based index of the column to be unselected. michael@0: @retval S_OK michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: HRESULT unselectColumn michael@0: ( michael@0: [in] long column michael@0: ); michael@0: michael@0: /** @brief Returns the type and extents describing how a table changed. michael@0: michael@0: Provided for use by the IA2_EVENT_TABLE_MODEL_CHANGED event handler. michael@0: michael@0: This data is only guaranteed to be valid while the thread notifying the event michael@0: continues. Once the handler has returned, the validity of the data depends on michael@0: how the server manages the life cycle of its objects. Also, note that the server michael@0: may have different life cycle management strategies for controls depending on michael@0: whether or not a control manages its children. Lists, trees, and tables can have michael@0: a large number of children and thus it's possible that the child objects for those michael@0: controls would only be created as needed. Servers should document their life cycle michael@0: strategy as this will be of interest to assistive technology or script engines michael@0: accessing data out of process or from other threads. Servers only need to save the michael@0: most recent row and column values associated with the change and a scope of the michael@0: entire application is adequate. michael@0: michael@0: @param [out] modelChange michael@0: A struct of (type(insert, delete, update), firstRow, lastRow, firstColumn, lastColumn). michael@0: @retval S_OK michael@0: @retval S_FALSE if there is nothing to return, [out] value is NULL michael@0: */ michael@0: [propget] HRESULT modelChange michael@0: ( michael@0: [out, retval] IA2TableModelChange *modelChange michael@0: ); michael@0: michael@0: }