[atk] atkobject: add atk_object_peek_parent

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

commit 82a1f6f8090e385ad9c61a6b4f83ca5ba9c97fd1
Author: Alejandro Piñeiro <apinheiro igalia com>
Date:   Mon Dec 9 11:28:51 2013 +0100

    atkobject: add atk_object_peek_parent
    
    https://bugzilla.gnome.org/show_bug.cgi?id=720095

 atk/atkobject.c       |   40 ++++++++++++++++++++++++++++++++++------
 atk/atkobject.h       |    1 +
 docs/atk-sections.txt |    1 +
 3 files changed, 36 insertions(+), 6 deletions(-)
---
diff --git a/atk/atkobject.c b/atk/atkobject.c
index e05eafa..a724fe5 100755
--- a/atk/atkobject.c
+++ b/atk/atkobject.c
@@ -482,7 +482,7 @@ atk_object_class_init (AtkObjectClass *klass)
                                    PROP_PARENT,
                                    g_param_spec_object (atk_object_name_property_parent,
                                                         _("Accessible Parent"),
-                                                        _("Is used to notify that the parent has changed"),
+                                                        _("Parent of the current accessible as returned by 
atk_object_get_parent()"),
                                                         ATK_TYPE_OBJECT,
                                                         G_PARAM_READWRITE));
   g_object_class_install_property (gobject_class,
@@ -783,10 +783,17 @@ atk_object_get_description (AtkObject *accessible)
  * atk_object_get_parent:
  * @accessible: an #AtkObject
  *
- * Gets the accessible parent of the accessible.
+ * Gets the accessible parent of the accessible. By default this is
+ * the one assigned with atk_object_set_parent(), but it is assumed
+ * that ATK implementors have ways to get the parent of the object
+ * without the need of assigning it manually with
+ * atk_object_set_parent(), and will return it with this method.
  *
- * Returns: (transfer none): a #AtkObject representing the accessible parent
- * of the accessible
+ * If you are only interested on the parent assigned with
+ * atk_object_set_parent(), use atk_object_peek_parent().
+ *
+ * Returns: (transfer none): an #AtkObject representing the accessible
+ * parent of the accessible
  **/
 AtkObject*
 atk_object_get_parent (AtkObject *accessible)
@@ -803,6 +810,27 @@ atk_object_get_parent (AtkObject *accessible)
 }
 
 /**
+ * atk_object_peek_parent:
+ * @accessible: an #AtkObject
+ *
+ * Gets the accessible parent of the accessible, if it has been
+ * manually assigned with atk_object_set_parent. Otherwise, this
+ * function returns %NULL.
+ *
+ * This method is intended as an utility for ATK implementors, and not
+ * to be exposed to accessible tools. See atk_object_get_parent() for
+ * further reference.
+ *
+ * Returns: (transfer none): an #AtkObject representing the accessible
+ * parent of the accessible if assigned
+ **/
+AtkObject*
+atk_object_peek_parent (AtkObject *accessible)
+{
+  return accessible->accessible_parent;
+}
+
+/**
  * atk_object_get_n_accessible_children:
  * @accessible: an #AtkObject
  *
@@ -1084,7 +1112,7 @@ atk_object_set_description (AtkObject   *accessible,
  * @accessible: an #AtkObject
  * @parent: an #AtkObject to be set as the accessible parent
  *
- * Sets the accessible parent of the accessible.
+ * Sets the accessible parent of the accessible. @parent can be NULL.
  **/
 void
 atk_object_set_parent (AtkObject *accessible,
@@ -1406,7 +1434,7 @@ atk_object_real_get_description (AtkObject *object)
 static AtkObject*
 atk_object_real_get_parent (AtkObject       *object)
 {
-  return object->accessible_parent;
+  return atk_object_peek_parent (object);
 }
 
 static AtkRole
diff --git a/atk/atkobject.h b/atk/atkobject.h
index 712060d..404b505 100755
--- a/atk/atkobject.h
+++ b/atk/atkobject.h
@@ -645,6 +645,7 @@ AtkObject*              atk_implementor_ref_accessible            (AtkImplemento
 const gchar*            atk_object_get_name                       (AtkObject *accessible);
 const gchar*            atk_object_get_description                (AtkObject *accessible);
 AtkObject*              atk_object_get_parent                     (AtkObject *accessible);
+AtkObject*              atk_object_peek_parent                    (AtkObject *accessible);
 gint                    atk_object_get_n_accessible_children      (AtkObject *accessible);
 AtkObject*              atk_object_ref_accessible_child           (AtkObject *accessible,
                                                                    gint        i);
diff --git a/docs/atk-sections.txt b/docs/atk-sections.txt
index 881ad60..e4b9c41 100644
--- a/docs/atk-sections.txt
+++ b/docs/atk-sections.txt
@@ -171,6 +171,7 @@ atk_implementor_ref_accessible
 atk_object_get_name
 atk_object_get_description
 atk_object_get_parent
+atk_object_peek_parent
 atk_object_get_n_accessible_children
 atk_object_ref_accessible_child
 atk_object_ref_relation_set