Annotate the Public Symbols in Public Headers
[platform/upstream/atk.git] / atk / atkutil.h
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 #if defined(ATK_DISABLE_SINGLE_INCLUDES) && !defined (__ATK_H_INSIDE__) && !defined (ATK_COMPILATION)
21 #error "Only <atk/atk.h> can be included directly."
22 #endif
23
24 #ifndef __ATK_UTIL_H__
25 #define __ATK_UTIL_H__
26
27 #include <atk/atkobject.h>
28
29 G_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_
41 typedef struct _AtkUtil      AtkUtil;
42 typedef struct _AtkUtilClass AtkUtilClass;
43 typedef 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  **/
59 typedef 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  **/
69 typedef 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  **/
86 typedef 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  **/
110 struct _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  **/
128 typedef enum
129 {
130   ATK_KEY_EVENT_PRESS,
131   ATK_KEY_EVENT_RELEASE,
132   ATK_KEY_EVENT_LAST_DEFINED
133 } AtkKeyEventType;
134
135 struct _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  */
160 struct _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 };
173 ATK_AVAILABLE_IN_ALL
174 GType 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  *
182  *Specifies how xy coordinates are to be interpreted. Used by functions such
183  *as atk_component_get_position() and atk_text_get_character_extents() 
184  **/
185 typedef enum {
186   ATK_XY_SCREEN,
187   ATK_XY_WINDOW
188 }AtkCoordType;
189
190 ATK_DEPRECATED_IN_2_10
191 guint    atk_add_focus_tracker     (AtkEventListener      focus_tracker);
192 ATK_DEPRECATED_IN_2_10
193 void     atk_remove_focus_tracker  (guint                tracker_id);
194 ATK_DEPRECATED_IN_2_10
195 void     atk_focus_tracker_init    (AtkEventListenerInit  init);
196 ATK_DEPRECATED_IN_2_10
197 void     atk_focus_tracker_notify  (AtkObject            *object);
198 ATK_AVAILABLE_IN_ALL
199 guint   atk_add_global_event_listener (GSignalEmissionHook listener,
200                                        const gchar        *event_type);
201 ATK_AVAILABLE_IN_ALL
202 void    atk_remove_global_event_listener (guint listener_id);
203 ATK_AVAILABLE_IN_ALL
204 guint   atk_add_key_event_listener (AtkKeySnoopFunc listener, gpointer data);
205 ATK_AVAILABLE_IN_ALL
206 void    atk_remove_key_event_listener (guint listener_id);
207
208 ATK_AVAILABLE_IN_ALL
209 AtkObject* atk_get_root(void);
210 ATK_AVAILABLE_IN_ALL
211 AtkObject* atk_get_focus_object (void);
212
213 ATK_AVAILABLE_IN_ALL
214 const gchar *atk_get_toolkit_name (void);
215 ATK_AVAILABLE_IN_ALL
216 const gchar *atk_get_toolkit_version (void);
217 ATK_AVAILABLE_IN_ALL
218 const gchar *atk_get_version (void);
219
220 /* --- GType boilerplate --- */
221 /* convenience macros for atk type implementations, which for a type GtkGadgetAccessible will:
222  * - prototype: static void     gtk_gadget_accessible_class_init (GtkGadgetClass *klass);
223  * - prototype: static void     gtk_gadget_accessible_init       (GtkGadget      *self);
224  * - define:    static gpointer gtk_gadget_accessible_parent_class = NULL;
225  *   gtk_gadget_accessible_parent_class is initialized prior to calling gtk_gadget_class_init()
226  * - implement: GType           gtk_gadget_accessible_get_type (void) { ... }
227  * - support custom code in gtk_gadget_accessible_get_type() after the type is registered.
228  *
229  * macro arguments: TypeName, type_name, TYPE_PARENT, CODE
230  * example: ATK_DEFINE_TYPE_WITH_CODE (GtkGadgetAccessible, gtk_gadget_accessible, GTK_TYPE_GADGET,
231  *                                     G_IMPLEMENT_INTERFACE (ATK_TYPE_TABLE, gtk_gadget_accessible_table_iface_init))
232  */
233
234 /**
235  * ATK_DEFINE_TYPE:
236  * @TN: The name of the new type, in Camel case.
237  * @t_n: The name of the new type, in lowercase, with words separated by '_'.
238  * @T_P: The #GType of the parent type.
239  *
240  * A convenience macro for type ATK implementations, which declares a class
241  * initialization function, an instance initialization function (see #GTypeInfo
242  * for information about these) and a static variable named
243  * @t_n _parent_class pointing to the parent class. Furthermore, it
244  * defines a _get_type() function.
245  *
246  * Since: 1.22
247  */
248 #define ATK_DEFINE_TYPE(TN, t_n, T_P)                          ATK_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, {})
249
250 /**
251  * ATK_DEFINE_TYPE_WITH_CODE:
252  * @TN: The name of the new type, in Camel case.
253  * @t_n: The name of the new type in lowercase, with words separated by '_'.
254  * @T_P: The #GType of the parent type.
255  * @_C_: Custom code that gets inserted in the _get_type() function.
256  *
257  * A convenience macro for ATK type implementations.
258  * Similar to ATK_DEFINE_TYPE(), but allows you to insert custom code into the
259  * _get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE().
260  *
261  * Since: 1.22
262  */
263 #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()
264
265 /**
266  * ATK_DEFINE_ABSTRACT_TYPE:
267  * @TN: The name of the new type, in Camel case.
268  * @t_n: The name of the new type, in lowercase, with words separated by '_'.
269  * @T_P: The #GType of the parent type.
270  *
271  * A convenience macro for ATK type implementations.
272  * Similar to ATK_DEFINE_TYPE(), but defines an abstract type.
273  *
274  * Since: 1.22
275  */
276 #define ATK_DEFINE_ABSTRACT_TYPE(TN, t_n, T_P)                 ATK_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, {})
277
278 /**
279  * ATK_DEFINE_ABSTRACT_TYPE_WITH_CODE:
280  * @TN: The name of the new type, in Camel case.
281  * @t_n: The name of the new type, in lowercase, with words separated by '_'.
282  * @T_P: The #GType of the parent type.
283  * @_C_: Custom code that gets inserted in the _get_type() function.
284  *
285  * A convenience macro for ATK type implementations.
286  * Similar to ATK_DEFINE_TYPE_WITH_CODE(), but defines an abstract type.
287  *
288  * Since: 1.22
289  */
290 #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()
291
292 /**
293  * ATK_DEFINE_TYPE_EXTENDED:
294  * @TN: The name of the new type, in Camel case.
295  * @t_n: The name of the new type, in lowercase, with words separated by '_'.
296  * @T_P: The #GType of the parent type.
297  * @_f_: #GTypeFlags to pass to g_type_register_static()
298  * @_C_: Custom code that gets inserted in the _get_type() function.
299  *
300  * The most general convenience macro for ATK type implementations, on which
301  * ATK_DEFINE_TYPE(), etc are based.
302  *
303  * Since: 1.22
304  */
305 #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()
306
307 #define _ATK_DEFINE_TYPE_EXTENDED_BEGIN(TypeName, type_name, TYPE, flags) \
308 \
309 static void     type_name##_init              (TypeName        *self); \
310 static void     type_name##_class_init        (TypeName##Class *klass); \
311 static gpointer type_name##_parent_class = NULL; \
312 static void     type_name##_class_intern_init (gpointer klass) \
313 { \
314   type_name##_parent_class = g_type_class_peek_parent (klass); \
315   type_name##_class_init ((TypeName##Class*) klass); \
316 } \
317 \
318 ATK_AVAILABLE_IN_ALL \
319 GType \
320 type_name##_get_type (void) \
321 { \
322   static volatile gsize g_define_type_id__volatile = 0; \
323   if (g_once_init_enter (&g_define_type_id__volatile))  \
324     { \
325       AtkObjectFactory *factory; \
326       GType derived_type; \
327       GTypeQuery query; \
328       GType derived_atk_type; \
329       GType g_define_type_id; \
330 \
331       /* Figure out the size of the class and instance we are deriving from */ \
332       derived_type = g_type_parent (TYPE); \
333       factory = atk_registry_get_factory (atk_get_default_registry (), \
334                                           derived_type); \
335       derived_atk_type = atk_object_factory_get_accessible_type (factory); \
336       g_type_query (derived_atk_type, &query); \
337 \
338       g_define_type_id = \
339         g_type_register_static_simple (derived_atk_type, \
340                                        g_intern_static_string (#TypeName), \
341                                        query.class_size, \
342                                        (GClassInitFunc) type_name##_class_intern_init, \
343                                        query.instance_size, \
344                                        (GInstanceInitFunc) type_name##_init, \
345                                        (GTypeFlags) flags); \
346       { /* custom code follows */
347 #define _ATK_DEFINE_TYPE_EXTENDED_END() \
348         /* following custom code */     \
349       }                                 \
350       g_once_init_leave (&g_define_type_id__volatile, g_define_type_id); \
351     }                                   \
352   return g_define_type_id__volatile;    \
353 } /* closes type_name##_get_type() */
354
355 G_END_DECLS
356
357 #endif /* __ATK_UTIL_H__ */