1 #Copyright (C) 2008 Codethink Ltd
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.
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.
15 from interfaces import *
16 from accessible import Accessible
17 from factory import accessible_factory
25 #------------------------------------------------------------------------------
27 class Table(Accessible):
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.
43 def addColumnSelection(self, column):
45 Select the specified column, adding it to the current column
46 selection, if the table's selection model permits it.
48 @return True if the specified column was successfully selected,
51 func = self.get_dbus_method("addColumnSelection", dbus_interface=ATSPI_TABLE)
54 def addRowSelection(self, row):
56 Select the specified row, adding it to the current row selection,
57 if the table's selection model permits it.
59 @return True if the specified row was successfully selected,
62 func = self.get_dbus_method("addRowSelection", dbus_interface=ATSPI_TABLE)
65 def getAccessibleAt(self, row, column):
67 Get the table cell at the specified row and column indices.
69 the specified table row, zero-indexed.
71 the specified table column, zero-indexed.
72 @return an Accessible object representing the specified table
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)
79 def getColumnAtIndex(self, index):
81 Get the table column index occupied by the child at a particular
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.
88 func = self.get_dbus_method("getColumnAtIndex", dbus_interface=ATSPI_TABLE)
91 def getColumnDescription(self, column):
93 Get a text description of a particular table column. This differs
94 from AccessibleTable_getColumnHeader, which returns an Accessible.
96 the specified table column, zero-indexed.
97 @return a UTF-8 string describing the specified table column,
100 func = self.get_dbus_method("getColumnDescription", dbus_interface=ATSPI_TABLE)
103 def getColumnExtentAt(self, row, column):
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).
109 the specified table row, zero-indexed.
111 the specified table column, zero-indexed.
112 @return a long integer indicating the number of columns spanned
113 by the specified cell.
115 func = self.get_dbus_method("getColumnExtentAt", dbus_interface=ATSPI_TABLE)
116 return func(row, column)
118 def getColumnHeader(self, index):
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.
124 the specified table column, zero-indexed.
125 @return an Accessible representatin of the specified table column,
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)
132 def getIndexAt(self, row, column):
134 Get the 1-D child index corresponding to the specified 2-D row
137 the specified table row, zero-indexed.
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.
143 func = self.get_dbus_method("getIndexAt", dbus_interface=ATSPI_TABLE)
144 return func(row, column)
146 def getRowAtIndex(self, index):
148 Get the table row index occupied by the child at a particular
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.
155 func = self.get_dbus_method("getRowAtIndex", dbus_interface=ATSPI_TABLE)
158 def getRowColumnExtentsAtIndex(self, index):
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.
165 the index of the Table child whose row/column extents are requested.
167 back-filled with the first table row associated with the cell
168 with child index index.
170 back-filled with the first table column associated with the cell
171 with child index index.
173 back-filled with the number of table rows across which child
176 back-filled with the number of table columns across which child
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,
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,
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.
194 func = self.get_dbus_method("getRowColumnExtentsAtIndex", dbus_interface=ATSPI_TABLE)
197 def getRowDescription(self, index):
199 Get a text description of a particular table row. This differs
200 from AccessibleTable_getRowHeader, which returns an Accessible.
202 the specified table row, zero-indexed.
203 @return a UTF-8 string describing the specified table row, if
206 func = self.get_dbus_method("getRowDescription", dbus_interface=ATSPI_TABLE)
209 def getRowExtentAt(self, row, column):
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).
215 the specified table row, zero-indexed.
217 the specified table column, zero-indexed.
218 @return a long integer indicating the number of rows spanned
219 by the specified cell.
221 func = self.get_dbus_method("getRowExtentAt", dbus_interface=ATSPI_TABLE)
222 return func(row, column)
224 def getRowHeader(self, row):
226 Get the header associated with a table row, if available. This
227 differs from getRowDescription, which returns a string.
229 the specified table row, zero-indexed.
230 @return an Accessible representatin of the specified table row,
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)
237 def getSelectedColumns(self):
239 Obtain the indices of all columns which are currently selected.
240 @return a sequence of integers comprising the indices of columns
243 func = self.get_dbus_method("getSelectedColumns", dbus_interface=ATSPI_TABLE)
246 def getSelectedRows(self):
248 Obtain the indices of all rows which are currently selected.
249 @return a sequence of integers comprising the indices of rows
252 func = self.get_dbus_method("getSelectedRows", dbus_interface=ATSPI_TABLE)
255 def isColumnSelected(self, column):
257 Determine whether a table column is selected.
259 the column being queried.
260 @return True if the specified column is currently selected, False
263 func = self.get_dbus_method("isColumnSelected", dbus_interface=ATSPI_TABLE)
266 def isRowSelected(self, row):
268 Determine whether a table row is selected.
270 the row being queried.
271 @return True if the specified row is currently selected, False
274 func = self.get_dbus_method("isRowSelected", dbus_interface=ATSPI_TABLE)
277 def isSelected(self, row, column):
279 Determine whether the cell at a specific row and column is selected.
281 a row occupied by the cell whose state is being queried.
283 a column occupied by the cell whose state is being queried.
284 @return True if the specified cell is currently selected, False
287 func = self.get_dbus_method("isSelected", dbus_interface=ATSPI_TABLE)
288 return func(row, column)
290 def removeColumnSelection(self, column):
292 Remove the specified column from current column selection, if
293 the table's selection model permits it.
295 @return True if the specified column was successfully de-selected,
298 func = self.get_dbus_method("removeColumnSelection", dbus_interface=ATSPI_TABLE)
301 def removeRowSelection(self, row):
303 Remove the specified row from current row selection, if the table's
304 selection model permits it.
306 @return True if the specified row was successfully de-selected,
309 func = self.get_dbus_method("removeRowSelection", dbus_interface=ATSPI_TABLE)
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)
318 An Accessible which represents of a caption for a Table.
320 caption = property(fget=get_caption, doc=_captionDoc)
322 def get_nColumns(self):
323 return dbus.Int32(self._pgetter(self._dbus_interface, "nColumns"))
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
331 nColumns = property(fget=get_nColumns, doc=_nColumnsDoc)
334 return dbus.Int32(self._pgetter(self._dbus_interface, "nRows"))
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.
341 nRows = property(fget=get_nRows, doc=_nRowsDoc)
343 def get_nSelectedColumns(self):
344 return dbus.Int32(self._pgetter(self._dbus_interface, "nSelectedColumns"))
345 _nSelectedColumnsDoc = \
347 The number of columns currently selected. A selected column is
348 one in which all included cells are selected.
350 nSelectedColumns = property(fget=get_nSelectedColumns, doc=_nSelectedColumnsDoc)
352 def get_nSelectedRows(self):
353 return dbus.Int32(self._pgetter(self._dbus_interface, "nSelectedRows"))
354 _nSelectedRowsDoc = \
356 The number of rows currently selected. A selected row is one
357 in which all included cells are selected.
359 nSelectedRows = property(fget=get_nSelectedRows, doc=_nSelectedRowsDoc)
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)
367 An accessible object which summarizes the contents of a Table.
368 This object is frequently itself a Table instance, albeit a simplified
371 summary = property(fget=get_summary, doc=_summaryDoc)
373 # Register the accessible class with the factory.
374 accessible_factory.register_accessible_class(ATSPI_TABLE, Table)
376 #END----------------------------------------------------------------------------