pyatspi/accessible.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 create_accessible, add_accessible_class
  18 from stateset import StateSet, _marshal_state_set
  19 from relation import _marshal_relation_set
  20
  21 __all__ = [
  22            "Accessible",
  23           ]
  24
  25 #------------------------------------------------------------------------------
  26
  27 class Accessible(BaseProxy):
  28     """
  29     The base interface which is implemented by all accessible objects.
  30     All objects support interfaces for querying their contained
  31     'children' and position in the accessible-object hierarchy,
  32     whether or not they actually have children.
  33     """
  34
  35     def getApplication(self):
  36         """
  37         Get the containing Application for this object.
  38         @return the Application instance to which this object belongs.
  39         """
  40         application_root = self._cache[self._app_name]._get_root()
  41         #TODO Set the desktop object as the parent of this.
  42         return create_accessible(self._cache,
  43                                  self._app_name,
  44                                  application_root,
  45                                  interfaces.ATSPI_APPLICATION,
  46                                  dbus_object=self._dbus_object)
  47
  48     def getAttributes(self):
  49         """
  50         Get a list of properties applied to this object as a whole, as
  51         an AttributeSet consisting of name-value pairs. As such these
  52         attributes may be considered weakly-typed properties or annotations,
  53         as distinct from the strongly-typed interface instance data declared
  54         using the IDL "attribute" keyword.
  55         Not all objects have explicit "name-value pair" AttributeSet
  56         properties.
  57         Attribute names and values may have any UTF-8 string value, however
  58         where possible, in order to facilitate consistent use and exposure
  59         of "attribute" properties by applications and AT clients, attribute
  60         names and values should chosen from a publicly-specified namespace
  61         where appropriate.
  62         Where possible, the names and values in the name-value pairs
  63         should be chosen from well-established attribute namespaces using
  64         standard semantics. For example, attributes of Accessible objects
  65         corresponding to XHTML content elements should correspond to
  66         attribute names and values specified in the w3c XHTML specification,
  67         at http://www.w3.org/TR/xhtml2, where such values are not already
  68         exposed via a more strongly-typed aspect of the AT-SPI API. Metadata
  69         names and values should be chosen from the 'Dublin Core' Metadata
  70         namespace using Dublin Core semantics: http://dublincore.org/dcregistry/
  71         Similarly, relevant structural metadata should be exposed using
  72         attribute names and values chosen from the CSS2 and WICD specification:
  73         http://www.w3.org/TR/1998/REC-CSS2-19980512 WICD (http://www.w3.org/TR/2005/WD-WICD-20051121/).
  74
  75         @return : An AttributeSet encapsulating any "attribute values"
  76         currently defined for the object. An attribute set is a list of strings
  77         with each string comprising an name-value pair format 'name:value'.
  78         """
  79         func = self.get_dbus_method("getAttributes")
  80         return func()
  81
  82     def getChildAtIndex(self, index):
  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         path = self.cached_data.children[index]
  90         return create_accessible(self._cache,
  91                                  self._app_name,
  92                                  path,
  93                                  interfaces.ATSPI_ACCESSIBLE,
  94                                  dbus_object=self._dbus_object)
  95
  96     def getIndexInParent(self):
  97         """
  98         Get the index of this object in its parent's child list.
  99         @return : a long integer indicating this object's index in the
 100         parent's list.
 101         """
 102         for i in range(0, self.parent.childCount):
 103                 child = self.parent.getChildAtIndex(i)
 104                 if self.isEqual(child):
 105                         return i
 106         raise AccessibleObjectNoLongerExists("Child not found within parent")
 107
 108     def getLocalizedRoleName(self):
 109         """
 110         Get a string indicating the type of UI role played by this object,
 111         translated to the current locale.
 112         @return : a UTF-8 string indicating the type of UI role played
 113         by this object.
 114         """
 115         func = self.get_dbus_method("getLocalizedRoleName")
 116         return func()
 117
 118     def getRelationSet(self):
 119         """
 120         Get a set defining this object's relationship to other accessible
 121         objects.
 122         @return : a RelationSet defining this object's relationships.
 123         """
 124         func = self.get_dbus_method("getRelationSet")
 125         relation_set = func()
 126         return _marshal_relation_set(self._cache, self._dbus_object, self._app_name, relation_set)
 127
 128     def getRole(self):
 129         """
 130         Get the Role indicating the type of UI role played by this object.
 131         @return : a Role indicating the type of UI role played by this
 132         object.
 133         """
 134         return self.cached_data.role
 135
 136     def getRoleName(self):
 137         """
 138         Get a string indicating the type of UI role played by this object.
 139         @return : a UTF-8 string indicating the type of UI role played
 140         by this object.
 141         """
 142         func = self.get_dbus_method("getRoleName")
 143         return func()
 144
 145     def getState(self):
 146         """
 147         Get the current state of the object as a StateSet.
 148         @return : a StateSet encapsulating the currently true states
 149         of the object.
 150         """
 151         func = self.get_dbus_method("getState")
 152         bitfield = func()
 153         return _marshal_state_set(bitfield)
 154
 155     def isEqual(self, accessible):
 156         """
 157         Determine whether an Accessible refers to the same object as
 158         another. This method should be used rather than brute-force comparison
 159         of object references (i.e. "by-value" comparison), as two object
 160         references may have different apparent values yet refer to the
 161         same object.
 162         @param : obj
 163         an Accessible object reference to compare to
 164         @return : a boolean indicating whether the two object references
 165         point to the same object.
 166         """
 167         return  (self._app_name == accessible._app_name) and \
 168                 (self._acc_path == accessible._acc_path)
 169
 170     def get_childCount(self):
 171         return len(self.cached_data.children)
 172     _childCountDoc = \
 173         """
 174         childCount: the number of children contained by this object.
 175         """
 176     childCount = property(fget=get_childCount, doc=_childCountDoc)
 177
 178     def get_description(self):
 179         return self.cached_data.description
 180     _descriptionDoc = \
 181         """
 182         a string describing the object in more detail than name.
 183         """
 184     description = property(fget=get_description, doc=_descriptionDoc)
 185
 186     def get_name(self):
 187         return self.cached_data.name
 188     _nameDoc = \
 189         """
 190         a (short) string representing the object's name.
 191         """
 192     name = property(fget=get_name, doc=_nameDoc)
 193
 194     def get_parent(self):
 195         if self._parent:
 196                 return self._parent
 197         else:
 198                 return create_accessible(self._cache,
 199                                          self._app_name,
 200                                          self.cached_data.parent,
 201                                          interfaces.ATSPI_ACCESSIBLE,
 202                                          dbus_object=self._dbus_object)
 203
 204     _parentDoc = \
 205         """
 206         an Accessible object which is this object's containing object.
 207         """
 208     parent = property(fget=get_parent, doc=_parentDoc)
 209
 210 # Register the Accessible class with the accessible factory.
 211 add_accessible_class(interfaces.ATSPI_ACCESSIBLE, Accessible)
 212
 213 #END----------------------------------------------------------------------------