[atk] Deprecate AtkObject::focus-event signal and all related methods

[Alejandro Piñeiro Iglesias <apinheiro src gnome org>]

commit c568794a6f75cc9cc297b24978bc7480ee689bea
Author: Alejandro Piñeiro <apinheiro igalia com>
Date:   Mon Aug 12 16:47:06 2013 +0200

    Deprecate AtkObject::focus-event signal and all related methods
    
    From now on, state-changed:focused is the only focus related signal
    to use. All the tracking methods (on both AtkUtil and AtkComponent)
    are also deprecated.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=649575

 atk/atkcomponent.c |   11 ++++++++++-
 atk/atkcomponent.h |   30 ++++++++++++++++++++++++++++--
 atk/atkdocument.h  |    5 +++++
 atk/atkobject.c    |   12 ++++++++++++
 atk/atkobject.h    |    8 ++++++++
 atk/atkutil.c      |   20 ++++++++++++++++++++
 atk/atkutil.h      |    4 ++++
 7 files changed, 87 insertions(+), 3 deletions(-)
---
diff --git a/atk/atkcomponent.c b/atk/atkcomponent.c
index 46e80c8..3a6b1b4 100755
--- a/atk/atkcomponent.c
+++ b/atk/atkcomponent.c
@@ -104,7 +104,11 @@ atk_component_base_init (AtkComponentIface *class)
  * when this object receives focus events (in or out). If the handler is
  * already added it is not added again
  *
- * Returns: a handler id which can be used in atk_component_remove_focus_handler
+ * Deprecated: This method is deprecated since ATK version 2.9.4. If
+ * you need to track when an object gains or lose the focus, use
+ * state-changed:focused notification instead.
+ *
+ * Returns: a handler id which can be used in atk_component_remove_focus_handler()
  * or zero if the handler was already added.
  **/
 guint
@@ -131,6 +135,11 @@ atk_component_add_focus_handler (AtkComponent    *component,
  * Remove the handler specified by @handler_id from the list of
  * functions to be executed when this object receives focus events 
  * (in or out).
+ *
+ * Deprecated: This method is deprecated since ATK version 2.9.4. If
+ * you need to track when an object gains or lose the focus, use
+ * state-changed:focused notification instead.
+ *
  **/
 void
 atk_component_remove_focus_handler (AtkComponent    *component,
diff --git a/atk/atkcomponent.h b/atk/atkcomponent.h
index cf6dc9f..49b5202 100755
--- a/atk/atkcomponent.h
+++ b/atk/atkcomponent.h
@@ -47,7 +47,21 @@ typedef struct _AtkComponent AtkComponent;
 #endif
 typedef struct _AtkComponentIface  AtkComponentIface;
 
-typedef void (*AtkFocusHandler) (AtkObject*, gboolean);
+/**
+ * AtkFocusHandler:
+ * @object: the #AtkObject that receives/lose the focus
+ * @focus_in: TRUE if the object receives the focus
+ *
+ * The type of callback function used for
+ * atk_component_add_focus_handler() and
+ * atk_component_remove_focus_handler()
+ *
+ * Deprecated: This type is deprecated since ATK version 2.9.4. as
+ * atk_component_add_focus_handler() and
+ * atk_component_remove_focus_handler() are deprecated. See those
+ * methods for more information.
+ */
+typedef void (*AtkFocusHandler) (AtkObject* object, gboolean focus_in);
 
 typedef struct _AtkRectangle       AtkRectangle;
 
@@ -62,6 +76,17 @@ struct _AtkRectangle
 GType atk_rectangle_get_type (void);
 
 #define ATK_TYPE_RECTANGLE (atk_rectangle_get_type ())
+
+/**
+ * AtkComponentIface:
+ * @add_focus_handler: This virtual function is deprecated since 2.9.4
+ * and it should not be overriden. See
+ * atk_component_add_focus_handler() for more information.
+ * @remove_focus_handler: This virtual function is deprecated since
+ * 2.9.4 and it should not be overriden. See
+ * atk_component_remove_focus_handler() for more information.
+ */
+
 struct _AtkComponentIface
 {
   GTypeInterface parent;
@@ -122,7 +147,7 @@ struct _AtkComponentIface
 GType atk_component_get_type (void);
 
 /* convenience functions */
-
+G_DEPRECATED
 guint                atk_component_add_focus_handler      (AtkComponent    *component,
                                                            AtkFocusHandler handler);
 gboolean              atk_component_contains               (AtkComponent    *component,
@@ -149,6 +174,7 @@ void                  atk_component_get_size               (AtkComponent    *com
 AtkLayer              atk_component_get_layer              (AtkComponent    *component);
 gint                  atk_component_get_mdi_zorder         (AtkComponent    *component);
 gboolean              atk_component_grab_focus             (AtkComponent    *component);
+G_DEPRECATED
 void                  atk_component_remove_focus_handler   (AtkComponent    *component,
                                                             guint           handler_id);
 gboolean              atk_component_set_extents            (AtkComponent    *component,
diff --git a/atk/atkdocument.h b/atk/atkdocument.h
index 7f11eb4..874e89d 100755
--- a/atk/atkdocument.h
+++ b/atk/atkdocument.h
@@ -46,6 +46,11 @@ typedef struct _AtkDocument AtkDocument;
 #endif
 typedef struct _AtkDocumentIface AtkDocumentIface;
 
+/**
+ * AtkDocumentIface:
+ * @get_document_locale: gets locale. This virtual function is
+ * deprecated since 2.7.90 and it should not be overriden.
+ */
 struct _AtkDocumentIface
 {
   GTypeInterface parent;
diff --git a/atk/atkobject.c b/atk/atkobject.c
index 0e3b0b2..39afb03 100755
--- a/atk/atkobject.c
+++ b/atk/atkobject.c
@@ -555,6 +555,18 @@ atk_object_class_init (AtkObjectClass *klass)
                  g_cclosure_marshal_VOID__UINT_POINTER,
                  G_TYPE_NONE,
                  2, G_TYPE_UINT, G_TYPE_POINTER);
+
+  /**
+   * AtkObject::focus-event:
+   * @atkobject: the object which received the signal
+   * @arg1: a boolean value which indicates whether the object gained
+   * or lost focus.
+   *
+   * The signal "focus-event" is emitted when an object gained or lost
+   * focus.
+   *
+   * Deprecated: Since 2.9.4. Use #AtkObject::state-change signal instead.
+   */
   atk_object_signals[FOCUS_EVENT] =
     g_signal_new ("focus_event",
                  G_TYPE_FROM_CLASS (klass),
diff --git a/atk/atkobject.h b/atk/atkobject.h
index f50e77a..edb0508 100755
--- a/atk/atkobject.h
+++ b/atk/atkobject.h
@@ -400,6 +400,14 @@ struct _AtkObject
   AtkLayer layer;
 };
 
+
+/**
+ * AtkObjectClass:
+ * @focus_event: The signal handler which is executed when there is a
+ *   focus event for an object. This virtual function is deprecated
+ *   since 2.9.4 and it should not be overriden. Use
+ *   state-changed:focused signal instead.
+ */
 struct _AtkObjectClass
 {
   GObjectClass parent;
diff --git a/atk/atkutil.c b/atk/atkutil.c
index 924d0a0..e45d88f 100755
--- a/atk/atkutil.c
+++ b/atk/atkutil.c
@@ -87,6 +87,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 +108,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 +148,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 +185,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)
diff --git a/atk/atkutil.h b/atk/atkutil.h
index ce7e21d..420d83e 100755
--- a/atk/atkutil.h
+++ b/atk/atkutil.h
@@ -166,9 +166,13 @@ typedef enum {
   ATK_XY_WINDOW
 }AtkCoordType;
 
+G_DEPRECATED
 guint    atk_add_focus_tracker     (AtkEventListener      focus_tracker);
+G_DEPRECATED
 void     atk_remove_focus_tracker  (guint                tracker_id);
+G_DEPRECATED
 void     atk_focus_tracker_init    (AtkEventListenerInit  init);
+G_DEPRECATED
 void     atk_focus_tracker_notify  (AtkObject            *object);
 guint  atk_add_global_event_listener (GSignalEmissionHook listener,
                                       const gchar        *event_type);