Revert "Revert "Merge remote-tracking branch 'origin/sandbox/mniesluchow/upstream_2_1...

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

diff --git a/atk/atkimage.c b/atk/atkimage.c
index 1f69fbc..2ba5909 100755 (executable)
--- a/atk/atkimage.c
+++ b/atk/atkimage.c
@@ -17,8 +17,31 @@
  * Boston, MA 02111-1307, USA.
  */
 
+#include "config.h"
+
 #include "atkimage.h"
 
+/**
+ * SECTION:atkimage
+ * @Short_description: The ATK Interface implemented by components
+ *  which expose image or pixmap content on-screen.
+ * @Title:AtkImage
+ *
+ * #AtkImage should be implemented by #AtkObject subtypes on behalf of
+ * components which display image/pixmap information onscreen, and
+ * which provide information (other than just widget borders, etc.)
+ * via that image content.  For instance, icons, buttons with icons,
+ * toolbar elements, and image viewing panes typically should
+ * implement #AtkImage.
+ *
+ * #AtkImage primarily provides two types of information: coordinate
+ * information (useful for screen review mode of screenreaders, and
+ * for use by onscreen magnifiers), and descriptive information.  The
+ * descriptive information is provided for alternative, text-only
+ * presentation of the most significant information present in the
+ * image.
+ */
+
 GType
 atk_image_get_type (void)
 {
@@ -46,7 +69,7 @@ atk_image_get_type (void)
  *
  * Returns: a string representing the image description
  **/
-G_CONST_RETURN gchar*
+const gchar*
 atk_image_get_image_description (AtkImage *image)
 {
   AtkImageIface *iface;
@@ -68,12 +91,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, 
@@ -169,10 +192,6 @@ atk_image_get_image_position (AtkImage *image,
     real_y = y;
   else
     real_y = &local_y;
-  
-  iface = ATK_IMAGE_GET_IFACE (image);
-
-  g_return_if_fail (ATK_IS_IMAGE (image));
 
   iface = ATK_IMAGE_GET_IFACE (image);
 
@@ -187,11 +206,18 @@ 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. 
- * @Since ATK 1.12
+/**
+ * atk_image_get_image_locale: 
+ * @image: An #AtkImage
+ *
+ * Since: 1.12
+ *
+ * Returns: (nullable): a string corresponding to the POSIX
+ * LC_MESSAGES locale used by the image description, or %NULL if the
+ * image does not specify a locale.
+ *
  */
-G_CONST_RETURN gchar* 
+const gchar*
 atk_image_get_image_locale (AtkImage   *image)
 {