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