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 base import BaseProxyMeta
  17 from accessible import BoundingBox
  18 from state import StateSet
  19
  20 from role import ROLE_UNKNOWN
  21 from component import LAYER_WIDGET
  22
  23 __all__ = [
  24            "Desktop",
  25           ]
  26
  27 #------------------------------------------------------------------------------
  28
  29 class DesktopComponent(object):
  30         """
  31         The Component interface is implemented by objects which occupy
  32         on-screen space, e.g. objects which have onscreen visual representations.
  33         The methods in Component allow clients to identify where the
  34         objects lie in the onscreen coordinate system, their relative
  35         size, stacking order, and position. It also provides a mechanism
  36         whereby keyboard focus may be transferred to specific user interface
  37         elements programmatically. This is a 2D API, coordinates of 3D
  38         objects are projected into the 2-dimensional screen view for
  39         purposes of this interface.
  40         """
  41
  42         def contains(self, *args, **kwargs):
  43                 """
  44                 @return True if the specified point lies within the Component's
  45                 bounding box, False otherwise.
  46                 """
  47                 return False
  48
  49         def deregisterFocusHandler(self, *args, **kwargs):
  50                 """
  51                 Request that an EventListener registered via registerFocusHandler
  52                 no longer be notified when this object receives keyboard focus.
  53                 """
  54                 pass
  55
  56         def getAccessibleAtPoint(self, *args, **kwargs):
  57                 """
  58                 @return the Accessible child whose bounding box contains the
  59                 specified point.
  60                 """
  61                 return None
  62
  63         def getAlpha(self, *args, **kwargs):
  64                 """
  65                 Obtain the alpha value of the component. An alpha value of 1.0
  66                 or greater indicates that the object is fully opaque, and an
  67                 alpha value of 0.0 indicates that the object is fully transparent.
  68                 Negative alpha values have no defined meaning at this time.
  69                 """
  70                 return 1.0
  71
  72         def getExtents(self, coord_type):
  73                 """
  74                 Obtain the Component's bounding box, in pixels, relative to the
  75                 specified coordinate system.
  76                 @param coord_type
  77                 @return a BoundingBox which entirely contains the object's onscreen
  78                 visual representation.
  79                 """
  80                 #TODO This needs to return the window size
  81                 return BoundingBox(*(0,0,1024,768))
  82
  83         def getLayer(self, *args, **kwargs):
  84                 """
  85                 @return the ComponentLayer in which this object resides.
  86                 """
  87                 return LAYER_WIDGET
  88
  89         def getMDIZOrder(self):
  90                 """
  91                 Obtain the relative stacking order (i.e. 'Z' order) of an object.
  92                 Larger values indicate that an object is on "top" of the stack,
  93                 therefore objects with smaller MDIZOrder may be obscured by objects
  94                 with a larger MDIZOrder, but not vice-versa.
  95                 @return an integer indicating the object's place in the stacking
  96                 order.
  97                 """
  98                 return 0
  99
 100         def getPosition(self, coord_type):
 101                 """
 102                 Obtain the position of the current component in the coordinate
 103                 system specified by coord_type.
 104                 @param : coord_type
 105                 @param : x
 106                 an out parameter which will be back-filled with the returned
 107                 x coordinate.
 108                 @param : y
 109                 an out parameter which will be back-filled with the returned
 110                 y coordinate.
 111                 """
 112                 return (0,0)
 113
 114         def getSize(self, *args, **kwargs):
 115                 """
 116                 Obtain the size, in the coordinate system specified by coord_type,
 117                 of the rectangular area which fully contains the object's visual
 118                 representation, without accounting for viewport clipping.
 119                 @param : width
 120                 the object's horizontal extents in the specified coordinate system.
 121                 @param : height
 122                 the object's vertical extents in the specified coordinate system.
 123                 """
 124                 #TODO Need to return window size
 125                 return (1024, 768)
 126
 127         def grabFocus(self, *args, **kwargs):
 128                 """
 129                 Request that the object obtain keyboard focus.
 130                 @return True if keyboard focus was successfully transferred to
 131                 the Component.
 132                 """
 133                 return False
 134
 135         def registerFocusHandler(self, *args, **kwargs):
 136                 """
 137                 Register an EventListener for notification when this object receives
 138                 keyboard focus.
 139                 """
 140                 pass
 141
 142 #------------------------------------------------------------------------------
 143
 144 class Desktop(object):
 145         """
 146         The base interface which is implemented by all accessible objects.
 147         All objects support interfaces for querying their contained
 148         'children' and position in the accessible-object hierarchy,
 149         whether or not they actually have children.
 150         """
 151
 152         __metaclass__ = BaseProxyMeta
 153
 154         def __init__(self, cache):
 155                 """
 156                 Creates a desktop object. There should be one single desktop
 157                 object for the Registry object.
 158
 159                 @param cache - The application cache.
 160                 @kwarf application - The application D-Bus name
 161
 162                 If the application name is provided the Desktop is being used for
 163                 test and will only report the application provided as its single child.
 164                 """
 165                 self._appcache = cache
 166                 self._app_name = ':'
 167                 self._acc_path = '/'
 168
 169         def __nonzero__(self):
 170                         return True
 171
 172         def __len__(self):
 173                         return self.getChildCount()
 174
 175         def __getitem__(self, index):
 176                         # IndexError thrown by getChildAtIndex
 177                         return self.getChildAtIndex(index)
 178
 179         def __eq__(self, other):
 180                 if self._app_name == other._app_name and \
 181                    self._acc_path == other._app_path:
 182                         return True
 183                 else:
 184                         return False
 185
 186         def __ne__(self, other):
 187                 return not self.__eq__(other)
 188
 189         def getApplication(self):
 190                 """
 191                 Get the containing Application for this object.
 192                 @return the Application instance to which this object belongs.
 193                 """
 194                 return None
 195
 196         def getAttributes(self):
 197                 """
 198                 Get a list of properties applied to this object as a whole, as
 199                 an AttributeSet consisting of name-value pairs. As such these
 200                 attributes may be considered weakly-typed properties or annotations,
 201                 as distinct from the strongly-typed interface instance data declared
 202                 using the IDL "attribute" keyword.
 203                 Not all objects have explicit "name-value pair" AttributeSet
 204                 properties.
 205                 Attribute names and values may have any UTF-8 string value, however
 206                 where possible, in order to facilitate consistent use and exposure
 207                 of "attribute" properties by applications and AT clients, attribute
 208                 names and values should chosen from a publicly-specified namespace
 209                 where appropriate.
 210                 Where possible, the names and values in the name-value pairs
 211                 should be chosen from well-established attribute namespaces using
 212                 standard semantics. For example, attributes of Accessible objects
 213                 corresponding to XHTML content elements should correspond to
 214                 attribute names and values specified in the w3c XHTML specification,
 215                 at http://www.w3.org/TR/xhtml2, where such values are not already
 216                 exposed via a more strongly-typed aspect of the AT-SPI API. Metadata
 217                 names and values should be chosen from the 'Dublin Core' Metadata
 218                 namespace using Dublin Core semantics: http://dublincore.org/dcregistry/
 219                 Similarly, relevant structural metadata should be exposed using
 220                 attribute names and values chosen from the CSS2 and WICD specification:
 221                 http://www.w3.org/TR/1998/REC-CSS2-19980512 WICD (http://www.w3.org/TR/2005/WD-WICD-20051121/).
 222
 223                 @return : An AttributeSet encapsulating any "attribute values"
 224                 currently defined for the object. An attribute set is a list of strings
 225                 with each string comprising an name-value pair format 'name:value'.
 226                 """
 227                 return []
 228
 229         def getChildAtIndex(self, index):
 230                 """
 231                 Get the accessible child of this object at index.
 232                 @param : index
 233                 an in parameter indicating which child is requested (zero-indexed).
 234                 @return : the 'nth' Accessible child of this object.
 235                 """
 236                 return self._appcache.create_application(self._appcache.application_list[index])
 237
 238         def getIndexInParent(self):
 239                 """
 240                 Get the index of this object in its parent's child list.
 241                 @return : a long integer indicating this object's index in the
 242                 parent's list.
 243                 """
 244                 return -1
 245
 246         def getLocalizedRoleName(self):
 247                 """
 248                 Get a string indicating the type of UI role played by this object,
 249                 translated to the current locale.
 250                 @return : a UTF-8 string indicating the type of UI role played
 251                 by this object.
 252                 """
 253                 #TODO Need to localize this somehow. Hmmmmm
 254                 return 'unknown'
 255
 256         def getRelationSet(self):
 257                 """
 258                 Get a set defining this object's relationship to other accessible
 259                 objects.
 260                 @return : a RelationSet defining this object's relationships.
 261                 """
 262                 return []
 263
 264         def getRole(self):
 265                 """
 266                 Get the Role indicating the type of UI role played by this object.
 267                 @return : a Role indicating the type of UI role played by this
 268                 object.
 269                 """
 270                 return ROLE_UNKNOWN
 271
 272         def getRoleName(self):
 273                 """
 274                 Get a string indicating the type of UI role played by this object.
 275                 @return : a UTF-8 string indicating the type of UI role played
 276                 by this object.
 277                 """
 278                 return 'unknown'
 279
 280         def getState(self):
 281                 """
 282                 Get the current state of the object as a StateSet.
 283                 @return : a StateSet encapsulating the currently true states
 284                 of the object.
 285                 """
 286                 return StateSet()
 287
 288         def isEqual(self, accessible):
 289                 """
 290                 Determine whether an Accessible refers to the same object as
 291                 another. This method should be used rather than brute-force comparison
 292                 of object references (i.e. "by-value" comparison), as two object
 293                 references may have different apparent values yet refer to the
 294                 same object.
 295                 @param : obj
 296                 an Accessible object reference to compare to
 297                 @return : a boolean indicating whether the two object references
 298                 point to the same object.
 299                 """
 300                 #TODO Fix this method
 301                 return self == accessible
 302
 303         def get_childCount(self):
 304                 return len(self._appcache.application_list)
 305         _childCountDoc = \
 306                 """
 307                 childCount: the number of children contained by this object.
 308                 """
 309         childCount = property(fget=get_childCount, doc=_childCountDoc)
 310
 311         getChildCount = get_childCount
 312
 313         def get_description(self):
 314                 return ''
 315         _descriptionDoc = \
 316                 """
 317                 a string describing the object in more detail than name.
 318                 """
 319         description = property(fget=get_description, doc=_descriptionDoc)
 320
 321         def get_name(self):
 322                 return 'main'
 323         _nameDoc = \
 324                 """
 325                 a (short) string representing the object's name.
 326                 """
 327         name = property(fget=get_name, doc=_nameDoc)
 328
 329         def get_parent(self):
 330                 return None
 331         _parentDoc = \
 332                 """
 333                 An Accessible object which is this object's containing object.
 334                 """
 335         parent = property(fget=get_parent, doc=_parentDoc)
 336
 337         @property
 338         def interfaces(self):
 339                 return [interfaces.ATSPI_ACCESSIBLE, interfaces.ATSPI_COMPONENT]
 340
 341         def queryInterface(self, interface):
 342                 """
 343                 Gets a different accessible interface for this object
 344                 or raises a NotImplemented error if the given interface
 345                 is not supported.
 346                 """
 347                 if interface == interfaces.ATSPI_ACCESSIBLE:
 348                                 return self
 349                 elif interface == interfaces.ATSPI_COMPONENT:
 350                                 return DesktopComponent()
 351                 else:
 352                                 raise NotImplementedError(
 353                                                 "%s not supported by accessible object at path %s"
 354                                                 % (interface, self.path))
 355
 356 #END----------------------------------------------------------------------------