1#Copyright (C) 2008 Codethink Ltd
2#Copyright (c) 2012 SUSE LINUX Products GmbH, Nuernberg, Germany.
3
4#This library is free software; you can redistribute it and/or
5#modify it under the terms of the GNU Lesser General Public
6#License version 2 as published by the Free Software Foundation.
7
8#This program is distributed in the hope that it will be useful,
9#but WITHOUT ANY WARRANTY; without even the implied warranty of
10#MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11#GNU General Public License for more details.
12#You should have received a copy of the GNU Lesser General Public License
13#along with this program; if not, write to the Free Software
14#Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15
16from gi.repository import Atspi
17from pyatspi.atspienum import *
18from pyatspi.utils import *
19from pyatspi.interface import *
20
21__all__ = [
22           "CoordType",
23           "XY_SCREEN",
24           "XY_WINDOW",
25           "XY_PARENT",
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           "ScrollType",
38           "SCROLL_TOP_LEFT",
39           "SCROLL_BOTTOM_RIGHT",
40           "SCROLL_TOP_EDGE",
41           "SCROLL_BOTTOM_EDGE",
42           "SCROLL_LEFT_EDGE",
43           "SCROLL_RIGHT_EDGE",
44           "SCROLL_ANYWHERE",
45          ]
46
47#------------------------------------------------------------------------------
48
49class CoordType(AtspiEnum):
50        _enum_lookup = {
51                0:'XY_SCREEN',
52                1:'XY_WINDOW',
53                2:'XY_PARENT',
54        }
55
56XY_SCREEN = CoordType(0)
57XY_WINDOW = CoordType(1)
58XY_PARENT = CoordType(2)
59
60#------------------------------------------------------------------------------
61
62class ComponentLayer(AtspiEnum):
63        _enum_lookup = {
64                0:'LAYER_INVALID',
65                1:'LAYER_BACKGROUND',
66                2:'LAYER_CANVAS',
67                3:'LAYER_WIDGET',
68                4:'LAYER_MDI',
69                5:'LAYER_POPUP',
70                6:'LAYER_OVERLAY',
71                7:'LAYER_WINDOW',
72                8:'LAYER_LAST_DEFINED',
73        }
74
75LAYER_BACKGROUND = ComponentLayer(1)
76LAYER_CANVAS = ComponentLayer(2)
77LAYER_INVALID = ComponentLayer(0)
78LAYER_LAST_DEFINED = ComponentLayer(8)
79LAYER_MDI = ComponentLayer(4)
80LAYER_OVERLAY = ComponentLayer(6)
81LAYER_POPUP = ComponentLayer(5)
82LAYER_WIDGET = ComponentLayer(3)
83LAYER_WINDOW = ComponentLayer(7)
84
85#------------------------------------------------------------------------------
86
87class ScrollType(AtspiEnum):
88        _enum_lookup = {
89                0:'SCROLL_TOP_LEFT',
90                1:'SCROLL_BOTTOM_RIGHT',
91                2:'SCROLL_TOP_EDGE',
92                3:'SCROLL_BOTTOM_EDGE',
93                4:'SCROLL_LEFT_EDGE',
94                5:'SCROLL_RIGHT_EDGE',
95                6:'SCROLL_ANYWHERE',
96        }
97
98SCROLL_ANYWHERE = ScrollType(6)
99SCROLL_BOTTOM_EDGE = ScrollType(3)
100SCROLL_BOTTOM_RIGHT = ScrollType(1)
101SCROLL_LEFT_EDGE = ScrollType(4)
102SCROLL_RIGHT_EDGE = ScrollType(5)
103SCROLL_TOP_EDGE = ScrollType(2)
104SCROLL_TOP_LEFT = ScrollType(0)
105
106#------------------------------------------------------------------------------
107
108class Component(interface):
109        """
110        The Component interface is implemented by objects which occupy
111        on-screen space, e.g. objects which have onscreen visual representations.
112        The methods in Component allow clients to identify where the
113        objects lie in the onscreen coordinate system, their relative
114        size, stacking order, and position. It also provides a mechanism
115        whereby keyboard focus may be transferred to specific user interface
116        elements programmatically. This is a 2D API, coordinates of 3D
117        objects are projected into the 2-dimensional screen view for
118        purposes of this interface.
119        """
120
121        def contains(self, x, y, coord_type):
122                """
123                @return True if the specified point lies within the Component's
124                bounding box, False otherwise.
125                """
126                return Atspi.Component.contains(self.obj, x, y, coord_type)
127
128        def getAccessibleAtPoint(self, x, y, coord_type):
129                """
130                @return the Accessible child whose bounding box contains the
131                specified point.
132                """
133                return Atspi.Component.get_accessible_at_point(self.obj, x, y, coord_type)
134
135        def getAlpha(self):
136                """
137                Obtain the alpha value of the component. An alpha value of 1.0
138                or greater indicates that the object is fully opaque, and an
139                alpha value of 0.0 indicates that the object is fully transparent.
140                Negative alpha values have no defined meaning at this time.
141                """
142                return Atspi.Component.get_alpha(self.obj)
143
144        def getExtents(self, coord_type):
145                """
146                Obtain the Component's bounding box, in pixels, relative to the
147                specified coordinate system.
148                The returned values are meaningful only if the Component has
149                both STATE_VISIBLE and STATE_SHOWING.
150                @param coord_type
151                @return a BoundingBox which entirely contains the object's onscreen
152                visual representation.
153                """
154                return getBoundingBox(Atspi.Component.get_extents(self.obj, coord_type))
155
156        def getLayer(self):
157                """
158                @return the ComponentLayer in which this object resides.
159                """
160                return Atspi.Component.get_layer(self.obj)
161
162        def getMDIZOrder(self):
163                """
164                Obtain the relative stacking order (i.e. 'Z' order) of an object.
165                Larger values indicate that an object is on "top" of the stack,
166                therefore objects with smaller MDIZOrder may be obscured by objects
167                with a larger MDIZOrder, but not vice-versa.
168                @return an integer indicating the object's place in the stacking
169                order.
170                """
171                return Atspi.Component.get_mdi_z_order(self.obj)
172
173        def getPosition(self, coord_type):
174                """
175                Obtain the position of the current component in the coordinate
176                system specified by coord_type.
177                The returned values are meaningful only if the Component has
178                both STATE_VISIBLE and STATE_SHOWING.
179                @param : coord_type
180                @param : x
181                an out parameter which will be back-filled with the returned
182                x coordinate.
183                @param : y
184                an out parameter which will be back-filled with the returned
185                y coordinate.
186                """
187                return pointToList(Atspi.Component.get_position(self.obj, coord_type))
188
189        def getSize(self):
190                """
191                Obtain the size, in the coordinate system specified by coord_type,
192                of the rectangular area which fully contains the object's visual
193                representation, without accounting for viewport clipping.
194                The returned values are meaningful only if the Component has
195                both STATE_VISIBLE and STATE_SHOWING.
196                @param : width
197                the object's horizontal extents in the specified coordinate system.
198                @param : height
199                the object's vertical extents in the specified coordinate system.
200                """
201                return pointToList(Atspi.Component.get_size(self.obj))
202
203        def grabFocus(self):
204                """
205                Request that the object obtain keyboard focus.
206                @return True if keyboard focus was successfully transferred to
207                the Component.
208                """
209                return Atspi.Component.grab_focus(self.obj)
210
211        def scrollTo(self, scroll_type):
212                """
213                Makes the object visible on the screen at a given position by
214                scrolling all necessary parents.
215                @return True if scrolling was successful.
216                """
217                return Atspi.Component.scroll_to(self.obj, scroll_type)
218
219        def scrollToPoint(self, coord_type, x, y):
220                """
221                Makes the object visible on the screen at a given position by
222                scrolling all necessary parents.
223                @return True if scrolling was successful.
224                """
225                return Atspi.Component.scroll_to_point(self.obj, coord_type, x, y)
226
227#END----------------------------------------------------------------------------
228