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 __str__(self):
 170                     try:
 171                               return '[%s | %s]' % (self.getRoleName(), self.name)
 172                     except Exception:
 173                               return '[DEAD]'
 174
 175         def __nonzero__(self):
 176                         return True
 177
 178         def __len__(self):
 179                         return self.getChildCount()
 180
 181         def __getitem__(self, index):
 182                         # IndexError thrown by getChildAtIndex
 183                         return self.getChildAtIndex(index)
 184
 185         def __eq__(self, other):
 186                 if other is None:
 187                         return False
 188
 189                 if self._app_name == other._app_name and \
 190                    self._acc_path == other._acc_path:
 191                         return True
 192                 else:
 193                         return False
 194
 195         def __ne__(self, other):
 196                 return not self.__eq__(other)
 197
 198         def getApplication(self):
 199                 """
 200                 Get the containing Application for this object.
 201                 @return the Application instance to which this object belongs.
 202                 """
 203                 return None
 204
 205         def getAttributes(self):
 206                 """
 207                 Get a list of properties applied to this object as a whole, as
 208                 an AttributeSet consisting of name-value pairs. As such these
 209                 attributes may be considered weakly-typed properties or annotations,
 210                 as distinct from the strongly-typed interface instance data declared
 211                 using the IDL "attribute" keyword.
 212                 Not all objects have explicit "name-value pair" AttributeSet
 213                 properties.
 214                 Attribute names and values may have any UTF-8 string value, however
 215                 where possible, in order to facilitate consistent use and exposure
 216                 of "attribute" properties by applications and AT clients, attribute
 217                 names and values should chosen from a publicly-specified namespace
 218                 where appropriate.
 219                 Where possible, the names and values in the name-value pairs
 220                 should be chosen from well-established attribute namespaces using
 221                 standard semantics. For example, attributes of Accessible objects
 222                 corresponding to XHTML content elements should correspond to
 223                 attribute names and values specified in the w3c XHTML specification,
 224                 at http://www.w3.org/TR/xhtml2, where such values are not already
 225                 exposed via a more strongly-typed aspect of the AT-SPI API. Metadata
 226                 names and values should be chosen from the 'Dublin Core' Metadata
 227                 namespace using Dublin Core semantics: http://dublincore.org/dcregistry/
 228                 Similarly, relevant structural metadata should be exposed using
 229                 attribute names and values chosen from the CSS2 and WICD specification:
 230                 http://www.w3.org/TR/1998/REC-CSS2-19980512 WICD (http://www.w3.org/TR/2005/WD-WICD-20051121/).
 231
 232                 @return : An AttributeSet encapsulating any "attribute values"
 233                 currently defined for the object. An attribute set is a list of strings
 234                 with each string comprising an name-value pair format 'name:value'.
 235                 """
 236                 return []
 237
 238         def getChildAtIndex(self, index):
 239                 """
 240                 Get the accessible child of this object at index.
 241                 @param : index
 242                 an in parameter indicating which child is requested (zero-indexed).
 243                 @return : the 'nth' Accessible child of this object.
 244                 """
 245                 return self._appcache.create_application(self._appcache.application_list[index])
 246
 247         def getIndexInParent(self):
 248                 """
 249                 Get the index of this object in its parent's child list.
 250                 @return : a long integer indicating this object's index in the
 251                 parent's list.
 252                 """
 253                 return -1
 254
 255         def getLocalizedRoleName(self):
 256                 """
 257                 Get a string indicating the type of UI role played by this object,
 258                 translated to the current locale.
 259                 @return : a UTF-8 string indicating the type of UI role played
 260                 by this object.
 261                 """
 262                 #TODO Need to localize this somehow. Hmmmmm
 263                 return 'unknown'
 264
 265         def getRelationSet(self):
 266                 """
 267                 Get a set defining this object's relationship to other accessible
 268                 objects.
 269                 @return : a RelationSet defining this object's relationships.
 270                 """
 271                 return []
 272
 273         def getRole(self):
 274                 """
 275                 Get the Role indicating the type of UI role played by this object.
 276                 @return : a Role indicating the type of UI role played by this
 277                 object.
 278                 """
 279                 return ROLE_UNKNOWN
 280
 281         def getRoleName(self):
 282                 """
 283                 Get a string indicating the type of UI role played by this object.
 284                 @return : a UTF-8 string indicating the type of UI role played
 285                 by this object.
 286                 """
 287                 return 'unknown'
 288
 289         def getState(self):
 290                 """
 291                 Get the current state of the object as a StateSet.
 292                 @return : a StateSet encapsulating the currently true states
 293                 of the object.
 294                 """
 295                 return StateSet()
 296
 297         def isEqual(self, accessible):
 298                 """
 299                 Determine whether an Accessible refers to the same object as
 300                 another. This method should be used rather than brute-force comparison
 301                 of object references (i.e. "by-value" comparison), as two object
 302                 references may have different apparent values yet refer to the
 303                 same object.
 304                 @param : obj
 305                 an Accessible object reference to compare to
 306                 @return : a boolean indicating whether the two object references
 307                 point to the same object.
 308                 """
 309                 #TODO Fix this method
 310                 return self == accessible
 311
 312         def get_childCount(self):
 313                 return len(self._appcache.application_list)
 314         _childCountDoc = \
 315                 """
 316                 childCount: the number of children contained by this object.
 317                 """
 318         childCount = property(fget=get_childCount, doc=_childCountDoc)
 319
 320         getChildCount = get_childCount
 321
 322         def get_description(self):
 323                 return ''
 324         _descriptionDoc = \
 325                 """
 326                 a string describing the object in more detail than name.
 327                 """
 328         description = property(fget=get_description, doc=_descriptionDoc)
 329
 330         def get_name(self):
 331                 return 'main'
 332         _nameDoc = \
 333                 """
 334                 a (short) string representing the object's name.
 335                 """
 336         name = property(fget=get_name, doc=_nameDoc)
 337
 338         def get_parent(self):
 339                 return None
 340         _parentDoc = \
 341                 """
 342                 An Accessible object which is this object's containing object.
 343                 """
 344         parent = property(fget=get_parent, doc=_parentDoc)
 345
 346         @property
 347         def interfaces(self):
 348                 return [interfaces.ATSPI_ACCESSIBLE, interfaces.ATSPI_COMPONENT]
 349
 350         def queryInterface(self, interface):
 351                 """
 352                 Gets a different accessible interface for this object
 353                 or raises a NotImplemented error if the given interface
 354                 is not supported.
 355                 """
 356                 if interface == interfaces.ATSPI_ACCESSIBLE:
 357                                 return self
 358                 elif interface == interfaces.ATSPI_COMPONENT:
 359                                 return DesktopComponent()
 360                 else:
 361                                 raise NotImplementedError(
 362                                                 "%s not supported by accessible object at path %s"
 363                                                 % (interface, self._acc_path))
 364
 365 #END----------------------------------------------------------------------------