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  * If the size can not be obtained (e.g. missing support), x and y are set
 102  * to -1.
 103  **/
 104 void
 105 atk_image_get_image_size (AtkImage *image,
 106                           int      *width,
 107                           int      *height)
 108 {
 109   AtkImageIface *iface;
 110   gint local_width, local_height;
 111   gint *real_width, *real_height;
 112
 113   g_return_if_fail (ATK_IS_IMAGE (image));
 114
 115   if (width)
 116     real_width = width;
 117   else
 118     real_width = &local_width;
 119   if (height)
 120     real_height = height;
 121   else
 122     real_height = &local_height;
 123
 124   iface = ATK_IMAGE_GET_IFACE (image);
 125
 126   if (iface->get_image_size)
 127   {
 128     iface->get_image_size (image, real_width, real_height);
 129   }
 130   else
 131   {
 132     *real_width = -1;
 133     *real_height = -1;
 134   }
 135 }
 136
 137 /**
 138  * atk_image_set_image_description:
 139  * @image: a #GObject instance that implements AtkImageIface
 140  * @description: a string description to set for @image
 141  *
 142  * Sets the textual description for this image.
 143  *
 144  * Returns: boolean TRUE, or FALSE if operation could
 145  * not be completed.
 146  **/
 147 gboolean
 148 atk_image_set_image_description (AtkImage        *image,
 149                                  const gchar     *description)
 150 {
 151   AtkImageIface *iface;
 152
 153   g_return_val_if_fail (ATK_IS_IMAGE (image), FALSE);
 154
 155   iface = ATK_IMAGE_GET_IFACE (image);
 156
 157   if (iface->set_image_description)
 158     {
 159       return (iface->set_image_description) (image, description);
 160     }
 161   else
 162     {
 163       return FALSE;
 164     }
 165 }
 166
 167 /**
 168  * atk_image_get_image_position:
 169  * @image: a #GObject instance that implements AtkImageIface
 170  * @x: (out) (optional): address of #gint to put x coordinate position; otherwise, -1 if value cannot be obtained.
 171  * @y: (out) (optional): address of #gint to put y coordinate position; otherwise, -1 if value cannot be obtained.
 172  * @coord_type: specifies whether the coordinates are relative to the screen
 173  * or to the components top level window
 174  *
 175  * Gets the position of the image in the form of a point specifying the
 176  * images top-left corner.
 177  *
 178  * If the position can not be obtained (e.g. missing support), x and y are set
 179  * to -1.
 180  **/
 181 void
 182 atk_image_get_image_position (AtkImage *image,
 183                         gint *x,
 184                         gint *y,
 185                         AtkCoordType coord_type)
 186 {
 187   AtkImageIface *iface;
 188   gint local_x, local_y;
 189   gint *real_x, *real_y;
 190
 191   g_return_if_fail (ATK_IS_IMAGE (image));
 192
 193   if (x)
 194     real_x = x;
 195   else
 196     real_x = &local_x;
 197   if (y)
 198     real_y = y;
 199   else
 200     real_y = &local_y;
 201
 202   iface = ATK_IMAGE_GET_IFACE (image);
 203
 204   if (iface->get_image_position)
 205   {
 206     (iface->get_image_position) (image, real_x, real_y, coord_type);
 207   }
 208   else
 209   {
 210     *real_x = -1;
 211     *real_y = -1;
 212   }
 213 }
 214
 215 /**
 216  * atk_image_get_image_locale:
 217  * @image: An #AtkImage
 218  *
 219  * Retrieves the locale identifier associated to the #AtkImage.
 220  *
 221  * Since: 1.12
 222  *
 223  * Returns: (nullable): a string corresponding to the POSIX
 224  *   `LC_MESSAGES` locale used by the image description, or
 225  *   %NULL if the image does not specify a locale.
 226  *
 227  */
 228 const gchar*
 229 atk_image_get_image_locale (AtkImage   *image)
 230 {
 231
 232   AtkImageIface *iface;
 233
 234   g_return_val_if_fail (ATK_IS_IMAGE (image), NULL);
 235
 236   iface = ATK_IMAGE_GET_IFACE (image);
 237
 238   if (iface->get_image_locale)
 239     {
 240       return (iface->get_image_locale) (image);
 241     }
 242   else
 243     {
 244       return NULL;
 245     }
 246 }