atk/atkimage.c

   1 /* ATK -  Accessibility Toolkit
   2  * Copyright 2001 Sun Microsystems Inc.
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 #include "atkimage.h"
  21
  22 /**
  23  * SECTION:atkimage
  24  * @Short_description: The ATK Interface implemented by components
  25  *  which expose image or pixmap content on-screen.
  26  * @Title:AtkImage
  27  *
  28  * #AtkImage should be implemented by #AtkObject subtypes on behalf of
  29  * components which display image/pixmap information onscreen, and
  30  * which provide information (other than just widget borders, etc.)
  31  * via that image content.  For instance, icons, buttons with icons,
  32  * toolbar elements, and image viewing panes typically should
  33  * implement #AtkImage.
  34  *
  35  * #AtkImage primarily provides two types of information: coordinate
  36  * information (useful for screen review mode of screenreaders, and
  37  * for use by onscreen magnifiers), and descriptive information.  The
  38  * descriptive information is provided for alternative, text-only
  39  * presentation of the most significant information present in the
  40  * image.
  41  */
  42
  43 GType
  44 atk_image_get_type (void)
  45 {
  46   static GType type = 0;
  47
  48   if (!type) {
  49     static const GTypeInfo tinfo =
  50     {
  51       sizeof (AtkImageIface),
  52       (GBaseInitFunc) NULL,
  53       (GBaseFinalizeFunc) NULL
  54     };
  55
  56     type = g_type_register_static (G_TYPE_INTERFACE, "AtkImage", &tinfo, 0);
  57   }
  58
  59   return type;
  60 }
  61
  62 /**
  63  * atk_image_get_image_description:
  64  * @image: a #GObject instance that implements AtkImageIface
  65  *
  66  * Get a textual description of this image.
  67  *
  68  * Returns: a string representing the image description
  69  **/
  70 const gchar*
  71 atk_image_get_image_description (AtkImage *image)
  72 {
  73   AtkImageIface *iface;
  74
  75   g_return_val_if_fail (ATK_IS_IMAGE (image), NULL);
  76
  77   iface = ATK_IMAGE_GET_IFACE (image);
  78
  79   if (iface->get_image_description)
  80     {
  81       return (iface->get_image_description) (image);
  82     }
  83   else
  84     {
  85       return NULL;
  86     }
  87 }
  88
  89 /**
  90  * atk_image_get_image_size:
  91  * @image: a #GObject instance that implements AtkImageIface
  92  * @width: filled with the image width, or -1 if the value cannot be obtained.
  93  * @height: filled with the image height, or -1 if the value cannot be obtained.
  94  *
  95  * Get the width and height in pixels for the specified image.
  96  * The values of @width and @height are returned as -1 if the
  97  * values cannot be obtained (for instance, if the object is not onscreen).
  98  **/
  99 void
 100 atk_image_get_image_size (AtkImage *image,
 101                           int      *width,
 102                           int      *height)
 103 {
 104   AtkImageIface *iface;
 105   gint local_width, local_height;
 106   gint *real_width, *real_height;
 107
 108   g_return_if_fail (ATK_IS_IMAGE (image));
 109
 110   if (width)
 111     real_width = width;
 112   else
 113     real_width = &local_width;
 114   if (height)
 115     real_height = height;
 116   else
 117     real_height = &local_height;
 118
 119   iface = ATK_IMAGE_GET_IFACE (image);
 120
 121   if (iface->get_image_size)
 122   {
 123     iface->get_image_size (image, real_width, real_height);
 124   }
 125   else
 126   {
 127     *real_width = -1;
 128     *real_height = -1;
 129   }
 130 }
 131
 132 /**
 133  * atk_image_set_image_description:
 134  * @image: a #GObject instance that implements AtkImageIface
 135  * @description: a string description to set for @image
 136  *
 137  * Sets the textual description for this image.
 138  *
 139  * Returns: boolean TRUE, or FALSE if operation could
 140  * not be completed.
 141  **/
 142 gboolean
 143 atk_image_set_image_description (AtkImage        *image,
 144                                  const gchar     *description)
 145 {
 146   AtkImageIface *iface;
 147
 148   g_return_val_if_fail (ATK_IS_IMAGE (image), FALSE);
 149
 150   iface = ATK_IMAGE_GET_IFACE (image);
 151
 152   if (iface->set_image_description)
 153     {
 154       return (iface->set_image_description) (image, description);
 155     }
 156   else
 157     {
 158       return FALSE;
 159     }
 160 }
 161
 162 /**
 163  * atk_image_get_image_position:
 164  * @image: a #GObject instance that implements AtkImageIface
 165  * @x: address of #gint to put x coordinate position; otherwise, -1 if value cannot be obtained.
 166  * @y: address of #gint to put y coordinate position; otherwise, -1 if value cannot be obtained.
 167  * @coord_type: specifies whether the coordinates are relative to the screen
 168  * or to the components top level window
 169  *
 170  * Gets the position of the image in the form of a point specifying the
 171  * images top-left corner.
 172  **/
 173 void
 174 atk_image_get_image_position (AtkImage *image,
 175                         gint *x,
 176                         gint *y,
 177                         AtkCoordType coord_type)
 178 {
 179   AtkImageIface *iface;
 180   gint local_x, local_y;
 181   gint *real_x, *real_y;
 182
 183   g_return_if_fail (ATK_IS_IMAGE (image));
 184
 185   if (x)
 186     real_x = x;
 187   else
 188     real_x = &local_x;
 189   if (y)
 190     real_y = y;
 191   else
 192     real_y = &local_y;
 193
 194   iface = ATK_IMAGE_GET_IFACE (image);
 195
 196   if (iface->get_image_position)
 197   {
 198     (iface->get_image_position) (image, real_x, real_y, coord_type);
 199   }
 200   else
 201   {
 202     *real_x = -1;
 203     *real_y = -1;
 204   }
 205 }
 206
 207 /**
 208  * atk_image_get_image_locale:
 209  * @image: An #AtkImage
 210  *
 211  * Since ATK 1.12
 212  *
 213  * Returns: a string corresponding to the POSIX LC_MESSAGES locale
 214  * used by the image description, or NULL if the image does not
 215  * specify a locale.
 216  *
 217  */
 218 const gchar*
 219 atk_image_get_image_locale (AtkImage   *image)
 220 {
 221
 222   AtkImageIface *iface;
 223
 224   g_return_val_if_fail (ATK_IS_IMAGE (image), NULL);
 225
 226   iface = ATK_IMAGE_GET_IFACE (image);
 227
 228   if (iface->get_image_locale)
 229     {
 230       return (iface->get_image_locale) (image);
 231     }
 232   else
 233     {
 234       return NULL;
 235     }
 236 }