atkutil.h (8591B)
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 *@ATK_XY_PARENT: specifies xy coordinates relative to the widget's 159 * immediate parent. 160 * 161 *Specifies how xy coordinates are to be interpreted. Used by functions such 162 *as atk_component_get_position() and atk_text_get_character_extents() 163 **/ 164 typedef enum { 165 ATK_XY_SCREEN, 166 ATK_XY_WINDOW, 167 ATK_XY_PARENT 168 }AtkCoordType; 169 170 /* 171 * Adds the specified function to the list of functions to be called 172 * when an object receives focus. 173 */ 174 guint atk_add_focus_tracker (AtkEventListener focus_tracker); 175 176 /* 177 * Removes the specified focus tracker from the list of function 178 * to be called when any object receives focus 179 */ 180 void atk_remove_focus_tracker (guint tracker_id); 181 182 /* 183 * atk_focus_tracker_init: 184 * @init: An #AtkEventListenerInit function to be called 185 * prior to any focus-tracking requests. 186 * 187 * Specifies the function to be called for focus tracker initialization. 188 * removal. This function should be called by an implementation of the 189 * ATK interface if any specific work needs to be done to enable 190 * focus tracking. 191 */ 192 void atk_focus_tracker_init (AtkEventListenerInit init); 193 194 /* 195 * Cause the focus tracker functions which have been specified to be 196 * executed for the object. 197 */ 198 void atk_focus_tracker_notify (AtkObject *object); 199 200 /* 201 * Adds the specified function to the list of functions to be called 202 * when an event of type event_type occurs. 203 */ 204 guint atk_add_global_event_listener (GSignalEmissionHook listener, 205 const gchar *event_type); 206 207 /* 208 * Removes the specified event listener 209 */ 210 void atk_remove_global_event_listener (guint listener_id); 211 212 /* 213 * Adds the specified function to the list of functions to be called 214 * when an keyboard event occurs. 215 */ 216 guint atk_add_key_event_listener (AtkKeySnoopFunc listener, gpointer data); 217 218 /* 219 * Removes the specified event listener 220 */ 221 void atk_remove_key_event_listener (guint listener_id); 222 223 /* 224 * Returns the root accessible container for the current application. 225 */ 226 AtkObject* atk_get_root(void); 227 228 AtkObject* atk_get_focus_object (void); 229 230 /* 231 * Returns name string for the GUI toolkit. 232 */ 233 G_CONST_RETURN gchar *atk_get_toolkit_name (void); 234 235 /* 236 * Returns version string for the GUI toolkit. 237 */ 238 G_CONST_RETURN gchar *atk_get_toolkit_version (void); 239 240 #ifdef __cplusplus 241 } 242 #endif /* __cplusplus */ 243 244 245 #endif /* __ATK_UTIL_H__ */