1 /* ATK - Accessibility Toolkit
2 * Copyright 2001, 2002, 2003 Sun Microsystems Inc.
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.
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.
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.
23 #include <glib/gi18n-lib.h>
26 #include "atkmarshal.h"
27 #include "atk-enum-types.h"
28 #include "atkprivate.h"
32 * @Short_description: The ATK interface implemented by valuators and
33 * components which display or select a value from a bounded range of
37 * #AtkValue should be implemented for components which either display
38 * a value from a bounded range, or which allow the user to specify a
39 * value from a bounded range, or both. For instance, most sliders and
40 * range controls, as well as dials, should have #AtkObject
41 * representations which implement #AtkValue on the component's
42 * behalf. #AtKValues may be read-only, in which case attempts to
43 * alter the value return would fail.
45 * <refsect1 id="current-value-text">
46 * <title>On the subject of current value text</title>
48 * In addition to providing the current value, implementors can
49 * optionally provide an end-user-consumable textual description
50 * associated with this value. This description should be included
51 * when the numeric value fails to convey the full, on-screen
52 * representation seen by users.
56 * <title>Password strength</title>
57 * A password strength meter whose value changes as the user types
58 * their new password. Red is used for values less than 4.0, yellow
59 * for values between 4.0 and 7.0, and green for values greater than
60 * 7.0. In this instance, value text should be provided by the
61 * implementor. Appropriate value text would be "weak", "acceptable,"
62 * and "strong" respectively.
65 * A level bar whose value changes to reflect the battery charge. The
66 * color remains the same regardless of the charge and there is no
67 * on-screen text reflecting the fullness of the battery. In this
68 * case, because the position within the bar is the only indication
69 * the user has of the current charge, value text should not be
70 * provided by the implementor.
72 * <refsect2 id="implementor-notes">
73 * <title>Implementor Notes</title>
75 * Implementors should bear in mind that assistive technologies will
76 * likely prefer the value text provided over the numeric value when
77 * presenting a widget's value. As a result, strings not intended for
78 * end users should not be exposed in the value text, and strings
79 * which are exposed should be localized. In the case of widgets which
80 * display value text on screen, for instance through a separate label
81 * in close proximity to the value-displaying widget, it is still
82 * expected that implementors will expose the value text using the
87 * #AtkValue should NOT be implemented for widgets whose displayed
88 * value is not reflective of a meaningful amount. For instance, a
89 * progress pulse indicator whose value alternates between 0.0 and 1.0
90 * to indicate that some process is still taking place should not
91 * implement #AtkValue because the current value does not reflect
92 * progress towards completion.
97 * <refsect1 id="ranges">
98 * <title>On the subject of ranges</title>
100 * In addition to providing the minimum and maximum values,
101 * implementors can optionally provide details about subranges
102 * associated with the widget. These details should be provided by the
103 * implementor when both of the following are communicated visually to
107 * <listitem>The existence of distinct ranges such as "weak",
108 * "acceptable", and "strong" indicated by color, bar tick marks,
109 * and/or on-screen text.</listitem>
110 * <listitem>Where the current value stands within a given subrange,
111 * for instance illustrating progression from very "weak" towards
112 * nearly "acceptable" through changes in shade and/or position on
113 * the bar within the "weak" subrange.</listitem>
116 * If both of the above do not apply to the widget, it should be
117 * sufficient to expose the numeric value, along with the value text
118 * if appropriate, to make the widget accessible.
121 * <refsect2 id="ranges-implementor-notes">
122 * <title>Implementor Notes</title>
124 * If providing subrange details is deemed necessary, all possible
125 * values of the widget are expected to fall within one of the
126 * subranges defined by the implementor.
131 * <refsect1 id="localization">
132 * <title>On the subject of localization of end-user-consumable text
135 * Because value text and subrange descriptors are human-consumable,
136 * implementors are expected to provide localized strings which can be
137 * directly presented to end users via their assistive technology. In
138 * order to simplify this for implementors, implementors can use
139 * atk_value_type_get_localized_name() with the following
140 * already-localized constants for commonly-needed values can be used:
144 * <listitem>ATK_VALUE_VERY_WEAK</listitem>
145 * <listitem>ATK_VALUE_WEAK</listitem>
146 * <listitem>ATK_VALUE_ACCEPTABLE</listitem>
147 * <listitem>ATK_VALUE_STRONG</listitem>
148 * <listitem>ATK_VALUE_VERY_STRONG</listitem>
149 * <listitem>ATK_VALUE_VERY_LOW</listitem>
150 * <listitem>ATK_VALUE_LOW</listitem>
151 * <listitem>ATK_VALUE_MEDIUM</listitem>
152 * <listitem>ATK_VALUE_HIGH</listitem>
153 * <listitem>ATK_VALUE_VERY_HIGH</listitem>
154 * <listitem>ATK_VALUE_VERY_BAD</listitem>
155 * <listitem>ATK_VALUE_BAD</listitem>
156 * <listitem>ATK_VALUE_GOOD</listitem>
157 * <listitem>ATK_VALUE_VERY_GOOD</listitem>
158 * <listitem>ATK_VALUE_BEST</listitem>
159 * <listitem>ATK_VALUE_SUBSUBOPTIMAL</listitem>
160 * <listitem>ATK_VALUE_SUBOPTIMAL</listitem>
161 * <listitem>ATK_VALUE_OPTIMAL</listitem>
164 * Proposals for additional constants, along with their use cases,
165 * should be submitted to the GNOME Accessibility Team.
169 * <refsect1 id="changes">
170 * <title>On the subject of changes</title>
172 * Note that if there is a textual description associated with the new
173 * numeric value, that description should be included regardless of
174 * whether or not it has also changed.
179 static GPtrArray *value_type_names = NULL;
186 /* These are listed here for extraction by intltool */
204 static void atk_value_base_init (AtkValueIface *class);
206 static guint atk_value_signals[LAST_SIGNAL] = {0};
209 atk_value_get_type (void)
211 static GType type = 0;
216 sizeof (AtkValueIface),
217 (GBaseInitFunc) atk_value_base_init,
218 (GBaseFinalizeFunc) NULL,
222 type = g_type_register_static (G_TYPE_INTERFACE, "AtkValue", &tinfo, 0);
229 atk_value_base_init (AtkValueIface *class)
231 static gboolean initialized = FALSE;
235 * AtkValue::value-changed:
236 * @atkvalue: the object on which the signal was emitted.
237 * @value: the new value in a numerical form.
238 * @text: human readable text alternative (also called
239 * description) of this object. NULL if not available.
241 * The 'value-changed' signal is emitted when the current value
242 * that represent the object changes. @value is the numerical
243 * representation of this new value. @text is the human
244 * readable text alternative of @value, and can be NULL if it is
245 * not available. Note that if there is a textual description
246 * associated with the new numeric value, that description
247 * should be included regardless of whether or not it has also
250 * Example: a password meter whose value changes as the user
251 * types their new password. Appropiate value text would be
252 * "weak", "acceptable" and "strong".
256 atk_value_signals[VALUE_CHANGED] =
257 g_signal_new ("value_changed",
261 (GSignalAccumulator) NULL, NULL,
262 atk_marshal_VOID__DOUBLE_STRING,
264 2, G_TYPE_DOUBLE, G_TYPE_STRING);
271 * atk_value_get_current_value:
272 * @obj: a GObject instance that implements AtkValueIface
273 * @value: a #GValue representing the current accessible value
275 * Gets the value of this object.
277 * Deprecated: Since 2.12. Use atk_value_get_value_and_text()
281 atk_value_get_current_value (AtkValue *obj,
284 AtkValueIface *iface;
286 g_return_if_fail (value != NULL);
287 g_return_if_fail (ATK_IS_VALUE (obj));
289 iface = ATK_VALUE_GET_IFACE (obj);
291 if (iface->get_current_value)
293 if (G_IS_VALUE (value))
294 g_value_unset (value);
296 memset (value, 0, sizeof (*value));
298 (iface->get_current_value) (obj, value);
303 * atk_value_get_maximum_value:
304 * @obj: a GObject instance that implements AtkValueIface
305 * @value: a #GValue representing the maximum accessible value
307 * Gets the maximum value of this object.
309 * Deprecated: Since 2.12. Use atk_value_get_range() instead.
312 atk_value_get_maximum_value (AtkValue *obj,
315 AtkValueIface *iface;
317 g_return_if_fail (value != NULL);
318 g_return_if_fail (ATK_IS_VALUE (obj));
320 iface = ATK_VALUE_GET_IFACE (obj);
322 if (iface->get_maximum_value)
324 if (G_IS_VALUE (value))
325 g_value_unset (value);
327 memset (value, 0, sizeof (*value));
329 (iface->get_maximum_value) (obj, value);
334 * atk_value_get_minimum_value:
335 * @obj: a GObject instance that implements AtkValueIface
336 * @value: a #GValue representing the minimum accessible value
338 * Gets the minimum value of this object.
340 * Deprecated: Since 2.12. Use atk_value_get_range() instead.
343 atk_value_get_minimum_value (AtkValue *obj,
346 AtkValueIface *iface;
348 g_return_if_fail (value != NULL);
349 g_return_if_fail (ATK_IS_VALUE (obj));
351 iface = ATK_VALUE_GET_IFACE (obj);
353 if (iface->get_minimum_value)
355 if (G_IS_VALUE (value))
356 g_value_unset (value);
358 memset (value, 0, sizeof (*value));
360 (iface->get_minimum_value) (obj, value);
365 * atk_value_get_minimum_increment:
366 * @obj: a GObject instance that implements AtkValueIface
367 * @value: a #GValue representing the minimum increment by which the accessible value may be changed
369 * Gets the minimum increment by which the value of this object may be changed. If zero,
370 * the minimum increment is undefined, which may mean that it is limited only by the
371 * floating point precision of the platform.
375 * Deprecated: Since 2.12. Use atk_value_get_increment() instead.
378 atk_value_get_minimum_increment (AtkValue *obj,
381 AtkValueIface *iface;
383 g_return_if_fail (value != NULL);
384 g_return_if_fail (ATK_IS_VALUE (obj));
386 iface = ATK_VALUE_GET_IFACE (obj);
388 if (iface->get_minimum_increment)
390 if (G_IS_VALUE (value))
391 g_value_unset (value);
393 memset (value, 0, sizeof (*value));
395 (iface->get_minimum_increment) (obj, value);
400 * atk_value_set_current_value:
401 * @obj: a GObject instance that implements AtkValueIface
402 * @value: a #GValue which is the desired new accessible value.
404 * Sets the value of this object.
406 * Returns: %TRUE if new value is successfully set, %FALSE otherwise.
408 * Deprecated: Since 2.12. Use atk_value_set_value() instead.
411 atk_value_set_current_value (AtkValue *obj,
414 AtkValueIface *iface;
416 g_return_val_if_fail (ATK_IS_VALUE (obj), FALSE);
417 g_return_val_if_fail (G_IS_VALUE (value), FALSE);
419 iface = ATK_VALUE_GET_IFACE (obj);
421 if (iface->set_current_value)
422 return (iface->set_current_value) (obj, value);
429 * atk_value_get_value_and_text:
430 * @obj: a GObject instance that implements AtkValueIface
431 * @value: (out): address of #gdouble to put the current value of @obj
432 * @text: (out) (allow-none): address of #gchar to put the human
433 * readable text alternative for @value
435 * Gets the current value and the human readable text alternative of
436 * @obj. @text is a newly created string, that must be freed by the
437 * caller. Can be NULL if not descriptor is available.
443 atk_value_get_value_and_text (AtkValue *obj,
447 AtkValueIface *iface;
449 g_return_if_fail (ATK_IS_VALUE (obj));
451 iface = ATK_VALUE_GET_IFACE (obj);
453 if (iface->get_value_and_text)
455 (iface->get_value_and_text) (obj, value, text);
460 * atk_value_get_range:
461 * @obj: a GObject instance that implements AtkValueIface
463 * Gets the range of this object.
465 * Returns: (transfer full): a newly allocated #AtkRange that
466 * represents the minimum, maximum and descriptor (if available) of
467 * @obj. NULL if that range is not defined.
472 atk_value_get_range (AtkValue *obj)
474 AtkValueIface *iface;
476 g_return_val_if_fail (ATK_IS_VALUE (obj), NULL);
478 iface = ATK_VALUE_GET_IFACE (obj);
480 if (iface->get_range)
482 return (iface->get_range) (obj);
489 * atk_value_get_increment:
490 * @obj: a GObject instance that implements AtkValueIface
492 * Gets the minimum increment by which the value of this object may be
493 * changed. If zero, the minimum increment is undefined, which may
494 * mean that it is limited only by the floating point precision of the
497 * Return value: the minimum increment by which the value of this
498 * object may be changed. zero if undefined.
503 atk_value_get_increment (AtkValue *obj)
505 AtkValueIface *iface;
507 g_return_val_if_fail (ATK_IS_VALUE (obj), 0);
509 iface = ATK_VALUE_GET_IFACE (obj);
511 if (iface->get_increment)
513 return (iface->get_increment) (obj);
521 * atk_value_get_sub_ranges:
522 * @obj: a GObject instance that implements AtkValueIface
524 * Gets the list of subranges defined for this object. See #AtkValue
525 * introduction for examples of subranges and when to expose them.
527 * Returns: (element-type AtkRange) (transfer full): an #GSList of
528 * #AtkRange which each of the subranges defined for this object. Free
529 * the returns list with g_slist_free().
534 atk_value_get_sub_ranges (AtkValue *obj)
536 AtkValueIface *iface;
538 g_return_val_if_fail (ATK_IS_VALUE (obj), NULL);
540 iface = ATK_VALUE_GET_IFACE (obj);
542 if (iface->get_sub_ranges)
544 return (iface->get_sub_ranges) (obj);
551 * atk_value_set_value:
552 * @obj: a GObject instance that implements AtkValueIface
553 * @new_value: a double which is the desired new accessible value.
555 * Sets the value of this object.
557 * This method is intended to provide a way to change the value of the
558 * object. In any case, it is possible that the value can't be
559 * modified (ie: a read-only component). If the value changes due this
560 * call, it is possible that the text could change, and will trigger
561 * an #AtkValue::value-changed signal emission.
563 * Note for implementors: the deprecated atk_value_set_current_value()
564 * method returned TRUE or FALSE depending if the value was assigned
565 * or not. In the practice several implementors were not able to
566 * decide it, and returned TRUE in any case. For that reason it is not
567 * required anymore to return if the value was properly assigned or
573 atk_value_set_value (AtkValue *obj,
574 const gdouble new_value)
576 AtkValueIface *iface;
578 g_return_if_fail (ATK_IS_VALUE (obj));
580 iface = ATK_VALUE_GET_IFACE (obj);
582 if (iface->set_value)
584 (iface->set_value) (obj, new_value);
589 initialize_value_type_names ()
591 GTypeClass *enum_class;
592 GEnumValue *enum_value;
594 gchar *value_type_name = NULL;
596 if (value_type_names)
599 value_type_names = g_ptr_array_new ();
600 enum_class = g_type_class_ref (ATK_TYPE_VALUE_TYPE);
601 if (!G_IS_ENUM_CLASS(enum_class))
604 for (i = 0; i < ATK_VALUE_LAST_DEFINED; i++)
606 enum_value = g_enum_get_value (G_ENUM_CLASS (enum_class), i);
607 value_type_name = g_strdup (enum_value->value_nick);
608 _compact_name (value_type_name);
609 g_ptr_array_add (value_type_names, value_type_name);
612 g_type_class_unref (enum_class);
616 * atk_value_type_get_name:
617 * @role: The #AtkValueType whose name is required
619 * Gets the description string describing the #AtkValueType @value_type.
621 * Returns: the string describing the #AtkValueType
624 atk_value_type_get_name (AtkValueType value_type)
626 g_return_val_if_fail (value_type >= 0, NULL);
628 if (!value_type_names)
629 initialize_value_type_names ();
631 if (value_type < value_type_names->len)
632 return g_ptr_array_index (value_type_names, value_type);
638 * atk_value_type_get_localized_name:
639 * @value_type: The #AtkValueType whose localized name is required
641 * Gets the localized description string describing the #AtkValueType @value_type.
643 * Returns: the localized string describing the #AtkValueType
646 atk_value_type_get_localized_name (AtkValueType value_type)
648 _gettext_initialization ();
650 return dgettext (GETTEXT_PACKAGE, atk_value_type_get_name (value_type));