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