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.
/**
* 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,
/**
* 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*
* 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);
/**
+ * 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.
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);
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
@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>
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 ##### -->
<!-- ##### STRUCT AtkUtil ##### -->
<para>
-The AtkObject structure should not be accessed directly.
</para>
</para>
+@init:
+<!-- # Unused Parameters # -->
@add_function:
<!-- ##### 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>
<!-- ##### STRUCT AtkKeyEventStruct ##### -->
<para>
-The AtkKeyEventStruct describes a keyboard event.
+
</para>
@type:
<!-- ##### 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 ##### -->