Include config.h For All the C Source Files

[platform/upstream/atk.git] / atk / atkutil.c

diff --git a/atk/atkutil.c b/atk/atkutil.c
index 924d0a0..e9726e7 100755 (executable)
--- a/atk/atkutil.c
+++ b/atk/atkutil.c
@@ -17,9 +17,21 @@
  * Boston, MA 02111-1307, USA.
  */
 
+#include "config.h"
+
 #include "atkutil.h"
 #include "atkmarshal.c"
-#include "config.h"
+
+/**
+ * SECTION:atkutil
+ * @Short_description: A set of ATK utility functions for event and toolkit support.
+ * @Title:AtkUtil
+ *
+ * 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.
+ */
 
 static void atk_util_class_init (AtkUtilClass *klass);
 
@@ -87,6 +99,11 @@ struct _FocusTracker {
  * This function should be called by an implementation of the
  * ATK interface if any specific work needs to be done to enable
  * focus tracking.
+ *
+ * Deprecated: This method is deprecated since ATK version
+ * 2.9.4. Focus tracking has been dropped as a feature to be
+ * implemented by ATK itself.
+ *
  **/
 void
 atk_focus_tracker_init (AtkEventListenerInit    init)
@@ -103,6 +120,11 @@ atk_focus_tracker_init (AtkEventListenerInit    init)
  * Adds the specified function to the list of functions to be called
  * when an object receives focus.
  *
+ * Deprecated: This method is deprecated since ATK version
+ * 2.9.4. Focus tracking has been dropped as a feature to be
+ * implemented by ATK itself. If you need focus tracking on your
+ * implementation, subscribe to the state-changed:focused signal.
+ *
  * Returns: added focus tracker id, or 0 on failure.
  **/
 guint
@@ -138,6 +160,11 @@ atk_add_focus_tracker (AtkEventListener   focus_tracker)
  * atk_remove_focus_tracker:
  * @tracker_id: the id of the focus tracker to remove
  *
+ * Deprecated: This method is deprecated since ATK version
+ * 2.9.4. Focus tracking has been dropped as a feature to be
+ * implemented by ATK itself. If you need focus tracking on your
+ * implementation, subscribe to the state-changed:focused signal.
+ *
  * Removes the specified focus tracker from the list of functions
  * to be called when any object receives focus.
  **/
@@ -170,6 +197,11 @@ atk_remove_focus_tracker (guint            tracker_id)
  *
  * Cause the focus tracker functions which have been specified to be
  * executed for the object.
+ *
+ * Deprecated: This method is deprecated since ATK version
+ * 2.9.4. Focus tracking has been dropped as a feature to be
+ * implemented by ATK itself.
+ *
  **/
 void
 atk_focus_tracker_notify (AtkObject       *object)
@@ -322,11 +354,11 @@ atk_util_real_remove_global_event_listener (guint remove_listener)
  * when an ATK event of type event_type occurs.
  *
  * The format of event_type is the following:
- *  "ATK:<atk_type>:<atk_event>:<atk_event_detail>
+ *  "ATK:&lt;atk_type&gt;:&lt;atk_event&gt;:&lt;atk_event_detail&gt;
  *
- * Where "ATK" works as the namespace, <atk_interface> is the name of
- * the ATK type (interface or object), <atk_event> is the name of the
- * signal defined on that interface and <atk_event_detail> is the
+ * Where "ATK" works as the namespace, &lt;atk_interface&gt; is the name of
+ * the ATK type (interface or object), &lt;atk_event&gt; is the name of the
+ * signal defined on that interface and &lt;atk_event_detail&gt; is the
  * gsignal detail of that signal. You can find more info about gsignal
  * details here:
  * http://developer.gnome.org/gobject/stable/gobject-Signals.html
@@ -338,10 +370,12 @@ atk_util_real_remove_global_event_listener (guint remove_listener)
  *   ATK:AtkText:text-selection-changed
  *   ATK:AtkText:text-insert:system
  *
- * Toolkit implementor note: Atk provides a default implementation for
- * this virtual method, and that implementation should be enough for
- * most of the cases. You should have a really good reason to
- * reimplement this method.
+ * Toolkit implementor note: ATK provides a default implementation for
+ * this virtual method. ATK implementors are discouraged from
+ * reimplementing this method.
+ *
+ * Toolkit implementor note: this method is not intended to be used by
+ * ATK implementors but by ATK consumers.
  *
  * Returns: added event listener id, or 0 on failure.
  **/
@@ -372,10 +406,12 @@ atk_add_global_event_listener (GSignalEmissionHook listener,
  * @listener_id is the value returned by #atk_add_global_event_listener
  * when you registered that event listener.
  *
- * Toolkit implementor note: Atk provides a default implementation for
- * this virtual method, and that implementation should be enough for
- * most of the cases. You should have a really good reason to
- * reimplement this method.
+ * Toolkit implementor note: ATK provides a default implementation for
+ * this virtual method. ATK implementors are discouraged from
+ * reimplementing this method.
+ *
+ * Toolkit implementor note: this method is not intended to be used by
+ * ATK implementors but by ATK consumers.
  *
  * Removes the specified event listener
  **/