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----------------------------------------------------------------------------