michael@0: /*************************************************************************
michael@0:  *
michael@0:  *  File Name (AccessibleTable.idl)
michael@0:  * 
michael@0:  *  IAccessible2 IDL Specification 
michael@0:  * 
michael@0:  *  Copyright (c) 2007, 2013 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:  Typically all accessible objects that represent cells or cell-clusters of a table 
michael@0:   will be at the same time children of the table.  In this case IAccessible2::indexInParent
michael@0:   will return the child index which then can be used when calling IAccessibleTable::rowIndex
michael@0:   and IAccessibleTable::columnIndex.
michael@0: 
michael@0:  However, in some cases that kind of implementation will not be possible.  When
michael@0:   the table cells are not direct children of a table, the object representing
michael@0:   the cell can define a "table-cell-index" object attribute identifying the 0 
michael@0:   based table cell index.  This object attribute is obtained by parsing the
michael@0:   attribute string returned by IAccessible2::attributes.  The "table-cell-index"
michael@0:   attribute can be used just like a child index of the typical case.  ATs should 
michael@0:   first test for the presence of the "table-cell-index" attribute and if it is not
michael@0:   present then IAccessible2::indexInParent can be used as in the typical case
michael@0:   where cells are direct children of the table.
michael@0:               
michael@0:  The range of valid coordinates for this interface are implementation dependent.  
michael@0:   However, that range includes at least the intervals from the from the first row 
michael@0:   or column with the index 0 up to the last (but not including) used row or column 
michael@0:   as returned by IAccessibleTable::nRows and IAccessibleTable::nColumns.
michael@0: 
michael@0:  Note that newer implementations are now using IAccessibleTable2 and IAccessibleTableCell
michael@0:   rather than this interface.
michael@0: */
michael@0: [object, uuid(35AD8070-C20C-4fb4-B094-F4F7275DD469)]
michael@0: interface IAccessibleTable : 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] accessible
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, [out] value is NULL 
michael@0:   */
michael@0:   [propget] HRESULT accessibleAt
michael@0:     (
michael@0:      [in] long row, 
michael@0:      [in] long column,
michael@0:      [out, retval] IUnknown **accessible 
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:   */
michael@0:   [propget] HRESULT caption
michael@0:     (
michael@0:      [out, retval] IUnknown **accessible 
michael@0:     );
michael@0: 	  
michael@0:   /** @brief Translates the given row and column indexes into the corresponding cell index.
michael@0:    @param [in] rowIndex
michael@0:     0 based row index for the cell.
michael@0:    @param [in] columnIndex
michael@0:     0 based column index for the cell.
michael@0:    @param [out] cellIndex
michael@0:     Returns the 0 based index of the cell at the specified row and column indexes.
michael@0:    @retval S_OK
michael@0:    @retval E_INVALIDARG if bad [in] passed, [out] value is 0
michael@0:    @note The returned value is not necessarily a child index of the immediate parent.
michael@0:     In cases where the table cells are not direct children of the table the index 
michael@0:     is actually the cell index, i.e. conceptually it's an index into a one dimensional
michael@0: 	array of cells laid out in row order.
michael@0:   */
michael@0:   [propget] HRESULT childIndex
michael@0: 	(
michael@0: 	 [in] long rowIndex,
michael@0: 	 [in] long columnIndex,
michael@0: 	 [out, retval] long *cellIndex
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, [out] value is NULL
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:   /** @brief Returns the number of columns occupied by the accessible object 
michael@0:     at the specified row and column in the table.
michael@0:         
michael@0:    The result is greater than 1 if the specified cell spans multiple columns.
michael@0:    @param [in] row
michael@0:     0 based row index of the accessible for which to return the column extent.
michael@0:    @param [in] column
michael@0:     0 based column index of the accessible for which to return the column extent.
michael@0:    @param [out] nColumnsSpanned
michael@0:     Returns the 1 based column extent of the specified cell.
michael@0:    @retval S_OK
michael@0:    @retval E_INVALIDARG if bad [in] passed, [out] value is 0
michael@0:   */
michael@0:   [propget] HRESULT columnExtentAt
michael@0:     (
michael@0:      [in] long row,
michael@0:      [in] long column,
michael@0:      [out, retval] long *nColumnsSpanned 
michael@0:     );
michael@0: 
michael@0:   /** @brief Returns the column headers as an %IAccessibleTable object.
michael@0:         
michael@0:    Content and size of the returned table are implementation dependent.
michael@0:    @param [out] accessibleTable
michael@0:     The column header
michael@0:    @param [out] startingRowIndex
michael@0:     The 0 based row index where the header starts, usually 0.
michael@0:    @retval S_OK
michael@0:    @retval S_FALSE if there is no header, [out] values are NULL and 0 respectively 
michael@0:   */
michael@0:   [propget] HRESULT columnHeader
michael@0:     (
michael@0:      [out] IAccessibleTable **accessibleTable,
michael@0: 	 [out, retval] long *startingRowIndex
michael@0:     );
michael@0: 
michael@0:   /** @brief Translates the given cell index into the corresponding column index.
michael@0:    @param [in] cellIndex
michael@0:     0 based index of the cell in the parent or closest ancestor table.  Typically this
michael@0: 	is the value returned from IAccessible2::indexInParent, but in the case where the 
michael@0: 	table cells are not direct children of the table this is the cell index specified 
michael@0: 	by the "table-cell-index" object attribute obtained from parsing the attributes 
michael@0: 	string returned by calling IAccessible2::attributes on the cell object.
michael@0:    @param [out] columnIndex
michael@0:     Returns the 0 based column index of the cell of the specified child or the index of 
michael@0:     the first column if the child spans multiple columns.
michael@0:    @retval S_OK
michael@0:    @retval E_INVALIDARG if bad [in] passed, [out] value is 0
michael@0:   */
michael@0:   [propget] HRESULT columnIndex
michael@0:     (
michael@0: 	 [in] long cellIndex,
michael@0: 	 [out, retval] long *columnIndex
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 nSelectedChildren
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, [out] value is NULL
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 the number of rows occupied by the accessible object 
michael@0:     at the specified row and column in the table.
michael@0:         
michael@0:    The result is greater than 1 if the specified cell spans multiple rows.
michael@0:    @param [in] row
michael@0:     0 based row index of the accessible for which to return the row extent.
michael@0:    @param [in] column
michael@0:     0 based column index of the accessible for which to return the row extent.
michael@0:    @param [out] nRowsSpanned
michael@0:     Returns the row extent of the specified cell.
michael@0:    @retval S_OK
michael@0:    @retval E_INVALIDARG if bad [in] passed, [out] value is 0
michael@0:   */
michael@0:   [propget] HRESULT rowExtentAt
michael@0:     (
michael@0:      [in] long row,
michael@0:      [in] long column,
michael@0:      [out, retval] long *nRowsSpanned
michael@0:     );
michael@0: 
michael@0:   /** @brief Returns the row headers as an %IAccessibleTable object.
michael@0:         
michael@0:    Content and size of the returned table are implementation dependent.
michael@0:    @param [out] accessibleTable
michael@0:     The row header.
michael@0:    @param [out] startingColumnIndex
michael@0:     The 0 based column index where the header starts, usually 0.
michael@0:    @retval S_OK
michael@0:    @retval S_FALSE if there is no header, [out] values are NULL and 0 respectively 
michael@0:   */
michael@0:   [propget] HRESULT rowHeader
michael@0:     (
michael@0:      [out] IAccessibleTable **accessibleTable,
michael@0: 	 [out, retval] long *startingColumnIndex
michael@0:     );
michael@0: 
michael@0:   /** @brief Translates the given cell index into a row index.
michael@0:    @param [in] cellIndex
michael@0:     0 based index of the cell in the parent or closest ancestor table.  Typically this 
michael@0: 	is the value returned from IAccessible2::indexInParent, but in the case where the 
michael@0: 	table cells are not direct children of the table this is the cell index specified 
michael@0: 	by the "table-cell-index" object attribute obtained from parsing the attributes 
michael@0: 	string returned by calling IAccessible2::attributes on the cell object.
michael@0:    @param [out] rowIndex
michael@0:     0 based row index
michael@0:    @retval S_OK
michael@0:    @retval E_INVALIDARG if bad [in] passed, [out] value is 0
michael@0:   */
michael@0:   [propget] HRESULT rowIndex
michael@0:     (
michael@0: 	 [in] long cellIndex,
michael@0: 	 [out, retval] long *rowIndex 
michael@0: 	);
michael@0: 
michael@0:   /** @brief Returns a list of cell indexes currently selected (0 based).
michael@0:    @param [in] maxChildren
michael@0:     This parameter is ignored. Refer to @ref _arrayConsideration
michael@0: 	"Special Consideration when using Arrays" for more details.
michael@0:    @param [out] children
michael@0:     An array of cell indexes of selected cells (each index is 0 based), 
michael@0: 	allocated by the server. The client must free it with CoTaskMemFree.
michael@0:    @param [out] nChildren
michael@0:     The number of cell 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 selectedChildren
michael@0:     (
michael@0:      [in] long maxChildren,
michael@0:      [out, size_is(,maxChildren), length_is(,*nChildren)] long **children,
michael@0:      [out, retval] long *nChildren
michael@0:     );
michael@0: 
michael@0:   /** @brief Returns a list of column indexes currently selected (0 based).
michael@0:    @param [in] maxColumns
michael@0:     This parameter is ignored. Refer to @ref _arrayConsideration 
michael@0: 	"Special Consideration when using Arrays" for more details.
michael@0:    @param [out] columns
michael@0: 	An array of column indexes of selected columns (each index is 0 based), allocated
michael@0: 	by the server. The client must free it 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:      [in] long maxColumns,
michael@0:      [out, size_is(,maxColumns), length_is(,*nColumns)] long **columns,
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 [in] maxRows
michael@0:     This parameter is ignored. Refer to @ref _arrayConsideration
michael@0: 	"Special Consideration when using Arrays" for more details.
michael@0:    @param [out] rows
michael@0:     An array of row indexes of selected rows (each index is 0 based), allocated
michael@0: 	by the server. The client must free it with 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:      [in] long maxRows, 
michael@0:      [out, size_is(,maxRows), length_is(,*nRows)] long **rows, 
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:   */
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, [out] value is FALSE
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, [out] value is FALSE
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 Returns a boolean value indicating whether the specified cell is selected.
michael@0:    @param [in] row
michael@0:     0 based index of the row for the cell to determine whether it is selected.
michael@0:    @param [in] column
michael@0:     0 based index of the column for the cell to determine whether it is selected.
michael@0:    @param [out] isSelected
michael@0:     Returns TRUE if the specified cell is selected and FALSE otherwise.
michael@0:    @retval S_OK
michael@0:    @retval E_INVALIDARG if bad [in] passed, [out] value is FALSE
michael@0:   */
michael@0:   [propget] HRESULT isSelected
michael@0:     (
michael@0:      [in] long row,
michael@0:      [in] long column,
michael@0:      [out, retval] boolean *isSelected 
michael@0:     );
michael@0: 
michael@0:   /** @brief Selects a row and unselects all previously selected rows.
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:    @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:    @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:    @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 Given a cell index, gets the row and column indexes and extents of a cell 
michael@0:     and whether or not it is selected.
michael@0: 
michael@0:    This is a convenience function.  It is not mandatory to implement it.
michael@0:    @param [in] index
michael@0:     0 based index of this cell in the table.
michael@0:    @param [out] row
michael@0:     0 based row index.
michael@0:    @param [out] column
michael@0:     0 based column index.
michael@0:    @param [out] rowExtents
michael@0:     Number of cells spanned by this cell in this row.
michael@0:    @param [out] columnExtents
michael@0:     Number of cells spanned by this cell in this column.
michael@0:    @param [out] isSelected
michael@0:     Indicates if the specified cell is selected.
michael@0:    @retval S_OK
michael@0:    @retval E_INVALIDARG if bad [in] passed, [out] values are 0s and FALSE respectively
michael@0:   */
michael@0:   [propget] HRESULT rowColumnExtentsAtIndex
michael@0:     (
michael@0: 	 [in] long index, 
michael@0: 	 [out] long *row,  
michael@0: 	 [out] long *column,
michael@0: 	 [out] long *rowExtents,
michael@0: 	 [out] long *columnExtents,
michael@0: 	 [out, retval] boolean *isSelected
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: }