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