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 #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
  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  *@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  **/
 187 typedef enum {
 188   ATK_XY_SCREEN,
 189   ATK_XY_WINDOW,
 190   ATK_XY_PARENT
 191 }AtkCoordType;
 192
 193 ATK_DEPRECATED_IN_2_10
 194 guint    atk_add_focus_tracker     (AtkEventListener      focus_tracker);
 195 ATK_DEPRECATED_IN_2_10
 196 void     atk_remove_focus_tracker  (guint                tracker_id);
 197 ATK_DEPRECATED_IN_2_10
 198 void     atk_focus_tracker_init    (AtkEventListenerInit  init);
 199 ATK_DEPRECATED_IN_2_10
 200 void     atk_focus_tracker_notify  (AtkObject            *object);
 201 ATK_AVAILABLE_IN_ALL
 202 guint   atk_add_global_event_listener (GSignalEmissionHook listener,
 203                                        const gchar        *event_type);
 204 ATK_AVAILABLE_IN_ALL
 205 void    atk_remove_global_event_listener (guint listener_id);
 206 ATK_AVAILABLE_IN_ALL
 207 guint   atk_add_key_event_listener (AtkKeySnoopFunc listener, gpointer data);
 208 ATK_AVAILABLE_IN_ALL
 209 void    atk_remove_key_event_listener (guint listener_id);
 210
 211 ATK_AVAILABLE_IN_ALL
 212 AtkObject* atk_get_root(void);
 213 ATK_AVAILABLE_IN_ALL
 214 AtkObject* atk_get_focus_object (void);
 215
 216 ATK_AVAILABLE_IN_ALL
 217 const gchar *atk_get_toolkit_name (void);
 218 ATK_AVAILABLE_IN_ALL
 219 const gchar *atk_get_toolkit_version (void);
 220 ATK_AVAILABLE_IN_ALL
 221 const 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 \
 312 static void     type_name##_init              (TypeName        *self); \
 313 static void     type_name##_class_init        (TypeName##Class *klass); \
 314 static gpointer type_name##_parent_class = NULL; \
 315 static 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 \
 321 ATK_AVAILABLE_IN_ALL \
 322 GType \
 323 type_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
 358 G_END_DECLS
 359
 360 #endif /* __ATK_UTIL_H__ */