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

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