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