1 /* ATK - Accessibility Toolkit
2 * Copyright 2001 Sun Microsystems Inc.
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.
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.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
18 #if defined(ATK_DISABLE_SINGLE_INCLUDES) && !defined (__ATK_H_INSIDE__) && !defined (ATK_COMPILATION)
19 #error "Only <atk/atk.h> can be included directly."
22 #ifndef __ATK_UTIL_H__
23 #define __ATK_UTIL_H__
25 #include <atk/atkobject.h>
29 #define ATK_TYPE_UTIL (atk_util_get_type ())
30 #define ATK_IS_UTIL(obj) G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_UTIL)
31 #define ATK_UTIL(obj) G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_UTIL, AtkUtil)
32 #define ATK_UTIL_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), ATK_TYPE_UTIL, AtkUtilClass))
33 #define ATK_IS_UTIL_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), ATK_TYPE_UTIL))
34 #define ATK_UTIL_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), ATK_TYPE_UTIL, AtkUtilClass))
37 #ifndef _TYPEDEF_ATK_UTIL_
38 #define _TYPEDEF_ATK_UTIL_
39 typedef struct _AtkUtil AtkUtil;
40 typedef struct _AtkUtilClass AtkUtilClass;
41 typedef struct _AtkKeyEventStruct AtkKeyEventStruct;
46 * @obj: An #AtkObject instance for whom the callback will be called when
47 * the specified event (e.g. 'focus:') takes place.
49 * A function which is called when an object emits a matching event,
50 * as used in #atk_add_focus_tracker.
51 * Currently the only events for which object-specific handlers are
52 * supported are events of type "focus:". Most clients of ATK will prefer to
53 * attach signal handlers for the various ATK signals instead.
55 * see atk_add_focus_tracker.
57 typedef void (*AtkEventListener) (AtkObject* obj);
59 * AtkEventListenerInit:
61 * An #AtkEventListenerInit function is a special function that is
62 * called in order to initialize the per-object event registration system
63 * used by #AtkEventListener, if any preparation is required.
65 * see atk_focus_tracker_init.
67 typedef void (*AtkEventListenerInit) (void);
70 * @event: an AtkKeyEventStruct containing information about the key event for which
71 * notification is being given.
72 * @user_data: a block of data which will be passed to the event listener, on notification.
74 * An #AtkKeySnoopFunc is a type of callback which is called whenever a key event occurs,
75 * if registered via atk_add_key_event_listener. It allows for pre-emptive
76 * interception of key events via the return code as described below.
78 * Returns: TRUE (nonzero) if the event emission should be stopped and the event
79 * discarded without being passed to the normal GUI recipient; FALSE (zero) if the
80 * event dispatch to the client application should proceed as normal.
82 * see atk_add_key_event_listener.
84 typedef gint (*AtkKeySnoopFunc) (AtkKeyEventStruct *event,
89 * @type: An AtkKeyEventType, generally one of ATK_KEY_EVENT_PRESS or ATK_KEY_EVENT_RELEASE
90 * @state: A bitmask representing the state of the modifier keys immediately after the event takes place.
91 * The meaning of the bits is currently defined to match the bitmask used by GDK in
92 * GdkEventType.state, see
93 * http://developer.gnome.org/doc/API/2.0/gdk/gdk-Event-Structures.html#GdkEventKey
94 * @keyval: A guint representing a keysym value corresponding to those used by GDK and X11: see
95 * /usr/X11/include/keysymdef.h.
96 * @length: The length of member #string.
97 * @string: A string containing one of the following: either a string approximating the text that would
98 * result from this keypress, if the key is a control or graphic character, or a symbolic name for this keypress.
99 * Alphanumeric and printable keys will have the symbolic key name in this string member, for instance "A". "0",
100 * "semicolon", "aacute". Keypad keys have the prefix "KP".
101 * @keycode: The raw hardware code that generated the key event. This field is raraly useful.
102 * @timestamp: A timestamp in milliseconds indicating when the event occurred.
103 * These timestamps are relative to a starting point which should be considered arbitrary,
104 * and only used to compare the dispatch times of events to one another.
106 * Encapsulates information about a key event.
108 struct _AtkKeyEventStruct {
120 *@ATK_KEY_EVENT_PRESS: specifies a key press event
121 *@ATK_KEY_EVENT_RELEASE: specifies a key release event
122 *@ATK_KEY_EVENT_LAST_DEFINED: Not a valid value; specifies end of enumeration
124 *Specifies the type of a keyboard evemt.
129 ATK_KEY_EVENT_RELEASE,
130 ATK_KEY_EVENT_LAST_DEFINED
140 * @add_global_event_listener: adds the specified function to the list
141 * of functions to be called when an ATK event occurs. ATK
142 * implementors are discouraged from reimplementing this method.
143 * @remove_global_event_listener: removes the specified function to
144 * the list of functions to be called when an ATK event occurs. ATK
145 * implementors are discouraged from reimplementing this method.
146 * @add_key_event_listener: adds the specified function to the list of
147 * functions to be called when a key event occurs.
148 * @remove_key_event_listener: remove the specified function to the
149 * list of functions to be called when a key event occurs.
150 * @get_root: gets the root accessible container for the current
152 * @get_toolkit_name: gets name string for the GUI toolkit
153 * implementing ATK for this application.
154 * @get_toolkit_version: gets version string for the GUI toolkit
155 * implementing ATK for this application.
161 guint (* add_global_event_listener) (GSignalEmissionHook listener,
162 const gchar *event_type);
163 void (* remove_global_event_listener) (guint listener_id);
164 guint (* add_key_event_listener) (AtkKeySnoopFunc listener,
166 void (* remove_key_event_listener) (guint listener_id);
167 AtkObject* (* get_root) (void);
168 const gchar* (* get_toolkit_name) (void);
169 const gchar* (* get_toolkit_version) (void);
171 GType atk_util_get_type (void);
175 *@ATK_XY_SCREEN: specifies xy coordinates relative to the screen
176 *@ATK_XY_WINDOW: specifies xy coordinates relative to the widget's
179 *Specifies how xy coordinates are to be interpreted. Used by functions such
180 *as atk_component_get_position() and atk_text_get_character_extents()
188 guint atk_add_focus_tracker (AtkEventListener focus_tracker);
190 void atk_remove_focus_tracker (guint tracker_id);
192 void atk_focus_tracker_init (AtkEventListenerInit init);
194 void atk_focus_tracker_notify (AtkObject *object);
195 guint atk_add_global_event_listener (GSignalEmissionHook listener,
196 const gchar *event_type);
197 void atk_remove_global_event_listener (guint listener_id);
198 guint atk_add_key_event_listener (AtkKeySnoopFunc listener, gpointer data);
199 void atk_remove_key_event_listener (guint listener_id);
201 AtkObject* atk_get_root(void);
202 AtkObject* atk_get_focus_object (void);
204 const gchar *atk_get_toolkit_name (void);
205 const gchar *atk_get_toolkit_version (void);
206 const gchar *atk_get_version (void);
208 /* --- GType boilerplate --- */
209 /* convenience macros for atk type implementations, which for a type GtkGadgetAccessible will:
210 * - prototype: static void gtk_gadget_accessible_class_init (GtkGadgetClass *klass);
211 * - prototype: static void gtk_gadget_accessible_init (GtkGadget *self);
212 * - define: static gpointer gtk_gadget_accessible_parent_class = NULL;
213 * gtk_gadget_accessible_parent_class is initialized prior to calling gtk_gadget_class_init()
214 * - implement: GType gtk_gadget_accessible_get_type (void) { ... }
215 * - support custom code in gtk_gadget_accessible_get_type() after the type is registered.
217 * macro arguments: TypeName, type_name, TYPE_PARENT, CODE
218 * example: ATK_DEFINE_TYPE_WITH_CODE (GtkGadgetAccessible, gtk_gadget_accessible, GTK_TYPE_GADGET,
219 * G_IMPLEMENT_INTERFACE (ATK_TYPE_TABLE, gtk_gadget_accessible_table_iface_init))
224 * @TN: The name of the new type, in Camel case.
225 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
226 * @T_P: The #GType of the parent type.
228 * A convenience macro for type ATK implementations, which declares a class
229 * initialization function, an instance initialization function (see #GTypeInfo
230 * for information about these) and a static variable named
231 * @t_n _parent_class pointing to the parent class. Furthermore, it
232 * defines a _get_type() function.
236 #define ATK_DEFINE_TYPE(TN, t_n, T_P) ATK_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, {})
239 * ATK_DEFINE_TYPE_WITH_CODE:
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 * @_C_: Custom code that gets inserted in the _get_type() function.
245 * A convenience macro for ATK type implementations.
246 * Similar to ATK_DEFINE_TYPE(), but allows you to insert custom code into the
247 * _get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE().
251 #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()
254 * ATK_DEFINE_ABSTRACT_TYPE:
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.
259 * A convenience macro for ATK type implementations.
260 * Similar to ATK_DEFINE_TYPE(), but defines an abstract type.
264 #define ATK_DEFINE_ABSTRACT_TYPE(TN, t_n, T_P) ATK_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, {})
267 * ATK_DEFINE_ABSTRACT_TYPE_WITH_CODE:
268 * @TN: The name of the new type, in Camel case.
269 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
270 * @T_P: The #GType of the parent type.
271 * @_C_: Custom code that gets inserted in the _get_type() function.
273 * A convenience macro for ATK type implementations.
274 * Similar to ATK_DEFINE_TYPE_WITH_CODE(), but defines an abstract type.
278 #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()
281 * ATK_DEFINE_TYPE_EXTENDED:
282 * @TN: The name of the new type, in Camel case.
283 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
284 * @T_P: The #GType of the parent type.
285 * @_f_: #GTypeFlags to pass to g_type_register_static()
286 * @_C_: Custom code that gets inserted in the _get_type() function.
288 * The most general convenience macro for ATK type implementations, on which
289 * ATK_DEFINE_TYPE(), etc are based.
293 #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()
295 #define _ATK_DEFINE_TYPE_EXTENDED_BEGIN(TypeName, type_name, TYPE, flags) \
297 static void type_name##_init (TypeName *self); \
298 static void type_name##_class_init (TypeName##Class *klass); \
299 static gpointer type_name##_parent_class = NULL; \
300 static void type_name##_class_intern_init (gpointer klass) \
302 type_name##_parent_class = g_type_class_peek_parent (klass); \
303 type_name##_class_init ((TypeName##Class*) klass); \
307 type_name##_get_type (void) \
309 static volatile gsize g_define_type_id__volatile = 0; \
310 if (g_once_init_enter (&g_define_type_id__volatile)) \
312 AtkObjectFactory *factory; \
313 GType derived_type; \
315 GType derived_atk_type; \
316 GType g_define_type_id; \
318 /* Figure out the size of the class and instance we are deriving from */ \
319 derived_type = g_type_parent (TYPE); \
320 factory = atk_registry_get_factory (atk_get_default_registry (), \
322 derived_atk_type = atk_object_factory_get_accessible_type (factory); \
323 g_type_query (derived_atk_type, &query); \
326 g_type_register_static_simple (derived_atk_type, \
327 g_intern_static_string (#TypeName), \
329 (GClassInitFunc) type_name##_class_intern_init, \
330 query.instance_size, \
331 (GInstanceInitFunc) type_name##_init, \
332 (GTypeFlags) flags); \
333 { /* custom code follows */
334 #define _ATK_DEFINE_TYPE_EXTENDED_END() \
335 /* following custom code */ \
337 g_once_init_leave (&g_define_type_id__volatile, g_define_type_id); \
339 return g_define_type_id__volatile; \
340 } /* closes type_name##_get_type() */
344 #endif /* __ATK_UTIL_H__ */