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