/*************************************************************************
 *
 *  File Name (AccessibleTable2.idl)
 *
 *  IAccessible2 IDL Specification
 *
 *  Copyright (c) Linux Foundation 2007, 2009
 *  Copyright (c) IBM Corp. 2006
 *  Copyright (c) Sun Microsystems, Inc. 2000, 2006
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License version 2.1, as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 *
 ************************************************************************/

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.

 Please also refer to the IAccessibleTableCell interface.

 If you want to support older applications you should also support the
  IAccessibleTable inteface.
*/
[object, uuid(6167f295-06f0-4cdd-a1fa-02e25153d869)]
interface IAccessibleTable2 : 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] cell
    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 cellAt
    (
     [in] long row, 
     [in] long column,
     [out, retval] IUnknown **cell
    );

  /** @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 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 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 nSelectedCells
    (
     [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 a list of accessibles currently selected.
   @param [out] cells
    Pointer to an array of references to selected accessibles.  The array is
    allocated by the server.  Free it with CoTaskMemFree.
   @param [out] nSelectedCells
    The number of accessibles 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 selectedCells
    (
     [out, size_is(,*nSelectedCells,)] IUnknown ***cells,
     [out, retval] long *nSelectedCells
    );

  /** @brief Returns a list of column indexes currently selected (0 based).
   @param [out] selectedColumns
    A pointer to an array of column indexes of selected columns (each index is
    0 based).  The array is allocated by the server. 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
    (
     [out, size_is(,*nColumns)] long **selectedColumns,
     [out, retval] long *nColumns
    );

  /** @brief Returns a list of row indexes currently selected (0 based).
   @param [out] selectedRows
    An array of row indexes of selected rows (each index is 0 based), allocated
    by the server. 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
    (
     [out, size_is(,*nRows)] long **selectedRows, 
     [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 Selects a row and unselects all previously selected rows.

   The behavior should mimic that of the application, but for those applications
    which do not have a means in the GUI to select a full row of cells the behavior 
    should be as follows:  First any selected rows in the table are unselected.  Then
    the entire row of cells for the specified row is selected.  If any of the
    cells in the selected row span additional rows, the cells in those rows
    are also selected. 
   @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.

   The behavior should mimic that of the application, but for those applications
    which do not have a means in the GUI to select a full column of cells the behavior 
    should be as follows:  First any selected columns in the table are unselected.  Then
    the entire column of cells for the specified column is selected.  If any of the
    cells in the selected column span additional columns, the cells in those columns
    are also selected. 
   @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).

   The behavior should mimic that of the application, but for those applications
    which do not have a means in the GUI to unselect a full row of cells the
    behavior should be as follows:  The entire row of cells for the specified
    row is unselected.  If any of the cells in the selected row span additional
    rows, the cells in those rows are also unselected. 
   @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).

   The behavior should mimic that of the application, but for those applications
    which do not have a means in the GUI to unselect a full column of cells the
    behavior should be as follows:  The entire column of cells for the specified
    column is unselected.  If any of the cells in the selected column span additional
    columns, the cells in those columns are also unselected. 
   @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 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
    );

}