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 struct _AtkKeyEventStruct {
  88   gint type;
  89   guint state;
  90   guint keyval;
  91   gint length;
  92   gchar *string;
  93   guint16 keycode;
  94   guint32 timestamp;
  95 };
  96
  97 /**
  98  *AtkKeyEventType:
  99  *@ATK_KEY_EVENT_PRESS: specifies a key press event
 100  *@ATK_KEY_EVENT_RELEASE: specifies a key release event
 101  *@ATK_KEY_EVENT_LAST_DEFINED: Not a valid value; specifies end of enumeration
 102  *
 103  *Specifies the type of a keyboard evemt.
 104  **/
 105 typedef enum
 106 {
 107   ATK_KEY_EVENT_PRESS,
 108   ATK_KEY_EVENT_RELEASE,
 109   ATK_KEY_EVENT_LAST_DEFINED
 110 } AtkKeyEventType;
 111
 112 struct _AtkUtil
 113 {
 114   GObject parent;
 115 };
 116
 117 struct _AtkUtilClass
 118 {
 119    GObjectClass parent;
 120    guint        (* add_global_event_listener)    (GSignalEmissionHook listener,
 121                                                   const gchar        *event_type);
 122    void         (* remove_global_event_listener) (guint               listener_id);
 123    guint        (* add_key_event_listener)       (AtkKeySnoopFunc     listener,
 124                                                   gpointer data);
 125    void         (* remove_key_event_listener)    (guint               listener_id);
 126    AtkObject*   (* get_root)                     (void);
 127    G_CONST_RETURN gchar* (* get_toolkit_name)    (void);
 128    G_CONST_RETURN gchar* (* get_toolkit_version) (void);
 129 };
 130 GType atk_util_get_type (void);
 131
 132 /**
 133  *AtkCoordType:
 134  *@ATK_XY_SCREEN: specifies xy coordinates relative to the screen
 135  *@ATK_XY_WINDOW: specifies xy coordinates relative to the widget's
 136  * top-level window
 137  *
 138  *Specifies how xy coordinates are to be interpreted. Used by functions such
 139  *as atk_component_get_position() and atk_text_get_character_extents()
 140  **/
 141 typedef enum {
 142   ATK_XY_SCREEN,
 143   ATK_XY_WINDOW
 144 }AtkCoordType;
 145
 146 /*
 147  * Adds the specified function to the list of functions to be called
 148  * when an object receives focus.
 149  */
 150 guint    atk_add_focus_tracker     (AtkEventListener      focus_tracker);
 151
 152 /*
 153  * Removes the specified focus tracker from the list of function
 154  * to be called when any object receives focus
 155  */
 156 void     atk_remove_focus_tracker  (guint                tracker_id);
 157
 158 /*
 159  * atk_focus_tracker_init:
 160  * @init: An #AtkEventListenerInit function to be called
 161  * prior to any focus-tracking requests.
 162  *
 163  * Specifies the function to be called for focus tracker initialization.
 164  * removal. This function should be called by an implementation of the
 165  * ATK interface if any specific work needs to be done to enable
 166  * focus tracking.
 167  */
 168 void     atk_focus_tracker_init    (AtkEventListenerInit  init);
 169
 170 /*
 171  * Cause the focus tracker functions which have been specified to be
 172  * executed for the object.
 173  */
 174 void     atk_focus_tracker_notify  (AtkObject            *object);
 175
 176 /*
 177  * Adds the specified function to the list of functions to be called
 178  * when an event of type event_type occurs.
 179  */
 180 guint   atk_add_global_event_listener (GSignalEmissionHook listener,
 181                                        const gchar        *event_type);
 182
 183 /*
 184  * Removes the specified event listener
 185  */
 186 void    atk_remove_global_event_listener (guint listener_id);
 187
 188 /*
 189  * Adds the specified function to the list of functions to be called
 190  * when an keyboard event occurs.
 191  */
 192 guint   atk_add_key_event_listener (AtkKeySnoopFunc listener, gpointer data);
 193
 194 /*
 195  * Removes the specified event listener
 196  */
 197 void    atk_remove_key_event_listener (guint listener_id);
 198
 199 /*
 200  * Returns the root accessible container for the current application.
 201  */
 202 AtkObject* atk_get_root(void);
 203
 204 AtkObject* atk_get_focus_object (void);
 205
 206 /*
 207  * Returns name string for the GUI toolkit.
 208  */
 209 G_CONST_RETURN gchar *atk_get_toolkit_name (void);
 210
 211 /*
 212  * Returns version string for the GUI toolkit.
 213  */
 214 G_CONST_RETURN gchar *atk_get_toolkit_version (void);
 215
 216 #ifdef __cplusplus
 217 }
 218 #endif /* __cplusplus */
 219
 220
 221 #endif /* __ATK_UTIL_H__ */