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
 * AtkImage:
26
 *
27
 * The ATK Interface implemented by components
28
 *  which expose image or pixmap content on-screen.
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
1731
atk_image_get_type (void)
47
{
48
  static GType type = 0;
49

            
50
1731
  if (!type)
51
    {
52
      static const GTypeInfo tinfo = {
53
        sizeof (AtkImageIface),
54
        (GBaseInitFunc) NULL,
55
        (GBaseFinalizeFunc) NULL
56
      };
57

            
58
161
      type = g_type_register_static (G_TYPE_INTERFACE, "AtkImage", &tinfo, 0);
59
    }
60

            
61
1731
  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
1
atk_image_get_image_description (AtkImage *image)
74
{
75
  AtkImageIface *iface;
76

            
77
1
  g_return_val_if_fail (ATK_IS_IMAGE (image), NULL);
78

            
79
1
  iface = ATK_IMAGE_GET_IFACE (image);
80

            
81
1
  if (iface->get_image_description)
82
    {
83
1
      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
2
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
2
  g_return_if_fail (ATK_IS_IMAGE (image));
114

            
115
2
  if (width)
116
2
    real_width = width;
117
  else
118
    real_width = &local_width;
119
2
  if (height)
120
2
    real_height = height;
121
  else
122
    real_height = &local_height;
123

            
124
2
  iface = ATK_IMAGE_GET_IFACE (image);
125

            
126
2
  if (iface->get_image_size)
127
    {
128
2
      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
2
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
2
  g_return_if_fail (ATK_IS_IMAGE (image));
192

            
193
2
  if (x)
194
2
    real_x = x;
195
  else
196
    real_x = &local_x;
197
2
  if (y)
198
2
    real_y = y;
199
  else
200
    real_y = &local_y;
201

            
202
2
  iface = ATK_IMAGE_GET_IFACE (image);
203

            
204
2
  if (iface->get_image_position)
205
    {
206
2
      (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
1
atk_image_get_image_locale (AtkImage *image)
230
{
231

            
232
  AtkImageIface *iface;
233

            
234
1
  g_return_val_if_fail (ATK_IS_IMAGE (image), NULL);
235

            
236
1
  iface = ATK_IMAGE_GET_IFACE (image);
237

            
238
1
  if (iface->get_image_locale)
239
    {
240
1
      return (iface->get_image_locale) (image);
241
    }
242
  else
243
    {
244
      return NULL;
245
    }
246
}