1/* ATK - Accessibility Toolkit
2 * Copyright 2001 Sun Microsystems Inc.
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
13 *
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
18 */
19
20#ifndef __ATK_UTIL_H__
21#define __ATK_UTIL_H__
22
23#if defined(ATK_DISABLE_SINGLE_INCLUDES) && !defined(__ATK_H_INSIDE__) && !defined(ATK_COMPILATION)
24#error "Only <atk/atk.h> can be included directly."
25#endif
26
27#include <atk/atkobject.h>
28
29G_BEGIN_DECLS
30
31#define ATK_TYPE_UTIL (atk_util_get_type ())
32#define ATK_IS_UTIL(obj) G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_UTIL)
33#define ATK_UTIL(obj) G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_UTIL, AtkUtil)
34#define ATK_UTIL_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), ATK_TYPE_UTIL, AtkUtilClass))
35#define ATK_IS_UTIL_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), ATK_TYPE_UTIL))
36#define ATK_UTIL_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), ATK_TYPE_UTIL, AtkUtilClass))
37
38#ifndef _TYPEDEF_ATK_UTIL_
39#define _TYPEDEF_ATK_UTIL_
40typedef struct _AtkUtil AtkUtil;
41typedef struct _AtkUtilClass AtkUtilClass;
42typedef struct _AtkKeyEventStruct AtkKeyEventStruct;
43#endif
44
45/**
46 * AtkEventListener:
47 * @obj: An #AtkObject instance for whom the callback will be called when
48 * the specified event (e.g. 'focus:') takes place.
49 *
50 * A function which is called when an object emits a matching event,
51 * as used in #atk_add_focus_tracker.
52 * Currently the only events for which object-specific handlers are
53 * supported are events of type "focus:". Most clients of ATK will prefer to
54 * attach signal handlers for the various ATK signals instead.
55 *
56 * see [id@atk_add_focus_tracker]
57 **/
58typedef void (*AtkEventListener) (AtkObject *obj);
59/**
60 * AtkEventListenerInit:
61 *
62 * An #AtkEventListenerInit function is a special function that is
63 * called in order to initialize the per-object event registration system
64 * used by #AtkEventListener, if any preparation is required.
65 *
66 * see [id@atk_focus_tracker_init]
67 **/
68typedef void (*AtkEventListenerInit) (void);
69/**
70 * AtkKeySnoopFunc:
71 * @event: an AtkKeyEventStruct containing information about the key event for which
72 * notification is being given.
73 * @user_data: a block of data which will be passed to the event listener, on notification.
74 *
75 * An #AtkKeySnoopFunc is a type of callback which is called whenever a key event occurs,
76 * if registered via atk_add_key_event_listener. It allows for pre-emptive
77 * interception of key events via the return code as described below.
78 *
79 * Returns: TRUE (nonzero) if the event emission should be stopped and the event
80 * discarded without being passed to the normal GUI recipient; FALSE (zero) if the
81 * event dispatch to the client application should proceed as normal.
82 *
83 * see [id@atk_add_key_event_listener]
84 **/
85typedef gint (*AtkKeySnoopFunc) (AtkKeyEventStruct *event,
86 gpointer user_data);
87
88/**
89 * AtkKeyEventStruct:
90 * @type: An AtkKeyEventType, generally one of ATK_KEY_EVENT_PRESS or ATK_KEY_EVENT_RELEASE
91 * @state: A bitmask representing the state of the modifier keys immediately after the event takes place.
92 * The meaning of the bits is currently defined to match the bitmask used by GDK in
93 * GdkEventType.state, see
94 * http://developer.gnome.org/doc/API/2.0/gdk/gdk-Event-Structures.html#GdkEventKey
95 * @keyval: A guint representing a keysym value corresponding to those used by GDK and X11: see
96 * /usr/X11/include/keysymdef.h.
97 * @length: The length of member #string.
98 * @string: A string containing one of the following: either a string approximating the text that would
99 * result from this keypress, if the key is a control or graphic character, or a symbolic name for this keypress.
100 * Alphanumeric and printable keys will have the symbolic key name in this string member, for instance "A". "0",
101 * "semicolon", "aacute". Keypad keys have the prefix "KP".
102 * @keycode: The raw hardware code that generated the key event. This field is raraly useful.
103 * @timestamp: A timestamp in milliseconds indicating when the event occurred.
104 * These timestamps are relative to a starting point which should be considered arbitrary,
105 * and only used to compare the dispatch times of events to one another.
106 *
107 * Encapsulates information about a key event.
108 **/
109struct _AtkKeyEventStruct
110{
111 gint type;
112 guint state;
113 guint keyval;
114 gint length;
115 gchar *string;
116 guint16 keycode;
117 guint32 timestamp;
118};
119
120/**
121 *AtkKeyEventType:
122 *@ATK_KEY_EVENT_PRESS: specifies a key press event
123 *@ATK_KEY_EVENT_RELEASE: specifies a key release event
124 *@ATK_KEY_EVENT_LAST_DEFINED: Not a valid value; specifies end of enumeration
125 *
126 *Specifies the type of a keyboard evemt.
127 **/
128typedef enum
129{
130 ATK_KEY_EVENT_PRESS,
131 ATK_KEY_EVENT_RELEASE,
132 ATK_KEY_EVENT_LAST_DEFINED
133} AtkKeyEventType;
134
135struct _AtkUtil
136{
137 GObject parent;
138};
139
140/**
141 * AtkUtilClass:
142 * @add_global_event_listener: adds the specified function to the list
143 * of functions to be called when an ATK event occurs. ATK
144 * implementors are discouraged from reimplementing this method.
145 * @remove_global_event_listener: removes the specified function to
146 * the list of functions to be called when an ATK event occurs. ATK
147 * implementors are discouraged from reimplementing this method.
148 * @add_key_event_listener: adds the specified function to the list of
149 * functions to be called when a key event occurs.
150 * @remove_key_event_listener: remove the specified function to the
151 * list of functions to be called when a key event occurs.
152 * @get_root: gets the root accessible container for the current
153 * application.
154 * @get_toolkit_name: gets name string for the GUI toolkit
155 * implementing ATK for this application.
156 * @get_toolkit_version: gets version string for the GUI toolkit
157 * implementing ATK for this application.
158 *
159 */
160struct _AtkUtilClass
161{
162 GObjectClass parent;
163 guint (*add_global_event_listener) (GSignalEmissionHook listener,
164 const gchar *event_type);
165 void (*remove_global_event_listener) (guint listener_id);
166 guint (*add_key_event_listener) (AtkKeySnoopFunc listener,
167 gpointer data);
168 void (*remove_key_event_listener) (guint listener_id);
169 AtkObject *(*get_root) (void);
170 const gchar *(*get_toolkit_name) (void);
171 const gchar *(*get_toolkit_version) (void);
172};
173ATK_AVAILABLE_IN_ALL
174GType atk_util_get_type (void);
175
176/**
177 *AtkCoordType:
178 *@ATK_XY_SCREEN: specifies xy coordinates relative to the screen
179 *@ATK_XY_WINDOW: specifies xy coordinates relative to the widget's
180 * top-level window
181 *@ATK_XY_PARENT: specifies xy coordinates relative to the widget's
182 * immediate parent. Since: 2.30
183 *
184 *Specifies how xy coordinates are to be interpreted. Used by functions such
185 *as atk_component_get_position() and atk_text_get_character_extents()
186 **/
187typedef enum
188{
189 ATK_XY_SCREEN,
190 ATK_XY_WINDOW,
191 ATK_XY_PARENT
192} AtkCoordType;
193
194ATK_DEPRECATED_IN_2_10
195guint atk_add_focus_tracker (AtkEventListener focus_tracker);
196ATK_DEPRECATED_IN_2_10
197void atk_remove_focus_tracker (guint tracker_id);
198ATK_DEPRECATED_IN_2_10
199void atk_focus_tracker_init (AtkEventListenerInit init);
200ATK_DEPRECATED_IN_2_10
201void atk_focus_tracker_notify (AtkObject *object);
202ATK_AVAILABLE_IN_ALL
203guint atk_add_global_event_listener (GSignalEmissionHook listener,
204 const gchar *event_type);
205ATK_AVAILABLE_IN_ALL
206void atk_remove_global_event_listener (guint listener_id);
207ATK_AVAILABLE_IN_ALL
208guint atk_add_key_event_listener (AtkKeySnoopFunc listener, gpointer data);
209ATK_AVAILABLE_IN_ALL
210void atk_remove_key_event_listener (guint listener_id);
211
212ATK_AVAILABLE_IN_ALL
213AtkObject *atk_get_root (void);
214ATK_AVAILABLE_IN_ALL
215AtkObject *atk_get_focus_object (void);
216
217ATK_AVAILABLE_IN_ALL
218const gchar *atk_get_toolkit_name (void);
219ATK_AVAILABLE_IN_ALL
220const gchar *atk_get_toolkit_version (void);
221ATK_AVAILABLE_IN_ALL
222const gchar *atk_get_version (void);
223
224/* --- GType boilerplate --- */
225/* convenience macros for atk type implementations, which for a type GtkGadgetAccessible will:
226 * - prototype: static void gtk_gadget_accessible_class_init (GtkGadgetClass *klass);
227 * - prototype: static void gtk_gadget_accessible_init (GtkGadget *self);
228 * - define: static gpointer gtk_gadget_accessible_parent_class = NULL;
229 * gtk_gadget_accessible_parent_class is initialized prior to calling gtk_gadget_class_init()
230 * - implement: GType gtk_gadget_accessible_get_type (void) { ... }
231 * - support custom code in gtk_gadget_accessible_get_type() after the type is registered.
232 *
233 * macro arguments: TypeName, type_name, TYPE_PARENT, CODE
234 * example: ATK_DEFINE_TYPE_WITH_CODE (GtkGadgetAccessible, gtk_gadget_accessible, GTK_TYPE_GADGET,
235 * G_IMPLEMENT_INTERFACE (ATK_TYPE_TABLE, gtk_gadget_accessible_table_iface_init))
236 */
237
238/**
239 * ATK_DEFINE_TYPE:
240 * @TN: The name of the new type, in Camel case.
241 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
242 * @T_P: The #GType of the parent type.
243 *
244 * A convenience macro for type ATK implementations, which declares a class
245 * initialization function, an instance initialization function (see #GTypeInfo
246 * for information about these) and a static variable named
247 * @t_n _parent_class pointing to the parent class. Furthermore, it
248 * defines a _get_type() function.
249 *
250 * Since: 1.22
251 */
252#define ATK_DEFINE_TYPE(TN, t_n, T_P) ATK_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, {})
253
254/**
255 * ATK_DEFINE_TYPE_WITH_CODE:
256 * @TN: The name of the new type, in Camel case.
257 * @t_n: The name of the new type in lowercase, with words separated by '_'.
258 * @T_P: The #GType of the parent type.
259 * @_C_: Custom code that gets inserted in the _get_type() function.
260 *
261 * A convenience macro for ATK type implementations.
262 * Similar to ATK_DEFINE_TYPE(), but allows you to insert custom code into the
263 * _get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE().
264 *
265 * Since: 1.22
266 */
267#define ATK_DEFINE_TYPE_WITH_CODE(TN, t_n, T_P, _C_) \
268 _ATK_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, 0) { _C_; } \
269 _ATK_DEFINE_TYPE_EXTENDED_END ()
270
271/**
272 * ATK_DEFINE_ABSTRACT_TYPE:
273 * @TN: The name of the new type, in Camel case.
274 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
275 * @T_P: The #GType of the parent type.
276 *
277 * A convenience macro for ATK type implementations.
278 * Similar to ATK_DEFINE_TYPE(), but defines an abstract type.
279 *
280 * Since: 1.22
281 */
282#define ATK_DEFINE_ABSTRACT_TYPE(TN, t_n, T_P) ATK_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, {})
283
284/**
285 * ATK_DEFINE_ABSTRACT_TYPE_WITH_CODE:
286 * @TN: The name of the new type, in Camel case.
287 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
288 * @T_P: The #GType of the parent type.
289 * @_C_: Custom code that gets inserted in the _get_type() function.
290 *
291 * A convenience macro for ATK type implementations.
292 * Similar to ATK_DEFINE_TYPE_WITH_CODE(), but defines an abstract type.
293 *
294 * Since: 1.22
295 */
296#define ATK_DEFINE_ABSTRACT_TYPE_WITH_CODE(TN, t_n, T_P, _C_) \
297 _ATK_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT) { _C_; } \
298 _ATK_DEFINE_TYPE_EXTENDED_END ()
299
300/**
301 * ATK_DEFINE_TYPE_EXTENDED:
302 * @TN: The name of the new type, in Camel case.
303 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
304 * @T_P: The #GType of the parent type.
305 * @_f_: #GTypeFlags to pass to g_type_register_static()
306 * @_C_: Custom code that gets inserted in the _get_type() function.
307 *
308 * The most general convenience macro for ATK type implementations, on which
309 * ATK_DEFINE_TYPE(), etc are based.
310 *
311 * Since: 1.22
312 */
313#define ATK_DEFINE_TYPE_EXTENDED(TN, t_n, T_P, _f_, _C_) \
314 _ATK_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, _f_) { _C_; } \
315 _ATK_DEFINE_TYPE_EXTENDED_END ()
316
317#define _ATK_DEFINE_TYPE_EXTENDED_BEGIN(TypeName, type_name, TYPE, flags) \
318 \
319 static void type_name##_init (TypeName *self); \
320 static void type_name##_class_init (TypeName##Class *klass); \
321 static gpointer type_name##_parent_class = NULL; \
322 static void type_name##_class_intern_init (gpointer klass) \
323 { \
324 type_name##_parent_class = g_type_class_peek_parent (klass); \
325 type_name##_class_init ((TypeName##Class *) klass); \
326 } \
327 \
328 ATK_AVAILABLE_IN_ALL \
329 GType \
330 type_name##_get_type (void) \
331 { \
332 static volatile gsize g_define_type_id__volatile = 0; \
333 if (g_once_init_enter (&g_define_type_id__volatile)) \
334 { \
335 AtkObjectFactory *factory; \
336 GType derived_type; \
337 GTypeQuery query; \
338 GType derived_atk_type; \
339 GType g_define_type_id; \
340 \
341 /* Figure out the size of the class and instance we are deriving from */ \
342 derived_type = g_type_parent (TYPE); \
343 factory = atk_registry_get_factory (atk_get_default_registry (), \
344 derived_type); \
345 derived_atk_type = atk_object_factory_get_accessible_type (factory); \
346 g_type_query (derived_atk_type, &query); \
347 \
348 g_define_type_id = \
349 g_type_register_static_simple (derived_atk_type, \
350 g_intern_static_string (#TypeName), \
351 query.class_size, \
352 (GClassInitFunc) type_name##_class_intern_init, \
353 query.instance_size, \
354 (GInstanceInitFunc) type_name##_init, \
355 (GTypeFlags) flags); \
356 { /* custom code follows */
357#define _ATK_DEFINE_TYPE_EXTENDED_END() \
358 /* following custom code */ \
359 } \
360 g_once_init_leave (&g_define_type_id__volatile, g_define_type_id); \
361 } \
362 return g_define_type_id__volatile; \
363 } /* closes type_name##_get_type() */
364
365G_END_DECLS
366
367#endif /* __ATK_UTIL_H__ */
368

source code of include/atk-1.0/atk/atkutil.h