The Tor Browser / file revision

 /* ATK -  Accessibility Toolkit

  * Copyright 2001 Sun Microsystems Inc.

  *

  * This library is free software; you can redistribute it and/or

  * modify it under the terms of the GNU Library General Public

  * License as published by the Free Software Foundation; either

  * version 2 of the License, or (at your option) any later version.

  *

  * This library is distributed in the hope that it will be useful,

  * but WITHOUT ANY WARRANTY; without even the implied warranty of

  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

  * Library General Public License for more details.

  *

  * You should have received a copy of the GNU Library General Public

  * License along with this library; if not, write to the

  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,

  * Boston, MA 02111-1307, USA.

  */

 #ifndef __ATK_UTIL_H__

 #define __ATK_UTIL_H__

 #include <atk/atkobject.h>

 #ifdef __cplusplus

 extern "C" {

 #endif /* __cplusplus */

 #define ATK_TYPE_UTIL                   (atk_util_get_type ())

 #define ATK_IS_UTIL(obj)                G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_UTIL)

 #define ATK_UTIL(obj)                   G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_UTIL, AtkUtil)

 #define ATK_UTIL_CLASS(klass)                   (G_TYPE_CHECK_CLASS_CAST ((klass), ATK_TYPE_UTIL, AtkUtilClass))

 #define ATK_IS_UTIL_CLASS(klass)                (G_TYPE_CHECK_CLASS_TYPE ((klass), ATK_TYPE_UTIL))

 #define ATK_UTIL_GET_CLASS(obj)                 (G_TYPE_INSTANCE_GET_CLASS ((obj), ATK_TYPE_UTIL, AtkUtilClass))

 #ifndef _TYPEDEF_ATK_UTIL_

 #define _TYPEDEF_ATK_UTIL_

 typedef struct _AtkUtil      AtkUtil;

 typedef struct _AtkUtilClass AtkUtilClass;

 typedef struct _AtkKeyEventStruct AtkKeyEventStruct;

 #endif

 /**

  * AtkEventListener: 

  * @obj: An #AtkObject instance for whom the callback will be called when

  * the specified event (e.g. 'focus:') takes place.

  *

  * A function which is called when an object emits a matching event,

  * as used in #atk_add_focus_tracker.

  * Currently the only events for which object-specific handlers are

  * supported are events of type "focus:".  Most clients of ATK will prefer to 

  * attach signal handlers for the various ATK signals instead.

  *

  * @see: atk_add_focus_tracker.

  **/

 typedef void  (*AtkEventListener) (AtkObject* obj);

 /**

  * AtkEventListenerInit:

  *

  * An #AtkEventListenerInit function is a special function that is

  * called in order to initialize the per-object event registration system

  * used by #AtkEventListener, if any preparation is required.  

  *

  * @see: atk_focus_tracker_init.

  **/

 typedef void  (*AtkEventListenerInit) (void);

 /**

  * AtkKeySnoopFunc:

  * @event: an AtkKeyEventStruct containing information about the key event for which

  * notification is being given.

  * @func_data: a block of data which will be passed to the event listener, on notification.

  *

  * An #AtkKeySnoopFunc is a type of callback which is called whenever a key event occurs, 

  * if registered via atk_add_key_event_listener.  It allows for pre-emptive 

  * interception of key events via the return code as described below.

  *

  * Returns: TRUE (nonzero) if the event emission should be stopped and the event 

  * discarded without being passed to the normal GUI recipient; FALSE (zero) if the 

  * event dispatch to the client application should proceed as normal.

  *

  * @see: atk_add_key_event_listener.

  **/

 typedef gint  (*AtkKeySnoopFunc)  (AtkKeyEventStruct *event,

 				   gpointer func_data);

 /**

  * AtkKeyEventStruct:

  * @type: An AtkKeyEventType, generally one of ATK_KEY_EVENT_PRESS or ATK_KEY_EVENT_RELEASE

  * @state: A bitmask representing the state of the modifier keys immediately after the event takes place.   

  * The meaning of the bits is currently defined to match the bitmask used by GDK in

  * GdkEventType.state, see 

  * http://developer.gnome.org/doc/API/2.0/gdk/gdk-Event-Structures.html#GdkEventKey

  * @keyval: A guint representing a keysym value corresponding to those used by GDK and X11: see

  * /usr/X11/include/keysymdef.h.

  * @length: The length of member #string.

  * @string: A string containing one of the following: either a string approximating the text that would 

  * result from this keypress, if the key is a control or graphic character, or a symbolic name for this keypress.

  * Alphanumeric and printable keys will have the symbolic key name in this string member, for instance "A". "0", 

  * "semicolon", "aacute".  Keypad keys have the prefix "KP".

  * @keycode: The raw hardware code that generated the key event.  This field is raraly useful.

  * @timestamp: A timestamp in milliseconds indicating when the event occurred.  

  * These timestamps are relative to a starting point which should be considered arbitrary, 

  * and only used to compare the dispatch times of events to one another.

  *

  * Encapsulates information about a key event.

  **/

 struct _AtkKeyEventStruct {

   gint type;

   guint state;

   guint keyval;

   gint length;

   gchar *string;

   guint16 keycode;

   guint32 timestamp;	

 };

 /**

  *AtkKeyEventType:

  *@ATK_KEY_EVENT_PRESS: specifies a key press event

  *@ATK_KEY_EVENT_RELEASE: specifies a key release event

  *@ATK_KEY_EVENT_LAST_DEFINED: Not a valid value; specifies end of enumeration

  *

  *Specifies the type of a keyboard evemt.

  **/

 typedef enum

 {

   ATK_KEY_EVENT_PRESS,

   ATK_KEY_EVENT_RELEASE,

   ATK_KEY_EVENT_LAST_DEFINED

 } AtkKeyEventType;

 struct _AtkUtil

 {

   GObject parent;

 };

 struct _AtkUtilClass

 {

    GObjectClass parent;

    guint        (* add_global_event_listener)    (GSignalEmissionHook listener,

 						  const gchar        *event_type);

    void         (* remove_global_event_listener) (guint               listener_id);

    guint	(* add_key_event_listener) 	 (AtkKeySnoopFunc     listener,

 						  gpointer data);

    void         (* remove_key_event_listener)    (guint               listener_id);

    AtkObject*   (* get_root)                     (void);

    G_CONST_RETURN gchar* (* get_toolkit_name)    (void);

    G_CONST_RETURN gchar* (* get_toolkit_version) (void);

 };

 GType atk_util_get_type (void);

 /**

  *AtkCoordType:

  *@ATK_XY_SCREEN: specifies xy coordinates relative to the screen

  *@ATK_XY_WINDOW: specifies xy coordinates relative to the widget's 

  * top-level window

  *

  *Specifies how xy coordinates are to be interpreted. Used by functions such

  *as atk_component_get_position() and atk_text_get_character_extents() 

  **/

 typedef enum {

   ATK_XY_SCREEN,

   ATK_XY_WINDOW

 }AtkCoordType;

 /*

  * Adds the specified function to the list of functions to be called

  * when an object receives focus.

  */

 guint    atk_add_focus_tracker     (AtkEventListener      focus_tracker);

 /*

  * Removes the specified focus tracker from the list of function

  * to be called when any object receives focus

  */

 void     atk_remove_focus_tracker  (guint                tracker_id);

 /*

  * atk_focus_tracker_init:

  * @init: An #AtkEventListenerInit function to be called

  * prior to any focus-tracking requests.

  *

  * Specifies the function to be called for focus tracker initialization.

  * removal. This function should be called by an implementation of the

  * ATK interface if any specific work needs to be done to enable

  * focus tracking.

  */

 void     atk_focus_tracker_init    (AtkEventListenerInit  init);

 /*

  * Cause the focus tracker functions which have been specified to be

  * executed for the object.

  */

 void     atk_focus_tracker_notify  (AtkObject            *object);

 /*

  * Adds the specified function to the list of functions to be called

  * when an event of type event_type occurs.

  */

 guint	atk_add_global_event_listener (GSignalEmissionHook listener,

 				       const gchar        *event_type);

 /*

  * Removes the specified event listener

  */

 void	atk_remove_global_event_listener (guint listener_id);

 /*

  * Adds the specified function to the list of functions to be called

  * when an keyboard event occurs.

  */

 guint	atk_add_key_event_listener (AtkKeySnoopFunc listener, gpointer data);

 /*

  * Removes the specified event listener

  */

 void	atk_remove_key_event_listener (guint listener_id);

 /*

  * Returns the root accessible container for the current application.

  */

 AtkObject* atk_get_root(void);

 AtkObject* atk_get_focus_object (void);

 /*

  * Returns name string for the GUI toolkit.

  */

 G_CONST_RETURN gchar *atk_get_toolkit_name (void);

 /*

  * Returns version string for the GUI toolkit.

  */

 G_CONST_RETURN gchar *atk_get_toolkit_version (void);

 #ifdef __cplusplus

 }

 #endif /* __cplusplus */

 #endif /* __ATK_UTIL_H__ */