pyatspi/desktop.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 base import BaseProxy
  16
  17 from accessible import Accessible
  18
  19 class Desktop(Accessible):
  20     """
  21     The desktop class implements the
  22     accessible interface, but uses a different
  23     method to access its chilren and to obtain cached
  24     data.
  25
  26     This is because application caches are separate
  27     and the children of the desktop are applications.
  28     The child access must get the root accessible
  29     of the application cache that is accessed.
  30
  31     The data is accessed from the desktop cache.
  32     """
  33
  34         @property
  35         def _data(self):
  36                 try:
  37                         data = self._cache._objects[self._path]
  38                 except KeyError, ReferenceError:
  39                         raise AccessibleObjectNoLongerExists, 'Cache data cannot be found for path %s' % (self._path,)
  40                 return data
  41
  42     def getApplication(self, *args, **kwargs):
  43         """
  44         Get the containing Application for this object.
  45         @return the Application instance to which this object belongs.
  46         """
  47         func = self.get_dbus_method("getApplication")
  48         return func(*args, **kwargs)
  49
  50     def getAttributes(self, *args, **kwargs):
  51         """
  52         Get a list of properties applied to this object as a whole, as
  53         an AttributeSet consisting of name-value pairs. As such these
  54         attributes may be considered weakly-typed properties or annotations,
  55         as distinct from the strongly-typed interface instance data declared
  56         using the IDL "attribute" keyword.
  57         Not all objects have explicit "name-value pair" AttributeSet
  58         properties.
  59         Attribute names and values may have any UTF-8 string value, however
  60         where possible, in order to facilitate consistent use and exposure
  61         of "attribute" properties by applications and AT clients, attribute
  62         names and values should chosen from a publicly-specified namespace
  63         where appropriate.
  64         Where possible, the names and values in the name-value pairs
  65         should be chosen from well-established attribute namespaces using
  66         standard semantics. For example, attributes of Accessible objects
  67         corresponding to XHTML content elements should correspond to
  68         attribute names and values specified in the w3c XHTML specification,
  69         at http://www.w3.org/TR/xhtml2, where such values are not already
  70         exposed via a more strongly-typed aspect of the AT-SPI API. Metadata
  71         names and values should be chosen from the 'Dublin Core' Metadata
  72         namespace using Dublin Core semantics: http://dublincore.org/dcregistry/
  73         Similarly, relevant structural metadata should be exposed using
  74         attribute names and values chosen from the CSS2 and WICD specification:
  75         http://www.w3.org/TR/1998/REC-CSS2-19980512 WICD (http://www.w3.org/TR/2005/WD-WICD-20051121/).
  76         @return : an AttributeSet encapsulating any "attribute values"
  77         currently defined for the object.
  78         """
  79         func = self.get_dbus_method("getAttributes")
  80         return func(*args, **kwargs)
  81
  82     def getChildAtIndex(self, *args, **kwargs):
  83         """
  84         Get the accessible child of this object at index.
  85         @param : index
  86         an in parameter indicating which child is requested (zero-indexed).
  87         @return : the 'nth' Accessible child of this object.
  88         """
  89         func = self.get_dbus_method("getChildAtIndex")
  90         return func(*args, **kwargs)
  91
  92     def getIndexInParent(self, *args, **kwargs):
  93         """
  94         Get the index of this object in its parent's child list.
  95         @return : a long integer indicating this object's index in the
  96         parent's list.
  97         """
  98         func = self.get_dbus_method("getIndexInParent")
  99         return func(*args, **kwargs)
 100
 101     def getLocalizedRoleName(self, *args, **kwargs):
 102         """
 103         Get a string indicating the type of UI role played by this object,
 104         translated to the current locale.
 105         @return : a UTF-8 string indicating the type of UI role played
 106         by this object.
 107         """
 108         func = self.get_dbus_method("getLocalizedRoleName")
 109         return func(*args, **kwargs)
 110
 111     def getRelationSet(self, *args, **kwargs):
 112         """
 113         Get a set defining this object's relationship to other accessible
 114         objects.
 115         @return : a RelationSet defining this object's relationships.
 116         """
 117         func = self.get_dbus_method("getRelationSet")
 118         return func(*args, **kwargs)
 119
 120     def getRole(self, *args, **kwargs):
 121         """
 122         Get the Role indicating the type of UI role played by this object.
 123         @return : a Role indicating the type of UI role played by this
 124         object.
 125         """
 126         func = self.get_dbus_method("getRole")
 127         return func(*args, **kwargs)
 128
 129     def getRoleName(self, *args, **kwargs):
 130         """
 131         Get a string indicating the type of UI role played by this object.
 132         @return : a UTF-8 string indicating the type of UI role played
 133         by this object.
 134         """
 135         func = self.get_dbus_method("getRoleName")
 136         return func(*args, **kwargs)
 137
 138     def getState(self, *args, **kwargs):
 139         """
 140         Get the current state of the object as a StateSet.
 141         @return : a StateSet encapsulating the currently true states
 142         of the object.
 143         """
 144         func = self.get_dbus_method("getState")
 145         return func(*args, **kwargs)
 146
 147     def isEqual(self, *args, **kwargs):
 148         """
 149         Determine whether an Accessible refers to the same object as
 150         another. This method should be used rather than brute-force comparison
 151         of object references (i.e. "by-value" comparison), as two object
 152         references may have different apparent values yet refer to the
 153         same object.
 154         @param : obj
 155         an Accessible object reference to compare to
 156         @return : a boolean indicating whether the two object references
 157         point to the same object.
 158         """
 159         func = self.get_dbus_method("isEqual")
 160         return func(*args, **kwargs)
 161
 162     def unimplemented(self, *args, **kwargs):
 163         """
 164         /cond future expansion
 165         """
 166         func = self.get_dbus_method("unimplemented")
 167         return func(*args, **kwargs)
 168
 169     def get_childCount(self):
 170         self._pgetter(self._dbus_interface, "childCount")
 171     def set_childCount(self, value):
 172         self._psetter(self._dbus_interface, "childCount", value)
 173     _childCountDoc = \
 174         """
 175         childCount: the number of children contained by this object.
 176         """
 177     childCount = property(fget=get_childCount, fset=set_childCount, doc=_childCountDoc)
 178
 179     def get_description(self):
 180         self._pgetter(self._dbus_interface, "description")
 181     def set_description(self, value):
 182         self._psetter(self._dbus_interface, "description", value)
 183     _descriptionDoc = \
 184         """
 185         a string describing the object in more detail than name.
 186         """
 187     description = property(fget=get_description, fset=set_description, doc=_descriptionDoc)
 188
 189     def get_name(self):
 190         self._pgetter(self._dbus_interface, "name")
 191     def set_name(self, value):
 192         self._psetter(self._dbus_interface, "name", value)
 193     _nameDoc = \
 194         """
 195         a (short) string representing the object's name.
 196         """
 197     name = property(fget=get_name, fset=set_name, doc=_nameDoc)
 198
 199     def get_parent(self):
 200         self._pgetter(self._dbus_interface, "parent")
 201     def set_parent(self, value):
 202         self._psetter(self._dbus_interface, "parent", value)
 203     _parentDoc = \
 204         """
 205         an Accessible object which is this object's containing object.
 206         """
 207     parent = property(fget=get_parent, fset=set_parent, doc=_parentDoc)