1 #Copyright (C) 2008 Codethink Ltd
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.
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.
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
25 #------------------------------------------------------------------------------
27 class Accessible(BaseProxy):
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.
35 def getApplication(self):
37 Get the containing Application for this object.
38 @return the Application instance to which this object belongs.
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,
45 interfaces.ATSPI_APPLICATION,
46 connection=self._cache._connection)
48 def getAttributes(self):
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
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
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/).
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'.
79 func = self.get_dbus_method("getAttributes")
82 def getChildAtIndex(self, index):
84 Get the accessible child of this object at index.
86 an in parameter indicating which child is requested (zero-indexed).
87 @return : the 'nth' Accessible child of this object.
89 path = self.cached_data.children[index]
90 return create_accessible(self._cache,
93 interfaces.ATSPI_ACCESSIBLE,
94 connection=self._cache._connection)
96 def getIndexInParent(self):
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
102 for i in range(0, self.parent.childCount):
103 child = self.parent.getChildAtIndex(i)
104 if self.isEqual(child):
106 raise AccessibleObjectNoLongerExists("Child not found within parent")
108 def getLocalizedRoleName(self):
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
115 func = self.get_dbus_method("getLocalizedRoleName")
118 def getRelationSet(self):
120 Get a set defining this object's relationship to other accessible
122 @return : a RelationSet defining this object's relationships.
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)
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
134 return self.cached_data.role
136 def getRoleName(self):
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
142 func = self.get_dbus_method("getRoleName")
147 Get the current state of the object as a StateSet.
148 @return : a StateSet encapsulating the currently true states
151 func = self.get_dbus_method("getState")
153 return _marshal_state_set(bitfield)
155 def isEqual(self, accessible):
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
163 an Accessible object reference to compare to
164 @return : a boolean indicating whether the two object references
165 point to the same object.
167 return (self._app_name == accessible._app_name) and \
168 (self._acc_path == accessible._acc_path)
170 def get_childCount(self):
171 return len(self.cached_data.children)
174 childCount: the number of children contained by this object.
176 childCount = property(fget=get_childCount, doc=_childCountDoc)
178 def get_description(self):
179 return self.cached_data.description
182 a string describing the object in more detail than name.
184 description = property(fget=get_description, doc=_descriptionDoc)
187 return self.cached_data.name
190 a (short) string representing the object's name.
192 name = property(fget=get_name, doc=_nameDoc)
194 def get_parent(self):
198 return create_accessible(self._cache,
200 self.cached_data.parent,
201 interfaces.ATSPI_ACCESSIBLE,
202 connection=self._cache._connection)
206 an Accessible object which is this object's containing object.
208 parent = property(fget=get_parent, doc=_parentDoc)
210 # Register the Accessible class with the accessible factory.
211 add_accessible_class(interfaces.ATSPI_ACCESSIBLE, Accessible)
213 #END----------------------------------------------------------------------------