idl/Accessibility_Image.idl

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2001 - 2005 Sun Microsystems, Inc.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #include "Accessibility_Accessible.idl"
  24
  25 module Accessibility {
  26
  27   /**
  28    * An interface implemented by objects which render image data or
  29    * pictorial information to the screen.  When onscreen components include
  30    * graphical information that is not purely intended to enhance "3d effect"
  31    * or visual layout, but which conveys some semantic or informational
  32    * content to the sighted user, they should implement Image, and that
  33    * semantic content should be conveyed textually to the extent possible
  34    * via the image description, as well as the Accessible::name and
  35    * Accessible::description properties.
  36    */
  37   interface Image : Bonobo::Unknown  {
  38     /**
  39      * A UTF-8 string providing a textual description
  40      * of what is visually depicted in the image.
  41      *
  42      * @note It is recommended that imageDescription be the shorter
  43      * of the available image descriptions, for instance "alt text"
  44      * in HTML images, and a longer description be provided in
  45      * Accessible::accessible-description, if available.
  46      * A short, one or two word label for the image should be provided in
  47      * Accessible::accessible-name.
  48      */
  49     readonly attribute string imageDescription;
  50     /**
  51      * A string corresponding to the POSIX LC_MESSAGES locale used
  52      * by the imageDescription.
  53      * @since AT-SPI 1.7.0
  54      */
  55     readonly attribute string imageLocale;
  56     /**
  57      * Obtain a bounding box which entirely contains the image contents,
  58      * as displayed on screen.  The bounds returned do not account for
  59      * any viewport clipping or the fact that the image may be
  60      * partially or wholly obscured by other onscreen content.
  61      * @note This method returns the bounds of the current onscreen
  62      * view, and not the nominal size of the source data in the
  63      * event that the original image has been rescaled.
  64      *
  65      * @param coordType If 0, the returned bounding box position is returned
  66      * relative to the screen; if 1, the bounding box position is returned
  67      * relative to the containing window.
  68      * @returns a BoundingBox enclosing the image's onscreen representation.
  69      */
  70     BoundingBox getImageExtents (in short coordType);
  71     /**
  72      * Get the coordinates of the current image position on screen.
  73      *
  74      * @param x Back-filled with the x coordinate of the
  75      * onscreen image (i.e. the minimum x coordinate)
  76      * @param y Back-filled with the y coordinate of the
  77      * onscreen image (i.e. the minimum y coordinate)
  78      * @param coordType If 0, the returned x and y coordinates are
  79      * returned relative to the screen;
  80      * if 1, they are returned relative to the containing window.
  81      */
  82     void getImagePosition (out long x, out long y, in short coordType);
  83     /**
  84      * Obtain the width and height of the current onscreen view of the
  85      * image.  The extents returned do not account for
  86      * any viewport clipping or the fact that the image may be
  87      * partially or wholly obscured by other onscreen content.
  88      * @note This method returns the size of the current onscreen
  89      * view, and not the nominal or "original" size of the source
  90      * image, in the event that the original image has been rescaled.
  91      *
  92      * @param width Back-filled with the x extents of the
  93      * onscreen image (i.e. the image width in pixels)
  94      * @param height Back-filled with the y extents of the
  95      * onscreen image (i.e. the image height in pixels)
  96      */
  97     void getImageSize (out long width, out long height);
  98
  99     /**
 100      * \cond
 101      * unImplemented:
 102      *
 103      * placeholders for future expansion.
 104      */
 105     void unImplemented ();
 106     void unImplemented2 ();
 107     void unImplemented3 ();
 108     /** \endcond */
 109   };
 110 };