Updated FSF's address
[platform/upstream/atk.git] / 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 }