diff options
author | Bill Haneman <billh@src.gnome.org> | 2006-03-20 14:49:04 +0000 |
---|---|---|
committer | Bill Haneman <billh@src.gnome.org> | 2006-03-20 14:49:04 +0000 |
commit | abe3a033eece55a775a7df20f288dd62b937b8cb (patch) | |
tree | bb12959a85139691e99ff39111bb18a934949b7c | |
parent | c1926f534b4605f421ef958ae1e7f3fb1d17a07e (diff) | |
download | atk-abe3a033eece55a775a7df20f288dd62b937b8cb.tar.gz |
Minor documentation clarifications and tweaks.
-rw-r--r-- | ChangeLog | 13 | ||||
-rwxr-xr-x | atk/atkimage.c | 7 | ||||
-rwxr-xr-x | atk/atkobject.c | 11 | ||||
-rwxr-xr-x | atk/atkutil.h | 50 | ||||
-rw-r--r-- | docs/tmpl/atkobject.sgml | 2 | ||||
-rw-r--r-- | docs/tmpl/atkutil.sgml | 31 |
6 files changed, 82 insertions, 32 deletions
@@ -1,4 +1,17 @@ 2006-03-20 Bill Haneman <bill.haneman@sun.com> + + * atk/atkutil.h: Added missing info on AtkEventListener, + AtkEventListenerInit, and AtkKeySnoopFunc. bug #320911. + + * atk/atkimage.h: Moved information about '-1' return values + to the corresponding parameters. bug #320916. + + * atk/atkobject.c: Fixed some docs issues in comment blocks. + + * docs/tmpl/atkobject.sgml: Clarify children-changed signal + params. bug #162410. + +2006-03-20 Bill Haneman <bill.haneman@sun.com> * atk/atkimage.c: Bug detected by Behdad Estafood (atk_image_get_position): Allow for NULL-in params. diff --git a/atk/atkimage.c b/atk/atkimage.c index 1f69fbc..3566d67 100755 --- a/atk/atkimage.c +++ b/atk/atkimage.c @@ -68,12 +68,12 @@ atk_image_get_image_description (AtkImage *image) /** * atk_image_get_image_size: * @image: a #GObject instance that implements AtkImageIface - * @width: filled with the image width - * @height: filled with the image height + * @width: filled with the image width, or -1 if the value cannot be obtained. + * @height: filled with the image height, or -1 if the value cannot be obtained. * * Get the width and height in pixels for the specified image. * The values of @width and @height are returned as -1 if the - * values cannot be obtained. + * values cannot be obtained (for instance, if the object is not onscreen). **/ void atk_image_get_image_size (AtkImage *image, @@ -189,6 +189,7 @@ atk_image_get_image_position (AtkImage *image, /** * Returns a string corresponding to the POSIX LC_MESSAGES locale used by the image description, or NULL if the image does not specify a locale. + * @image: An #AtkImage * @Since ATK 1.12 */ G_CONST_RETURN gchar* diff --git a/atk/atkobject.c b/atk/atkobject.c index 80dca6f..f896b51 100755 --- a/atk/atkobject.c +++ b/atk/atkobject.c @@ -1008,17 +1008,17 @@ atk_object_notify_state_change (AtkObject *accessible, * Returns: a reference to an object's #AtkObject implementation */ AtkObject * -atk_implementor_ref_accessible (AtkImplementor *object) +atk_implementor_ref_accessible (AtkImplementor *implementor) { AtkImplementorIface *iface; AtkObject *accessible = NULL; - g_return_val_if_fail (ATK_IS_IMPLEMENTOR (object), NULL); + g_return_val_if_fail (ATK_IS_IMPLEMENTOR (implementor), NULL); - iface = ATK_IMPLEMENTOR_GET_IFACE (object); + iface = ATK_IMPLEMENTOR_GET_IFACE (implementor); if (iface != NULL) - accessible = iface->ref_accessible (object); + accessible = iface->ref_accessible (implementor); g_return_val_if_fail ((accessible != NULL), NULL); @@ -1027,6 +1027,9 @@ atk_implementor_ref_accessible (AtkImplementor *object) /** + * atk_object_get_attributes: + * + * @accessible: An #AtkObject. * Get a list of properties applied to this object as a whole, as an #AtkAttributeSet consisting of * name-value pairs. As such these attributes may be considered weakly-typed properties or annotations, * as distinct from strongly-typed object data available via other get/set methods. diff --git a/atk/atkutil.h b/atk/atkutil.h index 042d610..1dbfcf3 100755 --- a/atk/atkutil.h +++ b/atk/atkutil.h @@ -41,12 +41,46 @@ typedef struct _AtkUtilClass AtkUtilClass; typedef struct _AtkKeyEventStruct AtkKeyEventStruct; #endif -/* - * A focus tracker is a function which is called when an object - * receives focus. - */ -typedef void (*AtkEventListener) (AtkObject*); +/** + * 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); @@ -122,12 +156,16 @@ guint atk_add_focus_tracker (AtkEventListener focus_tracker); 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 add_function); +void atk_focus_tracker_init (AtkEventListenerInit init); /* * Cause the focus tracker functions which have been specified to be diff --git a/docs/tmpl/atkobject.sgml b/docs/tmpl/atkobject.sgml index dc03dd3..4a0835a 100644 --- a/docs/tmpl/atkobject.sgml +++ b/docs/tmpl/atkobject.sgml @@ -60,7 +60,7 @@ removed form an object. It supports two details: "add" and "remove" @atkobject: the object which received the signal. @arg1: The index of the added or removed child -@arg2: The child which was added or removed +@arg2: A gpointer to the child AtkObject which was added or removed <!-- ##### SIGNAL AtkObject::focus-event ##### --> <para> diff --git a/docs/tmpl/atkutil.sgml b/docs/tmpl/atkutil.sgml index c715f41..08b2507 100644 --- a/docs/tmpl/atkutil.sgml +++ b/docs/tmpl/atkutil.sgml @@ -2,14 +2,13 @@ AtkUtil <!-- ##### SECTION Short_Description ##### --> -This is a utility class which supports the adding and removal of event listeners. +A set of ATK utility functions for event and toolkit support. <!-- ##### SECTION Long_Description ##### --> <para> -This is a utility class which supports the adding and removal of event -listeners. The adding and removing of the listeners must be done in the -same thread. The file also contains a number of utility functions. - +A set of ATK utility functions which are used to support event registration of +various types, and obtaining the 'root' accessible of a process and +information about the current ATK implementation and toolkit version. </para> <!-- ##### SECTION See_Also ##### --> @@ -22,7 +21,6 @@ same thread. The file also contains a number of utility functions. <!-- ##### STRUCT AtkUtil ##### --> <para> -The AtkObject structure should not be accessed directly. </para> @@ -57,6 +55,8 @@ The AtkObject structure should not be accessed directly. </para> +@init: +<!-- # Unused Parameters # --> @add_function: @@ -70,19 +70,14 @@ The AtkObject structure should not be accessed directly. <!-- ##### USER_FUNCTION AtkEventListener ##### --> <para> -An AtkEventListener is user specified function which is called when an event, -such as receiving focus, occurs. The parameter of the AtkEventListener is the -AtkObject on which the event occurred. + </para> -@Param1: an #AtkObject +@obj: <!-- ##### USER_FUNCTION AtkEventListenerInit ##### --> <para> -An AtkEventListenerInit is an initialization function in an implementation -of the ATK interface used to perform implementation-specific initialization -when enabling focus tracking. </para> @@ -108,7 +103,7 @@ when enabling focus tracking. <!-- ##### STRUCT AtkKeyEventStruct ##### --> <para> -The AtkKeyEventStruct describes a keyboard event. + </para> @type: @@ -130,12 +125,12 @@ The AtkKeyEventStruct describes a keyboard event. <!-- ##### USER_FUNCTION AtkKeySnoopFunc ##### --> <para> -An AtkKeySnoopFunc is a function which is called when a keyboard event occurs. + </para> -@event: keyboard event -@func_data: a data gpointer for the function -@Returns: return code +@event: +@func_data: +@Returns: <!-- ##### FUNCTION atk_add_key_event_listener ##### --> |