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 #include <atk/atkobject.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif /* __cplusplus */
  28
  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))
  35
  36
  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;
  42 #endif
  43
  44 /**
  45  * AtkEventListener:
  46  * @obj: An #AtkObject instance for whom the callback will be called when
  47  * the specified event (e.g. 'focus:') takes place.
  48  *
  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.
  54  *
  55  * @see: atk_add_focus_tracker.
  56  **/
  57 typedef void  (*AtkEventListener) (AtkObject* obj);
  58 /**
  59  * AtkEventListenerInit:
  60  *
  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.
  64  *
  65  * @see: atk_focus_tracker_init.
  66  **/
  67 typedef void  (*AtkEventListenerInit) (void);
  68 /**
  69  * AtkKeySnoopFunc:
  70  * @event: an AtkKeyEventStruct containing information about the key event for which
  71  * notification is being given.
  72  * @func_data: a block of data which will be passed to the event listener, on notification.
  73  *
  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.
  77  *
  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.
  81  *
  82  * @see: atk_add_key_event_listener.
  83  **/
  84 typedef gint  (*AtkKeySnoopFunc)  (AtkKeyEventStruct *event,
  85                                    gpointer func_data);
  86
  87 /**
  88  * AtkKeyEventStruct:
  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.
 105  *
 106  * Encapsulates information about a key event.
 107  **/
 108 struct _AtkKeyEventStruct {
 109   gint type;
 110   guint state;
 111   guint keyval;
 112   gint length;
 113   gchar *string;
 114   guint16 keycode;
 115   guint32 timestamp;
 116 };
 117
 118 /**
 119  *AtkKeyEventType:
 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
 123  *
 124  *Specifies the type of a keyboard evemt.
 125  **/
 126 typedef enum
 127 {
 128   ATK_KEY_EVENT_PRESS,
 129   ATK_KEY_EVENT_RELEASE,
 130   ATK_KEY_EVENT_LAST_DEFINED
 131 } AtkKeyEventType;
 132
 133 struct _AtkUtil
 134 {
 135   GObject parent;
 136 };
 137
 138 struct _AtkUtilClass
 139 {
 140    GObjectClass parent;
 141    guint        (* add_global_event_listener)    (GSignalEmissionHook listener,
 142                                                   const gchar        *event_type);
 143    void         (* remove_global_event_listener) (guint               listener_id);
 144    guint        (* add_key_event_listener)       (AtkKeySnoopFunc     listener,
 145                                                   gpointer data);
 146    void         (* remove_key_event_listener)    (guint               listener_id);
 147    AtkObject*   (* get_root)                     (void);
 148    G_CONST_RETURN gchar* (* get_toolkit_name)    (void);
 149    G_CONST_RETURN gchar* (* get_toolkit_version) (void);
 150 };
 151 GType atk_util_get_type (void);
 152
 153 /**
 154  *AtkCoordType:
 155  *@ATK_XY_SCREEN: specifies xy coordinates relative to the screen
 156  *@ATK_XY_WINDOW: specifies xy coordinates relative to the widget's
 157  * top-level window
 158  *
 159  *Specifies how xy coordinates are to be interpreted. Used by functions such
 160  *as atk_component_get_position() and atk_text_get_character_extents()
 161  **/
 162 typedef enum {
 163   ATK_XY_SCREEN,
 164   ATK_XY_WINDOW
 165 }AtkCoordType;
 166
 167 /*
 168  * Adds the specified function to the list of functions to be called
 169  * when an object receives focus.
 170  */
 171 guint    atk_add_focus_tracker     (AtkEventListener      focus_tracker);
 172
 173 /*
 174  * Removes the specified focus tracker from the list of function
 175  * to be called when any object receives focus
 176  */
 177 void     atk_remove_focus_tracker  (guint                tracker_id);
 178
 179 /*
 180  * atk_focus_tracker_init:
 181  * @init: An #AtkEventListenerInit function to be called
 182  * prior to any focus-tracking requests.
 183  *
 184  * Specifies the function to be called for focus tracker initialization.
 185  * removal. This function should be called by an implementation of the
 186  * ATK interface if any specific work needs to be done to enable
 187  * focus tracking.
 188  */
 189 void     atk_focus_tracker_init    (AtkEventListenerInit  init);
 190
 191 /*
 192  * Cause the focus tracker functions which have been specified to be
 193  * executed for the object.
 194  */
 195 void     atk_focus_tracker_notify  (AtkObject            *object);
 196
 197 /*
 198  * Adds the specified function to the list of functions to be called
 199  * when an event of type event_type occurs.
 200  */
 201 guint   atk_add_global_event_listener (GSignalEmissionHook listener,
 202                                        const gchar        *event_type);
 203
 204 /*
 205  * Removes the specified event listener
 206  */
 207 void    atk_remove_global_event_listener (guint listener_id);
 208
 209 /*
 210  * Adds the specified function to the list of functions to be called
 211  * when an keyboard event occurs.
 212  */
 213 guint   atk_add_key_event_listener (AtkKeySnoopFunc listener, gpointer data);
 214
 215 /*
 216  * Removes the specified event listener
 217  */
 218 void    atk_remove_key_event_listener (guint listener_id);
 219
 220 /*
 221  * Returns the root accessible container for the current application.
 222  */
 223 AtkObject* atk_get_root(void);
 224
 225 AtkObject* atk_get_focus_object (void);
 226
 227 /*
 228  * Returns name string for the GUI toolkit.
 229  */
 230 G_CONST_RETURN gchar *atk_get_toolkit_name (void);
 231
 232 /*
 233  * Returns version string for the GUI toolkit.
 234  */
 235 G_CONST_RETURN gchar *atk_get_toolkit_version (void);
 236
 237 /*
 238  * Gets the current version of ATK
 239  */
 240 G_CONST_RETURN gchar *atk_get_version (void);
 241
 242 /* --- GType boilerplate --- */
 243 /* convenience macros for atk type implementations, which for a type GtkGadgetAccessible will:
 244  * - prototype: static void     gtk_gadget_accessible_class_init (GtkGadgetClass *klass);
 245  * - prototype: static void     gtk_gadget_accessible_init       (GtkGadget      *self);
 246  * - define:    static gpointer gtk_gadget_accessible_parent_class = NULL;
 247  *   gtk_gadget_accessible_parent_class is initialized prior to calling gtk_gadget_class_init()
 248  * - implement: GType           gtk_gadget_accessible_get_type (void) { ... }
 249  * - support custom code in gtk_gadget_accessible_get_type() after the type is registered.
 250  *
 251  * macro arguments: TypeName, type_name, TYPE_PARENT, CODE
 252  * example: ATK_DEFINE_TYPE_WITH_CODE (GtkGadgetAccessible, gtk_gadget_accessible, GTK_TYPE_GADGET,
 253  *                                     G_IMPLEMENT_INTERFACE (ATK_TYPE_TABLE, gtk_gadget_accessible_table_iface_init))
 254  */
 255
 256 #define ATK_DEFINE_TYPE(TN, t_n, T_P)                          ATK_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, {})
 257 #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()
 258 #define ATK_DEFINE_ABSTRACT_TYPE(TN, t_n, T_P)                 ATK_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, {})
 259 #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()
 260 #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()
 261
 262 #define _ATK_DEFINE_TYPE_EXTENDED_BEGIN(TypeName, type_name, TYPE, flags) \
 263 \
 264 static void     type_name##_init              (TypeName        *self); \
 265 static void     type_name##_class_init        (TypeName##Class *klass); \
 266 static gpointer type_name##_parent_class = NULL; \
 267 static void     type_name##_class_intern_init (gpointer klass) \
 268 { \
 269   type_name##_parent_class = g_type_class_peek_parent (klass); \
 270   type_name##_class_init ((TypeName##Class*) klass); \
 271 } \
 272 \
 273 GType \
 274 type_name##_get_type (void) \
 275 { \
 276   static volatile gsize g_define_type_id__volatile = 0; \
 277   if (g_once_init_enter (&g_define_type_id__volatile))  \
 278     { \
 279       AtkObjectFactory *factory; \
 280       GType derived_type; \
 281       GTypeQuery query; \
 282       GType derived_atk_type; \
 283       GType g_define_type_id; \
 284 \
 285       /* Figure out the size of the class and instance we are deriving from */ \
 286       derived_type = g_type_parent (TYPE); \
 287       factory = atk_registry_get_factory (atk_get_default_registry (), \
 288                                           derived_type); \
 289       derived_atk_type = atk_object_factory_get_accessible_type (factory); \
 290       g_type_query (derived_atk_type, &query); \
 291 \
 292       g_define_type_id = \
 293         g_type_register_static_simple (derived_atk_type, \
 294                                        g_intern_static_string (#TypeName), \
 295                                        query.class_size, \
 296                                        (GClassInitFunc) type_name##_class_intern_init, \
 297                                        query.instance_size, \
 298                                        (GInstanceInitFunc) type_name##_init, \
 299                                        (GTypeFlags) flags); \
 300       { /* custom code follows */
 301 #define _ATK_DEFINE_TYPE_EXTENDED_END() \
 302         /* following custom code */     \
 303       }                                 \
 304       g_once_init_leave (&g_define_type_id__volatile, g_define_type_id); \
 305     }                                   \
 306   return g_define_type_id__volatile;    \
 307 } /* closes type_name##_get_type() */
 308
 309
 310 #ifdef __cplusplus
 311 }
 312 #endif /* __cplusplus */
 313
 314
 315 #endif /* __ATK_UTIL_H__ */