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

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