offapi/com/sun/star/accessibility/XAccessibleTable.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*************************************************************************
   3  *
   4  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   5  *
   6  * Copyright 2000, 2010 Oracle and/or its affiliates.
   7  *
   8  * OpenOffice.org - a multi-platform office productivity suite
   9  *
  10  * This file is part of OpenOffice.org.
  11  *
  12  * OpenOffice.org is free software: you can redistribute it and/or modify
  13  * it under the terms of the GNU Lesser General Public License version 3
  14  * only, as published by the Free Software Foundation.
  15  *
  16  * OpenOffice.org 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
  19  * GNU Lesser General Public License version 3 for more details
  20  * (a copy is included in the LICENSE file that accompanied this code).
  21  *
  22  * You should have received a copy of the GNU Lesser General Public License
  23  * version 3 along with OpenOffice.org.  If not, see
  24  * <http://www.openoffice.org/license.html>
  25  * for a copy of the LGPLv3 License.
  26  *
  27  ************************************************************************/
  28
  29 #ifndef __com_sun_star_accessibility_XAccessibleTable_idl__
  30 #define __com_sun_star_accessibility_XAccessibleTable_idl__
  31
  32 #include <com/sun/star/uno/XInterface.idl>
  33 #include <com/sun/star/lang/IndexOutOfBoundsException.idl>
  34
  35 module com { module sun { module star { module accessibility {
  36
  37  published interface XAccessible;
  38
  39 /** Implement this interface to give access to a two-dimensional table.
  40
  41    <p>The <type>XAccessibleTable</type> interface is used to represent
  42    two-dimensional tables.  This interface combines the two interfaces
  43    <code>javax.accessibility.AccessibleTable</code> and
  44    <code>javax.accessibility.AccessibleExtendedTable</code> of the Java Accessibility API
  45    (version 1.4).</p>
  46
  47    <p>All <type>XAccessible</type> objects that represent cells or
  48    cell-clusters of a table have to be at the same time children of the
  49    table.  This is necessary to be able to convert row and column indices
  50    into child indices and vice versa with the methods
  51    <member>XAccessibleTable::getAccessibleIndex</member>,
  52    <member>XAccessibleTable::getAccessibleRow</member>, and
  53    <member>XAccessibleTable::getAccessibleColumn</member>.</p>
  54
  55    <p>The range of valid coordinates for this interface are implementation
  56    dependent.  However, that range includes at least the intervals from the
  57    from the first row or column with the index 0 up to the last (but not
  58    including) used row or column as returned by
  59    <member>XAccessibleTable::getAccessibleRowCount</member> and
  60    <member>XAccessibleTable::getAccessibleColumnCount</member>.  In case of
  61    the Calc the current range of valid indices for retrieving data include
  62    the maximal table size--256 columns and 32000 rows--minus one.</p>
  63
  64     @since OOo 1.1.2
  65 */
  66 published interface XAccessibleTable : ::com::sun::star::uno::XInterface
  67 {
  68     /** Returns the number of used rows in the table.
  69
  70         <p>The implementation, however, may allow the access of columns
  71         beyond this number.</p>
  72
  73         @return
  74             Returns the number of used rows in the table or 0 for an empty
  75             table.
  76     */
  77     long getAccessibleRowCount ();
  78
  79     /** Returns the number of used columns in the table.
  80
  81         <p>The implementation, however, may allow the access of columns
  82         beyond this number.</p>
  83
  84         @return
  85             Returns the number of used columns in the table or 0 for an empty
  86             table.
  87     */
  88     long getAccessibleColumnCount ();
  89
  90     /** Returns the description text of the specified row in the
  91         table.
  92
  93         @param nRow
  94             The index of the row for which to retrieve the description.
  95
  96         @return
  97             Returns the description text of the specified row in the table
  98             if such a description exists.  Otherwise an empty string is
  99             returned.
 100         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 101             if the specified row index is not valid, i.e. lies not inside
 102             the valid range of 0 up to
 103             <member>XAccessibleTable::getAccessibleRowCount()</member> - 1.
 104
 105     */
 106     string getAccessibleRowDescription ([in] long nRow)
 107         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 108
 109     /** Returns the description text of the specified column in the
 110         table.
 111
 112         @param nColumn
 113             The index of the column for which to retrieve the description.
 114
 115         @return
 116             Returns the description text of the specified row in the table
 117             if such a description exists.  Otherwise an empty string is
 118             returned.
 119         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 120             if the specified column index is not valid, i.e. lies not inside
 121             the valid range of 0 up to
 122             <member>XAccessibleTable::getAccessibleColumnCount()</member> - 1.
 123     */
 124     string getAccessibleColumnDescription ([in] long nColumn)
 125         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 126
 127     /** Returns the number of rows occupied by the Accessible at the
 128         specified row and column in the table.
 129
 130         <p>The result differs from 1 if the specified cell spans multiple
 131         rows.</p>
 132
 133         @param nRow
 134             Row index of the accessible for which to return the column
 135             extent.
 136
 137         @param nColumn
 138             Column index of the accessible for which to return the column
 139             extent.
 140
 141         @return
 142             Returns the row extent of the specified cell.
 143
 144         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 145             if the specified row index is not valid, i.e. lies not inside
 146             the valid range of 0 up to
 147             <member>XAccessibleTable::getAccessibleRowCount()</member> - 1.
 148     */
 149     long getAccessibleRowExtentAt ([in] long nRow, [in] long nColumn)
 150         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 151
 152     /** Returns the number of columns occupied by the Accessible at the
 153         specified row and column in the table.
 154
 155         <p>The result differs from 1 if the specified cell spans multiple
 156         columns.</p>
 157
 158         @param nRow
 159             Row index of the accessible for which to return the column
 160             extent.
 161
 162         @param nColumn
 163             Column index of the accessible for which to return the column
 164             extent.
 165
 166         @return
 167             Returns the column extent of the specified.
 168
 169         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 170             if the specified column index is not valid, i.e. lies not inside
 171             the valid range of 0 up to
 172             <member>XAccessibleTable::getAccessibleColumnCount()</member> - 1.
 173     */
 174     long getAccessibleColumnExtentAt ([in] long nRow, [in] long nColumn)
 175         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 176
 177     /** Returns the row headers as an <type>XAccessibleTable</type>
 178         object.
 179
 180         <p>Content and size of the returned table are implementation
 181         dependent.</p>
 182
 183         @return
 184             Returns always a valid reference to an
 185             <type>XAccessibleTable</type> object.
 186     */
 187     XAccessibleTable getAccessibleRowHeaders ();
 188
 189     /** Returns the column headers as an <type>XAccessibleTable</type>
 190         object.
 191
 192         <p>Content and size of the returned table are implementation
 193         dependent.</p>
 194
 195         @return
 196             Returns always a valid reference to an
 197             <type>XAccessibleTable</type> object.
 198     */
 199     XAccessibleTable getAccessibleColumnHeaders ();
 200
 201     /** Returns a list of the indices of completely selected rows in a
 202         table.
 203
 204         @return
 205             The returned sequence contains indices of all completely
 206             selected rows in the table.  This sequence is in ascending
 207             order.  If no row is selected then the sequence is empty.
 208     */
 209     sequence<long> getSelectedAccessibleRows ();
 210
 211     /** Returns a list of the indices of completely selected columns in a
 212         table.
 213
 214         @return
 215             The returned sequence contains indices of all completely
 216             selected columns in the table.  This sequence is in ascending
 217             order.  If no column is selected then the sequence is empty.
 218     */
 219     sequence<long> getSelectedAccessibleColumns ();
 220
 221     /** Returns a boolean value indicating whether the specified row is
 222         completely selected.
 223
 224         @param nRow
 225             Index of the row for which to determine whether it is selected.
 226
 227         @return
 228             Returns <TRUE/> if the specified row is selected completely and
 229             <FALSE/> otherwise.
 230
 231         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 232             if the specified row index is not valid, i.e. lies not inside
 233             the valid range of 0 up to
 234             <member>XAccessibleTable::getAccessibleRowCount()</member> - 1.
 235     */
 236     boolean isAccessibleRowSelected ([in] long nRow)
 237         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 238
 239     /** Returns a boolean value indicating whether the specified column
 240         is completely selected.
 241
 242         @param nColumn
 243             Index of the column for which to determine whether it is
 244             selected.
 245
 246         @return
 247             Returns <TRUE/> if the specified column is selected completely
 248             and <FALSE/> otherwise.
 249
 250         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 251             if the specified column index is not valid, i.e. lies not inside
 252             the valid range of 0 up to
 253             <member>XAccessibleTable::getAccessibleColumnCount()</member> - 1.
 254     */
 255     boolean isAccessibleColumnSelected ([in] long nColumn)
 256         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 257
 258     /** Returns the <type>XAccessible</type> object at the specified row
 259         and column in the table.
 260
 261         <p>This method has been renamed from the Java name
 262         <code>getAccessibleAt</code> to
 263         <member>XAccessibleTable::getAccessibleCellAt</member> to avoid
 264         ambiguities with the
 265         <member>XAccessibleComponent::getAccessibleAt</member> method when
 266         accessed, for instance, from StarBasic.</p>
 267
 268         @param nRow
 269             The row index for which to retrieve the cell.
 270
 271         @param nColumn
 272             The column index for which to retrieve the cell.
 273
 274         @return
 275             If both row and column index are valid then the corresponding
 276             <type>XAccessible</type> object is returned that represents the
 277             requested cell regardless of whether the cell is currently
 278             visible (on the screen).
 279
 280         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 281             if the specified column and/or row index is not valid, i.e. lies not inside
 282             the valid range of 0 up to
 283             <member>XAccessibleTable::getAccessibleColumnCount()</member> - 1.
 284     */
 285     XAccessible getAccessibleCellAt ([in] long nRow, [in] long nColumn)
 286         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 287
 288     /** Returns the caption for the table.
 289
 290         @return
 291             If the table has a caption then a reference to it is returned,
 292             else an empty reference is returned.
 293     */
 294     XAccessible getAccessibleCaption ();
 295
 296     /** Returns the summary description of the table.
 297
 298         @return
 299             Returns a reference to an implementation dependent
 300             <type>XAccessible</type> object representing the table's summary
 301             or an empty reference if the table does not support a summary.
 302     */
 303     XAccessible getAccessibleSummary ();
 304
 305     /** Returns a boolean value indicating whether the accessible at the
 306         specified row and column is selected.
 307
 308         @param nRow
 309             Row index of the cell for which to determine if the accessible
 310             object that spans that cell is selected.
 311
 312         @param nColumn
 313             Column index of the cell for which to determine if the
 314             accessible object that spans that cell is selected.
 315
 316         @return
 317             Returns <TRUE/> if the given row and column indices are valid
 318             and the specified accessible object is selected.  Otherwise
 319             <FALSE/> is returned.
 320     */
 321     boolean isAccessibleSelected ([in] long nRow, [in] long nColumn)
 322         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 323
 324     /** Returns the child index of the accessible object that spans the
 325         specified cell.
 326
 327         <p>This is the same index that would be returned by calling
 328         <member>XAccessibleContext::getAccessibleIndexInParent</member> for
 329         that accessible object.</p>
 330
 331         @param nRow
 332             Row index of the accessible object for which to return the child
 333             index.
 334
 335         @param nColumn
 336             Row index of the accessible object for which to return the child
 337             index.
 338
 339         @return
 340             Child index of the specified accessible object or -1 if one or
 341             both of the given indices is/are invalid.
 342     */
 343     long getAccessibleIndex ([in] long nRow, [in] long nColumn)
 344         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 345
 346     /** Translate the given child index into the corresponding row
 347         index.
 348
 349         @param nChildIndex
 350             Index of the child of the table for which to return the row
 351             index.
 352
 353         @return
 354             Returns the row index of the cell of the specified child or the
 355             index of the first row if the child spans multiple rows.
 356
 357         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 358             if nChildIndex addresses an invalid row.
 359     */
 360     long getAccessibleRow ([in] long nChildIndex)
 361         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 362
 363     /** Translate the given child index into the corresponding column
 364         index.
 365
 366         @param nChildIndex
 367             Index of the child of the table for which to return the column
 368             index.
 369
 370         @return
 371             Returns the column index of the cell of the specified child or
 372             the index of the first column if the child spans multiple
 373             columns.
 374
 375         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 376             if nChildIndex addresses an invalid column.
 377     */
 378     long getAccessibleColumn ([in] long nChildIndex)
 379         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 380 };
 381
 382 }; }; }; };
 383
 384 #endif
 385
 386 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */