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
39#ifndef _TYPEDEF_ATK_UTIL_
40#define _TYPEDEF_ATK_UTIL_
41typedef struct _AtkUtil AtkUtil;
42typedef struct _AtkUtilClass AtkUtilClass;
43typedef struct _AtkKeyEventStruct AtkKeyEventStruct;
44#endif
45
46/**
47 * AtkEventListener:
48 * @obj: An #AtkObject instance for whom the callback will be called when
49 * the specified event (e.g. 'focus:') takes place.
50 *
51 * A function which is called when an object emits a matching event,
52 * as used in #atk_add_focus_tracker.
53 * Currently the only events for which object-specific handlers are
54 * supported are events of type "focus:". Most clients of ATK will prefer to
55 * attach signal handlers for the various ATK signals instead.
56 *
57 * see atk_add_focus_tracker.
58 **/
59typedef void (*AtkEventListener) (AtkObject* obj);
60/**
61 * AtkEventListenerInit:
62 *
63 * An #AtkEventListenerInit function is a special function that is
64 * called in order to initialize the per-object event registration system
65 * used by #AtkEventListener, if any preparation is required.
66 *
67 * see atk_focus_tracker_init.
68 **/
69typedef void (*AtkEventListenerInit) (void);
70/**
71 * AtkKeySnoopFunc:
72 * @event: an AtkKeyEventStruct containing information about the key event for which
73 * notification is being given.
74 * @user_data: a block of data which will be passed to the event listener, on notification.
75 *
76 * An #AtkKeySnoopFunc is a type of callback which is called whenever a key event occurs,
77 * if registered via atk_add_key_event_listener. It allows for pre-emptive
78 * interception of key events via the return code as described below.
79 *
80 * Returns: TRUE (nonzero) if the event emission should be stopped and the event
81 * discarded without being passed to the normal GUI recipient; FALSE (zero) if the
82 * event dispatch to the client application should proceed as normal.
83 *
84 * see atk_add_key_event_listener.
85 **/
86typedef gint (*AtkKeySnoopFunc) (AtkKeyEventStruct *event,
87 gpointer user_data);
88
89/**
90 * AtkKeyEventStruct:
91 * @type: An AtkKeyEventType, generally one of ATK_KEY_EVENT_PRESS or ATK_KEY_EVENT_RELEASE
92 * @state: A bitmask representing the state of the modifier keys immediately after the event takes place.
93 * The meaning of the bits is currently defined to match the bitmask used by GDK in
94 * GdkEventType.state, see
95 * http://developer.gnome.org/doc/API/2.0/gdk/gdk-Event-Structures.html#GdkEventKey
96 * @keyval: A guint representing a keysym value corresponding to those used by GDK and X11: see
97 * /usr/X11/include/keysymdef.h.
98 * @length: The length of member #string.
99 * @string: A string containing one of the following: either a string approximating the text that would
100 * result from this keypress, if the key is a control or graphic character, or a symbolic name for this keypress.
101 * Alphanumeric and printable keys will have the symbolic key name in this string member, for instance "A". "0",
102 * "semicolon", "aacute". Keypad keys have the prefix "KP".
103 * @keycode: The raw hardware code that generated the key event. This field is raraly useful.
104 * @timestamp: A timestamp in milliseconds indicating when the event occurred.
105 * These timestamps are relative to a starting point which should be considered arbitrary,
106 * and only used to compare the dispatch times of events to one another.
107 *
108 * Encapsulates information about a key event.
109 **/
110struct _AtkKeyEventStruct {
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 ATK_XY_SCREEN,
189 ATK_XY_WINDOW,
190 ATK_XY_PARENT
191}AtkCoordType;
192
193ATK_DEPRECATED_IN_2_10
194guint atk_add_focus_tracker (AtkEventListener focus_tracker);
195ATK_DEPRECATED_IN_2_10
196void atk_remove_focus_tracker (guint tracker_id);
197ATK_DEPRECATED_IN_2_10
198void atk_focus_tracker_init (AtkEventListenerInit init);
199ATK_DEPRECATED_IN_2_10
200void atk_focus_tracker_notify (AtkObject *object);
201ATK_AVAILABLE_IN_ALL
202guint atk_add_global_event_listener (GSignalEmissionHook listener,
203 const gchar *event_type);
204ATK_AVAILABLE_IN_ALL
205void atk_remove_global_event_listener (guint listener_id);
206ATK_AVAILABLE_IN_ALL
207guint atk_add_key_event_listener (AtkKeySnoopFunc listener, gpointer data);
208ATK_AVAILABLE_IN_ALL
209void atk_remove_key_event_listener (guint listener_id);
210
211ATK_AVAILABLE_IN_ALL
212AtkObject* atk_get_root(void);
213ATK_AVAILABLE_IN_ALL
214AtkObject* atk_get_focus_object (void);
215
216ATK_AVAILABLE_IN_ALL
217const gchar *atk_get_toolkit_name (void);
218ATK_AVAILABLE_IN_ALL
219const gchar *atk_get_toolkit_version (void);
220ATK_AVAILABLE_IN_ALL
221const gchar *atk_get_version (void);
222
223/* --- GType boilerplate --- */
224/* convenience macros for atk type implementations, which for a type GtkGadgetAccessible will:
225 * - prototype: static void gtk_gadget_accessible_class_init (GtkGadgetClass *klass);
226 * - prototype: static void gtk_gadget_accessible_init (GtkGadget *self);
227 * - define: static gpointer gtk_gadget_accessible_parent_class = NULL;
228 * gtk_gadget_accessible_parent_class is initialized prior to calling gtk_gadget_class_init()
229 * - implement: GType gtk_gadget_accessible_get_type (void) { ... }
230 * - support custom code in gtk_gadget_accessible_get_type() after the type is registered.
231 *
232 * macro arguments: TypeName, type_name, TYPE_PARENT, CODE
233 * example: ATK_DEFINE_TYPE_WITH_CODE (GtkGadgetAccessible, gtk_gadget_accessible, GTK_TYPE_GADGET,
234 * G_IMPLEMENT_INTERFACE (ATK_TYPE_TABLE, gtk_gadget_accessible_table_iface_init))
235 */
236
237/**
238 * ATK_DEFINE_TYPE:
239 * @TN: The name of the new type, in Camel case.
240 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
241 * @T_P: The #GType of the parent type.
242 *
243 * A convenience macro for type ATK implementations, which declares a class
244 * initialization function, an instance initialization function (see #GTypeInfo
245 * for information about these) and a static variable named
246 * @t_n _parent_class pointing to the parent class. Furthermore, it
247 * defines a _get_type() function.
248 *
249 * Since: 1.22
250 */
251#define ATK_DEFINE_TYPE(TN, t_n, T_P) ATK_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, {})
252
253/**
254 * ATK_DEFINE_TYPE_WITH_CODE:
255 * @TN: The name of the new type, in Camel case.
256 * @t_n: The name of the new type in lowercase, with words separated by '_'.
257 * @T_P: The #GType of the parent type.
258 * @_C_: Custom code that gets inserted in the _get_type() function.
259 *
260 * A convenience macro for ATK type implementations.
261 * Similar to ATK_DEFINE_TYPE(), but allows you to insert custom code into the
262 * _get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE().
263 *
264 * Since: 1.22
265 */
266#define ATK_DEFINE_TYPE_WITH_CODE(TN, t_n, T_P, _C_) _ATK_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, 0) {_C_;} _ATK_DEFINE_TYPE_EXTENDED_END()
267
268/**
269 * ATK_DEFINE_ABSTRACT_TYPE:
270 * @TN: The name of the new type, in Camel case.
271 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
272 * @T_P: The #GType of the parent type.
273 *
274 * A convenience macro for ATK type implementations.
275 * Similar to ATK_DEFINE_TYPE(), but defines an abstract type.
276 *
277 * Since: 1.22
278 */
279#define ATK_DEFINE_ABSTRACT_TYPE(TN, t_n, T_P) ATK_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, {})
280
281/**
282 * ATK_DEFINE_ABSTRACT_TYPE_WITH_CODE:
283 * @TN: The name of the new type, in Camel case.
284 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
285 * @T_P: The #GType of the parent type.
286 * @_C_: Custom code that gets inserted in the _get_type() function.
287 *
288 * A convenience macro for ATK type implementations.
289 * Similar to ATK_DEFINE_TYPE_WITH_CODE(), but defines an abstract type.
290 *
291 * Since: 1.22
292 */
293#define ATK_DEFINE_ABSTRACT_TYPE_WITH_CODE(TN, t_n, T_P, _C_) _ATK_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT) {_C_;} _ATK_DEFINE_TYPE_EXTENDED_END()
294
295/**
296 * ATK_DEFINE_TYPE_EXTENDED:
297 * @TN: The name of the new type, in Camel case.
298 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
299 * @T_P: The #GType of the parent type.
300 * @_f_: #GTypeFlags to pass to g_type_register_static()
301 * @_C_: Custom code that gets inserted in the _get_type() function.
302 *
303 * The most general convenience macro for ATK type implementations, on which
304 * ATK_DEFINE_TYPE(), etc are based.
305 *
306 * Since: 1.22
307 */
308#define ATK_DEFINE_TYPE_EXTENDED(TN, t_n, T_P, _f_, _C_) _ATK_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, _f_) {_C_;} _ATK_DEFINE_TYPE_EXTENDED_END()
309
310#define _ATK_DEFINE_TYPE_EXTENDED_BEGIN(TypeName, type_name, TYPE, flags) \
311\
312static void type_name##_init (TypeName *self); \
313static void type_name##_class_init (TypeName##Class *klass); \
314static gpointer type_name##_parent_class = NULL; \
315static void type_name##_class_intern_init (gpointer klass) \
316{ \
317 type_name##_parent_class = g_type_class_peek_parent (klass); \
318 type_name##_class_init ((TypeName##Class*) klass); \
319} \
320\
321ATK_AVAILABLE_IN_ALL \
322GType \
323type_name##_get_type (void) \
324{ \
325 static volatile gsize g_define_type_id__volatile = 0; \
326 if (g_once_init_enter (&g_define_type_id__volatile)) \
327 { \
328 AtkObjectFactory *factory; \
329 GType derived_type; \
330 GTypeQuery query; \
331 GType derived_atk_type; \
332 GType g_define_type_id; \
333\
334 /* Figure out the size of the class and instance we are deriving from */ \
335 derived_type = g_type_parent (TYPE); \
336 factory = atk_registry_get_factory (atk_get_default_registry (), \
337 derived_type); \
338 derived_atk_type = atk_object_factory_get_accessible_type (factory); \
339 g_type_query (derived_atk_type, &query); \
340\
341 g_define_type_id = \
342 g_type_register_static_simple (derived_atk_type, \
343 g_intern_static_string (#TypeName), \
344 query.class_size, \
345 (GClassInitFunc) type_name##_class_intern_init, \
346 query.instance_size, \
347 (GInstanceInitFunc) type_name##_init, \
348 (GTypeFlags) flags); \
349 { /* custom code follows */
350#define _ATK_DEFINE_TYPE_EXTENDED_END() \
351 /* following custom code */ \
352 } \
353 g_once_init_leave (&g_define_type_id__volatile, g_define_type_id); \
354 } \
355 return g_define_type_id__volatile; \
356} /* closes type_name##_get_type() */
357
358G_END_DECLS
359
360#endif /* __ATK_UTIL_H__ */
361