/* 
 * AT-SPI - Assistive Technology Service Provider Interface 
 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
 *
 * 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
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * 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 */
  };
};