atkimage.c 6.24 KB
Newer Older
Bill Haneman's avatar
Bill Haneman committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
/* ATK -  Accessibility Toolkit
 * Copyright 2001 Sun Microsystems Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
Piotr Drąg's avatar
Piotr Drąg committed
15
16
17
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
Bill Haneman's avatar
Bill Haneman committed
18
19
 */

20
21
#include "config.h"

Bill Haneman's avatar
Bill Haneman committed
22
23
#include "atkimage.h"

24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
/**
 * SECTION:atkimage
 * @Short_description: The ATK Interface implemented by components
 *  which expose image or pixmap content on-screen.
 * @Title:AtkImage
 *
 * #AtkImage should be implemented by #AtkObject subtypes on behalf of
 * components which display image/pixmap information onscreen, and
 * which provide information (other than just widget borders, etc.)
 * via that image content.  For instance, icons, buttons with icons,
 * toolbar elements, and image viewing panes typically should
 * implement #AtkImage.
 *
 * #AtkImage primarily provides two types of information: coordinate
 * information (useful for screen review mode of screenreaders, and
 * for use by onscreen magnifiers), and descriptive information.  The
 * descriptive information is provided for alternative, text-only
 * presentation of the most significant information present in the
 * image.
 */

Bill Haneman's avatar
Bill Haneman committed
45
GType
46
atk_image_get_type (void)
Bill Haneman's avatar
Bill Haneman committed
47
48
49
50
51
52
53
{
  static GType type = 0;

  if (!type) {
    static const GTypeInfo tinfo =
    {
      sizeof (AtkImageIface),
54
      (GBaseInitFunc) NULL,
55
      (GBaseFinalizeFunc) NULL
Bill Haneman's avatar
Bill Haneman committed
56
57
58
59
60
61
62
63
64
65
    };

    type = g_type_register_static (G_TYPE_INTERFACE, "AtkImage", &tinfo, 0);
  }

  return type;
}

/**
 * atk_image_get_image_description:
66
 * @image: a #GObject instance that implements AtkImageIface
Bill Haneman's avatar
Bill Haneman committed
67
 *
Bill Haneman's avatar
Bill Haneman committed
68
 * Get a textual description of this image.
Brian Cameron's avatar
Brian Cameron committed
69
 *
70
 * Returns: a string representing the image description
Bill Haneman's avatar
Bill Haneman committed
71
 **/
72
const gchar*
Brian Cameron's avatar
Brian Cameron committed
73
atk_image_get_image_description (AtkImage *image)
Bill Haneman's avatar
Bill Haneman committed
74
75
76
{
  AtkImageIface *iface;

Brian Cameron's avatar
Brian Cameron committed
77
  g_return_val_if_fail (ATK_IS_IMAGE (image), NULL);
Bill Haneman's avatar
Bill Haneman committed
78

Brian Cameron's avatar
Brian Cameron committed
79
  iface = ATK_IMAGE_GET_IFACE (image);
Bill Haneman's avatar
Bill Haneman committed
80
81

  if (iface->get_image_description)
Bill Haneman's avatar
Bill Haneman committed
82
    {
Brian Cameron's avatar
Brian Cameron committed
83
      return (iface->get_image_description) (image);
Bill Haneman's avatar
Bill Haneman committed
84
    }
Bill Haneman's avatar
Bill Haneman committed
85
  else
Bill Haneman's avatar
Bill Haneman committed
86
87
88
    {
      return NULL;
    }
Bill Haneman's avatar
Bill Haneman committed
89
90
91
}

/**
92
 * atk_image_get_image_size:
93
 * @image: a #GObject instance that implements AtkImageIface
94
95
 * @width: (out) (optional): filled with the image width, or -1 if the value cannot be obtained.
 * @height: (out) (optional): filled with the image height, or -1 if the value cannot be obtained.
Bill Haneman's avatar
Bill Haneman committed
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
102
 *
 * If the size can not be obtained (e.g. missing support), x and y are set
 * to -1.
Bill Haneman's avatar
Bill Haneman committed
103
 **/
104
void
105
106
107
atk_image_get_image_size (AtkImage *image, 
                          int      *width,
                          int      *height)
Bill Haneman's avatar
Bill Haneman committed
108
109
{
  AtkImageIface *iface;
110
111
  gint local_width, local_height;
  gint *real_width, *real_height;
Bill Haneman's avatar
Bill Haneman committed
112

Brian Cameron's avatar
Brian Cameron committed
113
  g_return_if_fail (ATK_IS_IMAGE (image));
Bill Haneman's avatar
Bill Haneman committed
114

115
116
117
118
119
120
121
122
123
  if (width)
    real_width = width;
  else
    real_width = &local_width;
  if (height)
    real_height = height;
  else
    real_height = &local_height;
  
Brian Cameron's avatar
Brian Cameron committed
124
  iface = ATK_IMAGE_GET_IFACE (image);
Bill Haneman's avatar
Bill Haneman committed
125

126
  if (iface->get_image_size)
127
  {
128
    iface->get_image_size (image, real_width, real_height);
129
130
131
  }
  else
  {
132
133
    *real_width = -1;
    *real_height = -1;
134
  }
Bill Haneman's avatar
Bill Haneman committed
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
Bill Haneman's avatar
Bill Haneman committed
141
142
143
 *
 * Sets the textual description for this image.
 *
Brian Cameron's avatar
Brian Cameron committed
144
145
 * Returns: boolean TRUE, or FALSE if operation could
 * not be completed.
Bill Haneman's avatar
Bill Haneman committed
146
 **/
Bill Haneman's avatar
Bill Haneman committed
147
gboolean
Brian Cameron's avatar
Brian Cameron committed
148
atk_image_set_image_description (AtkImage        *image,
149
                                 const gchar     *description)
Bill Haneman's avatar
Bill Haneman committed
150
151
152
{
  AtkImageIface *iface;

Brian Cameron's avatar
Brian Cameron committed
153
  g_return_val_if_fail (ATK_IS_IMAGE (image), FALSE);
Bill Haneman's avatar
Bill Haneman committed
154

Brian Cameron's avatar
Brian Cameron committed
155
  iface = ATK_IMAGE_GET_IFACE (image);
Bill Haneman's avatar
Bill Haneman committed
156
157

  if (iface->set_image_description)
Bill Haneman's avatar
Bill Haneman committed
158
    {
Brian Cameron's avatar
Brian Cameron committed
159
      return (iface->set_image_description) (image, description);
Bill Haneman's avatar
Bill Haneman committed
160
161
162
163
164
    }
  else
    {
      return FALSE;
    }
Bill Haneman's avatar
Bill Haneman committed
165
}
166
167

/**
168
 * atk_image_get_image_position:
169
 * @image: a #GObject instance that implements AtkImageIface
170
171
 * @x: (out) (optional): address of #gint to put x coordinate position; otherwise, -1 if value cannot be obtained.
 * @y: (out) (optional): address of #gint to put y coordinate position; otherwise, -1 if value cannot be obtained.
172
173
174
175
 * @coord_type: specifies whether the coordinates are relative to the screen
 * or to the components top level window
 * 
 * Gets the position of the image in the form of a point specifying the
176
 * images top-left corner.
177
178
179
 *
 * If the position can not be obtained (e.g. missing support), x and y are set
 * to -1.
180
181
 **/
void     
182
atk_image_get_image_position (AtkImage *image,
183
184
185
186
187
                        gint *x,
		        gint *y,
    		        AtkCoordType coord_type)
{
  AtkImageIface *iface;
188
189
190
191
192
193
194
195
196
197
198
199
200
  gint local_x, local_y;
  gint *real_x, *real_y;

  g_return_if_fail (ATK_IS_IMAGE (image));

  if (x)
    real_x = x;
  else
    real_x = &local_x;
  if (y)
    real_y = y;
  else
    real_y = &local_y;
201
202
203

  iface = ATK_IMAGE_GET_IFACE (image);

204
205
  if (iface->get_image_position)
  {
206
    (iface->get_image_position) (image, real_x, real_y, coord_type);
207
208
209
  }
  else
  {
210
211
    *real_x = -1;
    *real_y = -1;
212
  }
213
}
214

215
216
/**
 * atk_image_get_image_locale: 
217
 * @image: An #AtkImage
218
 *
219
220
 * Retrieves the locale identifier associated to the #AtkImage.
 *
221
 * Since: 1.12
222
 *
223
 * Returns: (nullable): a string corresponding to the POSIX
224
225
 *   `LC_MESSAGES` locale used by the image description, or
 *   %NULL if the image does not specify a locale.
226
 *
227
 */
228
const gchar*
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
atk_image_get_image_locale (AtkImage   *image)
{
	
  AtkImageIface *iface;

  g_return_val_if_fail (ATK_IS_IMAGE (image), NULL);

  iface = ATK_IMAGE_GET_IFACE (image);

  if (iface->get_image_locale)
    {
      return (iface->get_image_locale) (image);
    }
  else
    {
      return NULL;
    }
}