pyatspi/table.py

   1 #Copyright (C) 2008 Codethink Ltd
   2
   3 #This library is free software; you can redistribute it and/or
   4 #modify it under the terms of the GNU Lesser General Public
   5 #License version 2 as published by the Free Software Foundation.
   6
   7 #This program is distributed in the hope that it will be useful,
   8 #but WITHOUT ANY WARRANTY; without even the implied warranty of
   9 #MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  10 #GNU General Public License for more details.
  11 #You should have received a copy of the GNU Lesser General Public License
  12 #along with this program; if not, write to the Free Software
  13 #Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  14
  15 import interfaces
  16 from base import BaseProxy
  17 from factory import add_accessible_class
  18
  19 __all__ = [
  20            "Table",
  21           ]
  22
  23 #------------------------------------------------------------------------------
  24
  25 class Table(BaseProxy):
  26     """
  27     An interface used by containers whose contained data is arranged
  28     in a "tabular" (i.e. row-column) fashion. Tables may resemble
  29     a two-dimensional grid, as in a spreadsheet, or may feature objects
  30     which span multiple rows and/or columns, but whose bounds are
  31     aligned on a row/column matrix. Thus, the Table interface may
  32     be used to represent "spreadsheets" as well as "frames".
  33     Objects within tables are children of the Table instance, and
  34     they may be referenced either via a child index or via a row/column
  35     pair. Their role may be ROLE_TABLE_CELL, but table 'cells' may
  36     have other roles as well. These 'cells' may implement other interfaces,
  37     such as Text, Action, Image, and Component, and should do so
  38     as appropriate to their onscreen representation and/or behavior.
  39     """
  40
  41     def addColumnSelection(self, *args, **kwargs):
  42         """
  43         Select the specified column, adding it to the current column
  44         selection, if the table's selection model permits it.
  45         @param : column
  46         @return True if the specified column was successfully selected,
  47         False if not.
  48         """
  49         func = self.get_dbus_method("addColumnSelection")
  50         return func(*args, **kwargs)
  51
  52     def addRowSelection(self, *args, **kwargs):
  53         """
  54         Select the specified row, adding it to the current row selection,
  55         if the table's selection model permits it.
  56         @param : row
  57         @return True if the specified row was successfully selected,
  58         False if not.
  59         """
  60         func = self.get_dbus_method("addRowSelection")
  61         return func(*args, **kwargs)
  62
  63     def getAccessibleAt(self, *args, **kwargs):
  64         """
  65         Get the table cell at the specified row and column indices.
  66         @param : row
  67         the specified table row, zero-indexed.
  68         @param : column
  69         the specified table column, zero-indexed.
  70         @return an Accessible object representing the specified table
  71         cell.
  72         """
  73         func = self.get_dbus_method("getAccessibleAt")
  74         return func(*args, **kwargs)
  75
  76     def getColumnAtIndex(self, *args, **kwargs):
  77         """
  78         Get the table column index occupied by the child at a particular
  79         1-D child index.
  80         @param : index
  81         the specified child index, zero-indexed.
  82         @return a long integer indicating the first column spanned by
  83         the child of a table, at the specified 1-D (zero-offset) index.
  84         """
  85         func = self.get_dbus_method("getColumnAtIndex")
  86         return func(*args, **kwargs)
  87
  88     def getColumnDescription(self, *args, **kwargs):
  89         """
  90         Get a text description of a particular table column. This differs
  91         from AccessibleTable_getColumnHeader, which returns an Accessible.
  92         @param : column
  93         the specified table column, zero-indexed.
  94         @return a UTF-8 string describing the specified table column,
  95         if available.
  96         """
  97         func = self.get_dbus_method("getColumnDescription")
  98         return func(*args, **kwargs)
  99
 100     def getColumnExtentAt(self, *args, **kwargs):
 101         """
 102         Get the number of columns spanned by the table cell at the specific
 103         row and column. (some tables can have cells which span multiple
 104         rows and/or columns).
 105         @param : row
 106         the specified table row, zero-indexed.
 107         @param : column
 108         the specified table column, zero-indexed.
 109         @return a long integer indicating the number of columns spanned
 110         by the specified cell.
 111         """
 112         func = self.get_dbus_method("getColumnExtentAt")
 113         return func(*args, **kwargs)
 114
 115     def getColumnHeader(self, *args, **kwargs):
 116         """
 117         Get the header associated with a table column, if available,
 118         as an instance of Accessible. This differs from getColumnDescription,
 119         which returns a string.
 120         @param : column
 121         the specified table column, zero-indexed.
 122         @return an Accessible representatin of the specified table column,
 123         if available.
 124         """
 125         func = self.get_dbus_method("getColumnHeader")
 126         return func(*args, **kwargs)
 127
 128     def getIndexAt(self, *args, **kwargs):
 129         """
 130         Get the 1-D child index corresponding to the specified 2-D row
 131         and column indices.
 132         @param : row
 133         the specified table row, zero-indexed.
 134         @param : column
 135         the specified table column, zero-indexed.
 136         @return a long integer which serves as the index of a specified
 137         cell in the table, in a form usable by Accessible::getChildAtIndex.
 138         """
 139         func = self.get_dbus_method("getIndexAt")
 140         return func(*args, **kwargs)
 141
 142     def getRowAtIndex(self, *args, **kwargs):
 143         """
 144         Get the table row index occupied by the child at a particular
 145         1-D child index.
 146         @param : index
 147         the specified child index, zero-indexed.
 148         @return a long integer indicating the first row spanned by the
 149         child of a table, at the specified 1-D (zero-offset) index.
 150         """
 151         func = self.get_dbus_method("getRowAtIndex")
 152         return func(*args, **kwargs)
 153
 154     def getRowColumnExtentsAtIndex(self, *args, **kwargs):
 155         """
 156         Given a child index, determine the row and column indices and
 157         extents, and whether the cell is currently selected. If the child
 158         at index is not a cell (for instance, if it is a summary, caption,
 159         etc.), False is returned.
 160         @param : index
 161         the index of the Table child whose row/column extents are requested.
 162         @param : row
 163         back-filled with the first table row associated with the cell
 164         with child index index.
 165         @param : col
 166         back-filled with the first table column associated with the cell
 167         with child index index.
 168         @param : row_extents
 169         back-filled with the number of table rows across which child
 170         i extends.
 171         @param : col_extents
 172         back-filled with the number of table columns across which child
 173         i extends.
 174         @param : is_selected
 175         a boolean which is back-filled with True if the child at index
 176         i corresponds to a selected table cell, False otherwise.
 177         Example: If the Table child at index '6' extends across columns
 178         5 and 6 of row 2 of a Table instance, and is currently selected,
 179         then retval=table::getRowColumnExtentsAtIndex(6,row,col,
 180         row_extents,
 181         col_extents,
 182         is_selected);
 183          will return True, and after the call row, col, row_extents,
 184         col_extents, and is_selected will contain 2, 5, 1, 2, and True,
 185         respectively.
 186         @return True if the index is associated with a valid table cell,
 187         False if the index does not correspond to a cell. If False is
 188         returned, the values of the out parameters are undefined.
 189         """
 190         func = self.get_dbus_method("getRowColumnExtentsAtIndex")
 191         return func(*args, **kwargs)
 192
 193     def getRowDescription(self, *args, **kwargs):
 194         """
 195         Get a text description of a particular table row. This differs
 196         from AccessibleTable_getRowHeader, which returns an Accessible.
 197         @param : row
 198         the specified table row, zero-indexed.
 199         @return a UTF-8 string describing the specified table row, if
 200         available.
 201         """
 202         func = self.get_dbus_method("getRowDescription")
 203         return func(*args, **kwargs)
 204
 205     def getRowExtentAt(self, *args, **kwargs):
 206         """
 207         Get the number of rows spanned by the table cell at the specific
 208         row and column. (some tables can have cells which span multiple
 209         rows and/or columns).
 210         @param : row
 211         the specified table row, zero-indexed.
 212         @param : column
 213         the specified table column, zero-indexed.
 214         @return a long integer indicating the number of rows spanned
 215         by the specified cell.
 216         """
 217         func = self.get_dbus_method("getRowExtentAt")
 218         return func(*args, **kwargs)
 219
 220     def getRowHeader(self, *args, **kwargs):
 221         """
 222         Get the header associated with a table row, if available. This
 223         differs from getRowDescription, which returns a string.
 224         @param : row
 225         the specified table row, zero-indexed.
 226         @return an Accessible representatin of the specified table row,
 227         if available.
 228         """
 229         func = self.get_dbus_method("getRowHeader")
 230         return func(*args, **kwargs)
 231
 232     def getSelectedColumns(self, *args, **kwargs):
 233         """
 234         Obtain the indices of all columns which are currently selected.
 235         @return a sequence of integers comprising the indices of columns
 236         currently selected.
 237         """
 238         func = self.get_dbus_method("getSelectedColumns")
 239         return func(*args, **kwargs)
 240
 241     def getSelectedRows(self, *args, **kwargs):
 242         """
 243         Obtain the indices of all rows which are currently selected.
 244         @return a sequence of integers comprising the indices of rows
 245         currently selected.
 246         """
 247         func = self.get_dbus_method("getSelectedRows")
 248         return func(*args, **kwargs)
 249
 250     def isColumnSelected(self, *args, **kwargs):
 251         """
 252         Determine whether a table column is selected.
 253         @param : column
 254         the column being queried.
 255         @return True if the specified column is currently selected, False
 256         if not.
 257         """
 258         func = self.get_dbus_method("isColumnSelected")
 259         return func(*args, **kwargs)
 260
 261     def isRowSelected(self, *args, **kwargs):
 262         """
 263         Determine whether a table row is selected.
 264         @param : row
 265         the row being queried.
 266         @return True if the specified row is currently selected, False
 267         if not.
 268         """
 269         func = self.get_dbus_method("isRowSelected")
 270         return func(*args, **kwargs)
 271
 272     def isSelected(self, *args, **kwargs):
 273         """
 274         Determine whether the cell at a specific row and column is selected.
 275         @param : row
 276         a row occupied by the cell whose state is being queried.
 277         @param : column
 278         a column occupied by the cell whose state is being queried.
 279         @return True if the specified cell is currently selected, False
 280         if not.
 281         """
 282         func = self.get_dbus_method("isSelected")
 283         return func(*args, **kwargs)
 284
 285     def removeColumnSelection(self, *args, **kwargs):
 286         """
 287         Remove the specified column from current column selection, if
 288         the table's selection model permits it.
 289         @param : column
 290         @return True if the specified column was successfully de-selected,
 291         False if not.
 292         """
 293         func = self.get_dbus_method("removeColumnSelection")
 294         return func(*args, **kwargs)
 295
 296     def removeRowSelection(self, *args, **kwargs):
 297         """
 298         Remove the specified row from current row selection, if the table's
 299         selection model permits it.
 300         @param : row
 301         @return True if the specified row was successfully de-selected,
 302         False if not.
 303         """
 304         func = self.get_dbus_method("removeRowSelection")
 305         return func(*args, **kwargs)
 306
 307     def get_caption(self):
 308         self._pgetter(self._dbus_interface, "caption")
 309     def set_caption(self, value):
 310         self._psetter(self._dbus_interface, "caption", value)
 311     _captionDoc = \
 312         """
 313         An Accessible which represents of a caption for a Table.
 314         """
 315     caption = property(fget=get_caption, fset=set_caption, doc=_captionDoc)
 316
 317     def get_nColumns(self):
 318         self._pgetter(self._dbus_interface, "nColumns")
 319     def set_nColumns(self, value):
 320         self._psetter(self._dbus_interface, "nColumns", value)
 321     _nColumnsDoc = \
 322         """
 323         The total number of columns in this table (including empty columns),
 324         exclusive of columns which are programmatically hidden. Columns
 325         which are scrolled out of view or clipped by the current viewport
 326         are included.
 327         """
 328     nColumns = property(fget=get_nColumns, fset=set_nColumns, doc=_nColumnsDoc)
 329
 330     def get_nRows(self):
 331         self._pgetter(self._dbus_interface, "nRows")
 332     def set_nRows(self, value):
 333         self._psetter(self._dbus_interface, "nRows", value)
 334     _nRowsDoc = \
 335         """
 336         The total number of rows in this table (including empty rows),
 337         exclusive of any rows which are programmatically hidden. Rows
 338         which are merely scrolled out of view are included.
 339         """
 340     nRows = property(fget=get_nRows, fset=set_nRows, doc=_nRowsDoc)
 341
 342     def get_nSelectedColumns(self):
 343         self._pgetter(self._dbus_interface, "nSelectedColumns")
 344     def set_nSelectedColumns(self, value):
 345         self._psetter(self._dbus_interface, "nSelectedColumns", value)
 346     _nSelectedColumnsDoc = \
 347         """
 348         The number of columns currently selected. A selected column is
 349         one in which all included cells are selected.
 350         """
 351     nSelectedColumns = property(fget=get_nSelectedColumns, fset=set_nSelectedColumns, doc=_nSelectedColumnsDoc)
 352
 353     def get_nSelectedRows(self):
 354         self._pgetter(self._dbus_interface, "nSelectedRows")
 355     def set_nSelectedRows(self, value):
 356         self._psetter(self._dbus_interface, "nSelectedRows", value)
 357     _nSelectedRowsDoc = \
 358         """
 359         The number of rows currently selected. A selected row is one
 360         in which all included cells are selected.
 361         """
 362     nSelectedRows = property(fget=get_nSelectedRows, fset=set_nSelectedRows, doc=_nSelectedRowsDoc)
 363
 364     def get_summary(self):
 365         self._pgetter(self._dbus_interface, "summary")
 366     def set_summary(self, value):
 367         self._psetter(self._dbus_interface, "summary", value)
 368     _summaryDoc = \
 369         """
 370         An accessible object which summarizes the contents of a Table.
 371         This object is frequently itself a Table instance, albeit a simplified
 372         one.
 373         """
 374     summary = property(fget=get_summary, fset=set_summary, doc=_summaryDoc)
 375
 376 # ATTENTION - Register the Application class with the accessible factory.
 377 add_accessible_class(interfaces.ATSPI_TABLE, Table)
 378
 379 #END----------------------------------------------------------------------------