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