pyatspi/component.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 from interfaces import *
  16 from base import Enum
  17 from factory import accessible_factory
  18 from accessible import BoundingBox, Accessible
  19
  20 from dbus.types import Int16
  21
  22 __all__ = [
  23            "CoordType",
  24            "XY_SCREEN",
  25            "XY_WINDOW",
  26            "ComponentLayer",
  27            "Component",
  28            "LAYER_BACKGROUND",
  29            "LAYER_CANVAS",
  30            "LAYER_INVALID",
  31            "LAYER_LAST_DEFINED",
  32            "LAYER_MDI",
  33            "LAYER_OVERLAY",
  34            "LAYER_POPUP",
  35            "LAYER_WIDGET",
  36            "LAYER_WINDOW",
  37           ]
  38
  39 #------------------------------------------------------------------------------
  40
  41 class CoordType(Enum):
  42         _enum_lookup = {
  43                 0:'XY_SCREEN',
  44                 1:'XY_WINDOW',
  45         }
  46
  47 XY_SCREEN = CoordType(0)
  48 XY_WINDOW = CoordType(1)
  49
  50 #------------------------------------------------------------------------------
  51
  52 class ComponentLayer(Enum):
  53         _enum_lookup = {
  54                 0:'LAYER_INVALID',
  55                 1:'LAYER_BACKGROUND',
  56                 2:'LAYER_CANVAS',
  57                 3:'LAYER_WIDGET',
  58                 4:'LAYER_MDI',
  59                 5:'LAYER_POPUP',
  60                 6:'LAYER_OVERLAY',
  61                 7:'LAYER_WINDOW',
  62                 8:'LAYER_LAST_DEFINED',
  63         }
  64
  65 LAYER_BACKGROUND = ComponentLayer(1)
  66 LAYER_CANVAS = ComponentLayer(2)
  67 LAYER_INVALID = ComponentLayer(0)
  68 LAYER_LAST_DEFINED = ComponentLayer(8)
  69 LAYER_MDI = ComponentLayer(4)
  70 LAYER_OVERLAY = ComponentLayer(6)
  71 LAYER_POPUP = ComponentLayer(5)
  72 LAYER_WIDGET = ComponentLayer(3)
  73 LAYER_WINDOW = ComponentLayer(7)
  74
  75 #------------------------------------------------------------------------------
  76
  77 class Component(Accessible):
  78         """
  79         The Component interface is implemented by objects which occupy
  80         on-screen space, e.g. objects which have onscreen visual representations.
  81         The methods in Component allow clients to identify where the
  82         objects lie in the onscreen coordinate system, their relative
  83         size, stacking order, and position. It also provides a mechanism
  84         whereby keyboard focus may be transferred to specific user interface
  85         elements programmatically. This is a 2D API, coordinates of 3D
  86         objects are projected into the 2-dimensional screen view for
  87         purposes of this interface.
  88         """
  89
  90         def contains(self, *args, **kwargs):
  91                 """
  92                 @return True if the specified point lies within the Component's
  93                 bounding box, False otherwise.
  94                 """
  95                 func = self.get_dbus_method("contains", dbus_interface=ATSPI_COMPONENT)
  96                 return func(*args, **kwargs)
  97
  98         def deregisterFocusHandler(self, *args, **kwargs):
  99                 """
 100                 Request that an EventListener registered via registerFocusHandler
 101                 no longer be notified when this object receives keyboard focus.
 102                 """
 103                 func = self.get_dbus_method("deregisterFocusHandler", dbus_interface=ATSPI_COMPONENT)
 104                 return func(*args, **kwargs)
 105
 106         def getAccessibleAtPoint(self, *args, **kwargs):
 107                 """
 108                 @return the Accessible child whose bounding box contains the
 109                 specified point.
 110                 """
 111                 #TODO this needs a real implementation
 112                 func = self.get_dbus_method("getAccessibleAtPoint", dbus_interface=ATSPI_COMPONENT)
 113                 return func(*args, **kwargs)
 114
 115         def getAlpha(self, *args, **kwargs):
 116                 """
 117                 Obtain the alpha value of the component. An alpha value of 1.0
 118                 or greater indicates that the object is fully opaque, and an
 119                 alpha value of 0.0 indicates that the object is fully transparent.
 120                 Negative alpha values have no defined meaning at this time.
 121                 """
 122                 func = self.get_dbus_method("getAlpha", dbus_interface=ATSPI_COMPONENT)
 123                 return func(*args, **kwargs)
 124
 125         def getExtents(self, coord_type):
 126                 """
 127                 Obtain the Component's bounding box, in pixels, relative to the
 128                 specified coordinate system.
 129                 @param coord_type
 130                 @return a BoundingBox which entirely contains the object's onscreen
 131                 visual representation.
 132                 """
 133                 func = self.get_dbus_method("getExtents", dbus_interface=ATSPI_COMPONENT)
 134                 extents = func(Int16(coord_type))
 135                 return BoundingBox(*extents)
 136
 137         def getLayer(self, *args, **kwargs):
 138                 """
 139                 @return the ComponentLayer in which this object resides.
 140                 """
 141                 func = self.get_dbus_method("getLayer", dbus_interface=ATSPI_COMPONENT)
 142                 return ComponentLayer(func(*args, **kwargs))
 143
 144         def getMDIZOrder(self):
 145                 """
 146                 Obtain the relative stacking order (i.e. 'Z' order) of an object.
 147                 Larger values indicate that an object is on "top" of the stack,
 148                 therefore objects with smaller MDIZOrder may be obscured by objects
 149                 with a larger MDIZOrder, but not vice-versa.
 150                 @return an integer indicating the object's place in the stacking
 151                 order.
 152                 """
 153                 func = self.get_dbus_method("getMDIZOrder", dbus_interface=ATSPI_COMPONENT)
 154                 return func()
 155
 156         def getPosition(self, coord_type):
 157                 """
 158                 Obtain the position of the current component in the coordinate
 159                 system specified by coord_type.
 160                 @param : coord_type
 161                 @param : x
 162                 an out parameter which will be back-filled with the returned
 163                 x coordinate.
 164                 @param : y
 165                 an out parameter which will be back-filled with the returned
 166                 y coordinate.
 167                 """
 168                 func = self.get_dbus_method("getPosition", dbus_interface=ATSPI_COMPONENT)
 169                 return func(Int16(coord_type))
 170
 171         def getSize(self, *args, **kwargs):
 172                 """
 173                 Obtain the size, in the coordinate system specified by coord_type,
 174                 of the rectangular area which fully contains the object's visual
 175                 representation, without accounting for viewport clipping.
 176                 @param : width
 177                 the object's horizontal extents in the specified coordinate system.
 178                 @param : height
 179                 the object's vertical extents in the specified coordinate system.
 180                 """
 181                 func = self.get_dbus_method("getSize", dbus_interface=ATSPI_COMPONENT)
 182                 return func(*args, **kwargs)
 183
 184         def grabFocus(self, *args, **kwargs):
 185                 """
 186                 Request that the object obtain keyboard focus.
 187                 @return True if keyboard focus was successfully transferred to
 188                 the Component.
 189                 """
 190                 func = self.get_dbus_method("grabFocus", dbus_interface=ATSPI_COMPONENT)
 191                 return func(*args, **kwargs)
 192
 193         def registerFocusHandler(self, *args, **kwargs):
 194                 """
 195                 Register an EventListener for notification when this object receives
 196                 keyboard focus.
 197                 """
 198                 func = self.get_dbus_method("registerFocusHandler", dbus_interface=ATSPI_COMPONENT)
 199                 return func(*args, **kwargs)
 200
 201 # Register the accessible class with the factory.
 202 accessible_factory.register_accessible_class(ATSPI_COMPONENT, Component)
 203
 204 #END----------------------------------------------------------------------------