docs: improve documentation for AtkObject::children-changed signal
[platform/upstream/atk.git] / atk / atkvalue.c
1 /* ATK -  Accessibility Toolkit
2  * Copyright 2001, 2002, 2003 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 <string.h>
21 #include "atkvalue.h"
22
23 /**
24  * SECTION:atkvalue
25  * @Short_description: The ATK interface implemented by valuators and
26  *  components which display or select a value from a bounded range of
27  *  values.
28  * @Title:AtkValue
29  *
30  * #AtkValue should be implemented for components which either display
31  * a value from a bounded range, or which allow the user to specify a
32  * value from a bounded range, or both.  For instance, most sliders
33  * and range controls, as well as dials, should have #AtkObject
34  * representations which implement #AtkValue on the component's
35  * behalf.  #AtKValues may be read-only, in which case attempts to
36  * alter the value return FALSE to indicate failure.
37  */
38
39 GType
40 atk_value_get_type (void)
41 {
42   static GType type = 0;
43
44   if (!type) {
45     GTypeInfo tinfo =
46     {
47       sizeof (AtkValueIface),
48       (GBaseInitFunc) NULL,
49       (GBaseFinalizeFunc) NULL,
50
51     };
52
53     type = g_type_register_static (G_TYPE_INTERFACE, "AtkValue", &tinfo, 0);
54   }
55
56   return type;
57 }
58
59 /**
60  * atk_value_get_current_value:
61  * @obj: a GObject instance that implements AtkValueIface
62  * @value: a #GValue representing the current accessible value
63  *
64  * Gets the value of this object.
65  **/
66 void
67 atk_value_get_current_value (AtkValue *obj,
68                              GValue   *value)
69 {
70   AtkValueIface *iface;
71
72   g_return_if_fail (value != NULL);
73   g_return_if_fail (ATK_IS_VALUE (obj));
74
75   iface = ATK_VALUE_GET_IFACE (obj);
76
77   if (iface->get_current_value)
78     {
79       if (G_IS_VALUE (value))
80         g_value_unset (value);
81       else
82         memset (value, 0, sizeof (*value));
83
84       (iface->get_current_value) (obj, value);
85     }
86 }
87
88 /**
89  * atk_value_get_maximum_value:
90  * @obj: a GObject instance that implements AtkValueIface
91  * @value: a #GValue representing the maximum accessible value
92  *
93  * Gets the maximum value of this object.
94  **/
95 void
96 atk_value_get_maximum_value  (AtkValue *obj,
97                               GValue   *value)
98 {
99   AtkValueIface *iface;
100
101   g_return_if_fail (value != NULL);
102   g_return_if_fail (ATK_IS_VALUE (obj));
103
104   iface = ATK_VALUE_GET_IFACE (obj);
105
106   if (iface->get_maximum_value)
107     {
108       if (G_IS_VALUE (value))
109         g_value_unset (value);
110       else
111         memset (value, 0, sizeof (*value));
112
113       (iface->get_maximum_value) (obj, value);
114     }
115 }
116
117 /**
118  * atk_value_get_minimum_value:
119  * @obj: a GObject instance that implements AtkValueIface
120  * @value: a #GValue representing the minimum accessible value
121  *
122  * Gets the minimum value of this object.
123  **/
124 void
125 atk_value_get_minimum_value (AtkValue *obj,
126                              GValue   *value)
127 {
128   AtkValueIface *iface;
129
130   g_return_if_fail (value != NULL);
131   g_return_if_fail (ATK_IS_VALUE (obj));
132
133   iface = ATK_VALUE_GET_IFACE (obj);
134
135   if (iface->get_minimum_value)
136     {
137       if (G_IS_VALUE (value))
138         g_value_unset (value);
139       else
140         memset (value, 0, sizeof (*value));
141
142       (iface->get_minimum_value) (obj, value);
143     }
144 }
145
146 /**
147  * atk_value_get_minimum_increment:
148  * @obj: a GObject instance that implements AtkValueIface
149  * @value: a #GValue representing the minimum increment by which the accessible value may be changed
150  *
151  * Gets the minimum increment by which the value of this object may be changed.  If zero,
152  * the minimum increment is undefined, which may mean that it is limited only by the 
153  * floating point precision of the platform.
154  *
155  * Since: 1.12
156  **/
157 void
158 atk_value_get_minimum_increment (AtkValue *obj,
159                              GValue   *value)
160 {
161   AtkValueIface *iface;
162
163   g_return_if_fail (value != NULL);
164   g_return_if_fail (ATK_IS_VALUE (obj));
165
166   iface = ATK_VALUE_GET_IFACE (obj);
167
168   if (iface->get_minimum_increment)
169     {
170       if (G_IS_VALUE (value))
171         g_value_unset (value);
172       else
173         memset (value, 0, sizeof (*value));
174
175       (iface->get_minimum_increment) (obj, value);
176     }
177 }
178
179 /**
180  * atk_value_set_current_value:
181  * @obj: a GObject instance that implements AtkValueIface
182  * @value: a #GValue which is the desired new accessible value.
183  *
184  * Sets the value of this object.
185  *
186  * Returns: %TRUE if new value is successfully set, %FALSE otherwise.
187  **/
188 gboolean
189 atk_value_set_current_value (AtkValue       *obj, 
190                              const GValue   *value)
191 {
192   AtkValueIface *iface;
193
194   g_return_val_if_fail (ATK_IS_VALUE (obj), FALSE);
195   g_return_val_if_fail (G_IS_VALUE (value), FALSE);
196
197   iface = ATK_VALUE_GET_IFACE (obj);
198
199   if (iface->set_current_value)
200     return (iface->set_current_value) (obj, value);
201   else
202     return FALSE;
203 }