1 /* ATK - Accessibility Toolkit
2 * Copyright 2001 Sun Microsystems Inc.
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.
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.
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.
26 * @Short_description: The ATK Interface implemented by components
27 * which expose image or pixmap content on-screen.
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.
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
46 atk_image_get_type (void)
48 static GType type = 0;
51 static const GTypeInfo tinfo =
53 sizeof (AtkImageIface),
55 (GBaseFinalizeFunc) NULL
58 type = g_type_register_static (G_TYPE_INTERFACE, "AtkImage", &tinfo, 0);
65 * atk_image_get_image_description:
66 * @image: a #GObject instance that implements AtkImageIface
68 * Get a textual description of this image.
70 * Returns: a string representing the image description
73 atk_image_get_image_description (AtkImage *image)
77 g_return_val_if_fail (ATK_IS_IMAGE (image), NULL);
79 iface = ATK_IMAGE_GET_IFACE (image);
81 if (iface->get_image_description)
83 return (iface->get_image_description) (image);
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.
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).
101 * If the size can not be obtained (e.g. missing support), x and y are set
105 atk_image_get_image_size (AtkImage *image,
109 AtkImageIface *iface;
110 gint local_width, local_height;
111 gint *real_width, *real_height;
113 g_return_if_fail (ATK_IS_IMAGE (image));
118 real_width = &local_width;
120 real_height = height;
122 real_height = &local_height;
124 iface = ATK_IMAGE_GET_IFACE (image);
126 if (iface->get_image_size)
128 iface->get_image_size (image, real_width, real_height);
138 * atk_image_set_image_description:
139 * @image: a #GObject instance that implements AtkImageIface
140 * @description: a string description to set for @image
142 * Sets the textual description for this image.
144 * Returns: boolean TRUE, or FALSE if operation could
148 atk_image_set_image_description (AtkImage *image,
149 const gchar *description)
151 AtkImageIface *iface;
153 g_return_val_if_fail (ATK_IS_IMAGE (image), FALSE);
155 iface = ATK_IMAGE_GET_IFACE (image);
157 if (iface->set_image_description)
159 return (iface->set_image_description) (image, description);
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
175 * Gets the position of the image in the form of a point specifying the
176 * images top-left corner.
178 * If the position can not be obtained (e.g. missing support), x and y are set
182 atk_image_get_image_position (AtkImage *image,
185 AtkCoordType coord_type)
187 AtkImageIface *iface;
188 gint local_x, local_y;
189 gint *real_x, *real_y;
191 g_return_if_fail (ATK_IS_IMAGE (image));
202 iface = ATK_IMAGE_GET_IFACE (image);
204 if (iface->get_image_position)
206 (iface->get_image_position) (image, real_x, real_y, coord_type);
216 * atk_image_get_image_locale:
217 * @image: An #AtkImage
219 * Retrieves the locale identifier associated to the #AtkImage.
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.
229 atk_image_get_image_locale (AtkImage *image)
232 AtkImageIface *iface;
234 g_return_val_if_fail (ATK_IS_IMAGE (image), NULL);
236 iface = ATK_IMAGE_GET_IFACE (image);
238 if (iface->get_image_locale)
240 return (iface->get_image_locale) (image);