Protect against NULL pointer dereference
[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, 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 }