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.
16 from base import BaseProxy
17 from factory import add_accessible_class
23 #------------------------------------------------------------------------------
25 class Table(BaseProxy):
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.
41 def addColumnSelection(self, *args, **kwargs):
43 Select the specified column, adding it to the current column
44 selection, if the table's selection model permits it.
46 @return True if the specified column was successfully selected,
49 func = self.get_dbus_method("addColumnSelection")
50 return func(*args, **kwargs)
52 def addRowSelection(self, *args, **kwargs):
54 Select the specified row, adding it to the current row selection,
55 if the table's selection model permits it.
57 @return True if the specified row was successfully selected,
60 func = self.get_dbus_method("addRowSelection")
61 return func(*args, **kwargs)
63 def getAccessibleAt(self, *args, **kwargs):
65 Get the table cell at the specified row and column indices.
67 the specified table row, zero-indexed.
69 the specified table column, zero-indexed.
70 @return an Accessible object representing the specified table
73 func = self.get_dbus_method("getAccessibleAt")
74 return func(*args, **kwargs)
76 def getColumnAtIndex(self, *args, **kwargs):
78 Get the table column index occupied by the child at a particular
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.
85 func = self.get_dbus_method("getColumnAtIndex")
86 return func(*args, **kwargs)
88 def getColumnDescription(self, *args, **kwargs):
90 Get a text description of a particular table column. This differs
91 from AccessibleTable_getColumnHeader, which returns an Accessible.
93 the specified table column, zero-indexed.
94 @return a UTF-8 string describing the specified table column,
97 func = self.get_dbus_method("getColumnDescription")
98 return func(*args, **kwargs)
100 def getColumnExtentAt(self, *args, **kwargs):
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).
106 the specified table row, zero-indexed.
108 the specified table column, zero-indexed.
109 @return a long integer indicating the number of columns spanned
110 by the specified cell.
112 func = self.get_dbus_method("getColumnExtentAt")
113 return func(*args, **kwargs)
115 def getColumnHeader(self, *args, **kwargs):
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.
121 the specified table column, zero-indexed.
122 @return an Accessible representatin of the specified table column,
125 func = self.get_dbus_method("getColumnHeader")
126 return func(*args, **kwargs)
128 def getIndexAt(self, *args, **kwargs):
130 Get the 1-D child index corresponding to the specified 2-D row
133 the specified table row, zero-indexed.
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.
139 func = self.get_dbus_method("getIndexAt")
140 return func(*args, **kwargs)
142 def getRowAtIndex(self, *args, **kwargs):
144 Get the table row index occupied by the child at a particular
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.
151 func = self.get_dbus_method("getRowAtIndex")
152 return func(*args, **kwargs)
154 def getRowColumnExtentsAtIndex(self, *args, **kwargs):
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.
161 the index of the Table child whose row/column extents are requested.
163 back-filled with the first table row associated with the cell
164 with child index index.
166 back-filled with the first table column associated with the cell
167 with child index index.
169 back-filled with the number of table rows across which child
172 back-filled with the number of table columns across which child
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,
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,
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.
190 func = self.get_dbus_method("getRowColumnExtentsAtIndex")
191 return func(*args, **kwargs)
193 def getRowDescription(self, *args, **kwargs):
195 Get a text description of a particular table row. This differs
196 from AccessibleTable_getRowHeader, which returns an Accessible.
198 the specified table row, zero-indexed.
199 @return a UTF-8 string describing the specified table row, if
202 func = self.get_dbus_method("getRowDescription")
203 return func(*args, **kwargs)
205 def getRowExtentAt(self, *args, **kwargs):
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).
211 the specified table row, zero-indexed.
213 the specified table column, zero-indexed.
214 @return a long integer indicating the number of rows spanned
215 by the specified cell.
217 func = self.get_dbus_method("getRowExtentAt")
218 return func(*args, **kwargs)
220 def getRowHeader(self, *args, **kwargs):
222 Get the header associated with a table row, if available. This
223 differs from getRowDescription, which returns a string.
225 the specified table row, zero-indexed.
226 @return an Accessible representatin of the specified table row,
229 func = self.get_dbus_method("getRowHeader")
230 return func(*args, **kwargs)
232 def getSelectedColumns(self, *args, **kwargs):
234 Obtain the indices of all columns which are currently selected.
235 @return a sequence of integers comprising the indices of columns
238 func = self.get_dbus_method("getSelectedColumns")
239 return func(*args, **kwargs)
241 def getSelectedRows(self, *args, **kwargs):
243 Obtain the indices of all rows which are currently selected.
244 @return a sequence of integers comprising the indices of rows
247 func = self.get_dbus_method("getSelectedRows")
248 return func(*args, **kwargs)
250 def isColumnSelected(self, *args, **kwargs):
252 Determine whether a table column is selected.
254 the column being queried.
255 @return True if the specified column is currently selected, False
258 func = self.get_dbus_method("isColumnSelected")
259 return func(*args, **kwargs)
261 def isRowSelected(self, *args, **kwargs):
263 Determine whether a table row is selected.
265 the row being queried.
266 @return True if the specified row is currently selected, False
269 func = self.get_dbus_method("isRowSelected")
270 return func(*args, **kwargs)
272 def isSelected(self, *args, **kwargs):
274 Determine whether the cell at a specific row and column is selected.
276 a row occupied by the cell whose state is being queried.
278 a column occupied by the cell whose state is being queried.
279 @return True if the specified cell is currently selected, False
282 func = self.get_dbus_method("isSelected")
283 return func(*args, **kwargs)
285 def removeColumnSelection(self, *args, **kwargs):
287 Remove the specified column from current column selection, if
288 the table's selection model permits it.
290 @return True if the specified column was successfully de-selected,
293 func = self.get_dbus_method("removeColumnSelection")
294 return func(*args, **kwargs)
296 def removeRowSelection(self, *args, **kwargs):
298 Remove the specified row from current row selection, if the table's
299 selection model permits it.
301 @return True if the specified row was successfully de-selected,
304 func = self.get_dbus_method("removeRowSelection")
305 return func(*args, **kwargs)
307 def get_caption(self):
308 return self._pgetter(self._dbus_interface, "caption")
309 def set_caption(self, value):
310 self._psetter(self._dbus_interface, "caption", value)
313 An Accessible which represents of a caption for a Table.
315 caption = property(fget=get_caption, fset=set_caption, doc=_captionDoc)
317 def get_nColumns(self):
318 return self._pgetter(self._dbus_interface, "nColumns")
319 def set_nColumns(self, value):
320 self._psetter(self._dbus_interface, "nColumns", value)
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
328 nColumns = property(fget=get_nColumns, fset=set_nColumns, doc=_nColumnsDoc)
331 return self._pgetter(self._dbus_interface, "nRows")
332 def set_nRows(self, value):
333 self._psetter(self._dbus_interface, "nRows", value)
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.
340 nRows = property(fget=get_nRows, fset=set_nRows, doc=_nRowsDoc)
342 def get_nSelectedColumns(self):
343 return self._pgetter(self._dbus_interface, "nSelectedColumns")
344 def set_nSelectedColumns(self, value):
345 self._psetter(self._dbus_interface, "nSelectedColumns", value)
346 _nSelectedColumnsDoc = \
348 The number of columns currently selected. A selected column is
349 one in which all included cells are selected.
351 nSelectedColumns = property(fget=get_nSelectedColumns, fset=set_nSelectedColumns, doc=_nSelectedColumnsDoc)
353 def get_nSelectedRows(self):
354 return self._pgetter(self._dbus_interface, "nSelectedRows")
355 def set_nSelectedRows(self, value):
356 self._psetter(self._dbus_interface, "nSelectedRows", value)
357 _nSelectedRowsDoc = \
359 The number of rows currently selected. A selected row is one
360 in which all included cells are selected.
362 nSelectedRows = property(fget=get_nSelectedRows, fset=set_nSelectedRows, doc=_nSelectedRowsDoc)
364 def get_summary(self):
365 return self._pgetter(self._dbus_interface, "summary")
366 def set_summary(self, value):
367 self._psetter(self._dbus_interface, "summary", value)
370 An accessible object which summarizes the contents of a Table.
371 This object is frequently itself a Table instance, albeit a simplified
374 summary = property(fget=get_summary, fset=set_summary, doc=_summaryDoc)
376 # ATTENTION - Register the Application class with the accessible factory.
377 add_accessible_class(interfaces.ATSPI_TABLE, Table)
379 #END----------------------------------------------------------------------------