2008-05-28 Mark Doffman <mark.doffman@codethink.co.uk>

[platform/core/uifw/at-spi2-atk.git] / idl / Accessibility_Image.idl

diff --git a/idl/Accessibility_Image.idl b/idl/Accessibility_Image.idl
index d819172..6cf50f8 100644 (file)
--- a/idl/Accessibility_Image.idl
+++ b/idl/Accessibility_Image.idl
@@ -2,7 +2,7 @@
  * AT-SPI - Assistive Technology Service Provider Interface 
  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
  *
- * Copyright 2001 Sun Microsystems, Inc.
+ * Copyright 2001 - 2005 Sun Microsystems, Inc.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
@@ -20,12 +20,91 @@
  * Boston, MA 02111-1307, USA.
  */
 
+#include "Accessibility_Accessible.idl"
+
 module Accessibility {
 
+  /** 
+   * An interface implemented by objects which render image data or 
+   * pictorial information to the screen.  When onscreen components include
+   * graphical information that is not purely intended to enhance "3d effect"
+   * or visual layout, but which conveys some semantic or informational 
+   * content to the sighted user, they should implement Image, and that 
+   * semantic content should be conveyed textually to the extent possible 
+   * via the image description, as well as the Accessible::name and 
+   * Accessible::description properties.  
+   */
   interface Image : Bonobo::Unknown  {
+    /**
+     * A UTF-8 string providing a textual description
+     * of what is visually depicted in the image.
+     *
+     * @note It is recommended that imageDescription be the shorter
+     * of the available image descriptions, for instance "alt text"
+     * in HTML images, and a longer description be provided in
+     * Accessible::accessible-description, if available.
+     * A short, one or two word label for the image should be provided in
+     * Accessible::accessible-name.
+     */
     readonly attribute string imageDescription;
+    /** 
+     * A string corresponding to the POSIX LC_MESSAGES locale used 
+     * by the imageDescription.
+     * @since AT-SPI 1.7.0
+     */
+    readonly attribute string imageLocale;
+    /**
+     * Obtain a bounding box which entirely contains the image contents,
+     * as displayed on screen.  The bounds returned do not account for
+     * any viewport clipping or the fact that the image may be
+     * partially or wholly obscured by other onscreen content.
+     * @note This method returns the bounds of the current onscreen
+     * view, and not the nominal size of the source data in the
+     * event that the original image has been rescaled.
+     *
+     * @param coordType If 0, the returned bounding box position is returned
+     * relative to the screen; if 1, the bounding box position is returned 
+     * relative to the containing window.
+     * @returns a BoundingBox enclosing the image's onscreen representation.
+     */
     BoundingBox getImageExtents (in short coordType);
+    /**
+     * Get the coordinates of the current image position on screen.
+     *
+     * @param x Back-filled with the x coordinate of the 
+     * onscreen image (i.e. the minimum x coordinate)
+     * @param y Back-filled with the y coordinate of the 
+     * onscreen image (i.e. the minimum y coordinate)
+     * @param coordType If 0, the returned x and y coordinates are 
+     * returned relative to the screen; 
+     * if 1, they are returned relative to the containing window.
+     */
     void getImagePosition (out long x, out long y, in short coordType);
+    /**
+     * Obtain the width and height of the current onscreen view of the
+     * image.  The extents returned do not account for
+     * any viewport clipping or the fact that the image may be
+     * partially or wholly obscured by other onscreen content.
+     * @note This method returns the size of the current onscreen
+     * view, and not the nominal or "original" size of the source 
+     * image, in the event that the original image has been rescaled.
+     *
+     * @param width Back-filled with the x extents of the 
+     * onscreen image (i.e. the image width in pixels)
+     * @param height Back-filled with the y extents of the 
+     * onscreen image (i.e. the image height in pixels)
+     */
     void getImageSize (out long width, out long height);
+
+    /**
+     * \cond
+     * unImplemented:
+     *
+     * placeholders for future expansion.
+     */
+    void unImplemented ();
+    void unImplemented2 ();
+    void unImplemented3 ();
+    /** \endcond */
   };
 };