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