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