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