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