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 import interfaces
  16 from base import BaseProxy, Enum
  17 from factory import create_accessible, add_accessible_class
  18 from accessible import BoundingBox
  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(BaseProxy):
  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")
  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")
 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                 func = self.get_dbus_method("getAccessibleAtPoint")
 112                 return func(*args, **kwargs)
 113
 114         def getAlpha(self, *args, **kwargs):
 115                 """
 116                 Obtain the alpha value of the component. An alpha value of 1.0
 117                 or greater indicates that the object is fully opaque, and an
 118                 alpha value of 0.0 indicates that the object is fully transparent.
 119                 Negative alpha values have no defined meaning at this time.
 120                 """
 121                 func = self.get_dbus_method("getAlpha")
 122                 return func(*args, **kwargs)
 123
 124         def getExtents(self, coord_type):
 125                 """
 126                 Obtain the Component's bounding box, in pixels, relative to the
 127                 specified coordinate system.
 128                 @param coord_type
 129                 @return a BoundingBox which entirely contains the object's onscreen
 130                 visual representation.
 131                 """
 132                 func = self.get_dbus_method("getExtents")
 133                 extents = func(Int16(coord_type))
 134                 return BoundingBox(*extents)
 135
 136         def getLayer(self, *args, **kwargs):
 137                 """
 138                 @return the ComponentLayer in which this object resides.
 139                 """
 140                 func = self.get_dbus_method("getLayer")
 141                 return ComponentLayer(func(*args, **kwargs))
 142
 143         def getMDIZOrder(self):
 144                 """
 145                 Obtain the relative stacking order (i.e. 'Z' order) of an object.
 146                 Larger values indicate that an object is on "top" of the stack,
 147                 therefore objects with smaller MDIZOrder may be obscured by objects
 148                 with a larger MDIZOrder, but not vice-versa.
 149                 @return an integer indicating the object's place in the stacking
 150                 order.
 151                 """
 152                 func = self.get_dbus_method("getMDIZOrder")
 153                 return func()
 154
 155         def getPosition(self, coord_type):
 156                 """
 157                 Obtain the position of the current component in the coordinate
 158                 system specified by coord_type.
 159                 @param : coord_type
 160                 @param : x
 161                 an out parameter which will be back-filled with the returned
 162                 x coordinate.
 163                 @param : y
 164                 an out parameter which will be back-filled with the returned
 165                 y coordinate.
 166                 """
 167                 func = self.get_dbus_method("getPosition")
 168                 return func(Int16(coord_type))
 169
 170         def getSize(self, *args, **kwargs):
 171                 """
 172                 Obtain the size, in the coordinate system specified by coord_type,
 173                 of the rectangular area which fully contains the object's visual
 174                 representation, without accounting for viewport clipping.
 175                 @param : width
 176                 the object's horizontal extents in the specified coordinate system.
 177                 @param : height
 178                 the object's vertical extents in the specified coordinate system.
 179                 """
 180                 func = self.get_dbus_method("getSize")
 181                 return func(*args, **kwargs)
 182
 183         def grabFocus(self, *args, **kwargs):
 184                 """
 185                 Request that the object obtain keyboard focus.
 186                 @return True if keyboard focus was successfully transferred to
 187                 the Component.
 188                 """
 189                 func = self.get_dbus_method("grabFocus")
 190                 return func(*args, **kwargs)
 191
 192         def registerFocusHandler(self, *args, **kwargs):
 193                 """
 194                 Register an EventListener for notification when this object receives
 195                 keyboard focus.
 196                 """
 197                 func = self.get_dbus_method("registerFocusHandler")
 198                 return func(*args, **kwargs)
 199
 200 # Register the Accessible class with the accessible factory.
 201 add_accessible_class(interfaces.ATSPI_COMPONENT, Component)
 202
 203 #END----------------------------------------------------------------------------