On the subject of current value text

In addition to providing the current value, implementors can optionally provide an end-user-consumable textual description associated with this value. This description should be included when the numeric value fails to convey the full, on-screen representation seen by users.

A level bar whose value changes to reflect the battery charge. The color remains the same regardless of the charge and there is no on-screen text reflecting the fullness of the battery. In this case, because the position within the bar is the only indication the user has of the current charge, value text should not be provided by the implementor.

On the subject of ranges

In addition to providing the minimum and maximum values, implementors can optionally provide details about subranges associated with the widget. These details should be provided by the implementor when both of the following are communicated visually to the end user:

If both of the above do not apply to the widget, it should be sufficient to expose the numeric value, along with the value text if appropriate, to make the widget accessible.

On the subject of localization of end-user-consumable text values

Because value text and subrange descriptors are human-consumable, implementors are expected to provide localized strings which can be directly presented to end users via their assistive technology. In order to simplify this for implementors, implementors can use atk_value_type_get_localized_name() with the following already-localized constants for commonly-needed values can be used:

Proposals for additional constants, along with their use cases, should be submitted to the GNOME Accessibility Team.

On the subject of changes

Note that if there is a textual description associated with the new numeric value, that description should be included regardless of whether or not it has also changed.

atk_value_get_current_value ()

void
atk_value_get_current_value (AtkValue *obj,
                             GValue *value);

Gets the value of this object.

atk_value_get_maximum_value ()

void
atk_value_get_maximum_value (AtkValue *obj,
                             GValue *value);

Gets the maximum value of this object.

atk_value_get_minimum_value ()

void
atk_value_get_minimum_value (AtkValue *obj,
                             GValue *value);

Gets the minimum value of this object.

atk_value_set_current_value ()

gboolean
atk_value_set_current_value (AtkValue *obj,
                             const GValue *value);

Sets the value of this object.

atk_value_get_minimum_increment ()

void
atk_value_get_minimum_increment (AtkValue *obj,
                                 GValue *value);

Gets the minimum increment by which the value of this object may be changed. If zero, the minimum increment is undefined, which may mean that it is limited only by the floating point precision of the platform.

Since: 1.12

atk_value_get_value_and_text ()

void
atk_value_get_value_and_text (AtkValue *obj,
                              gdouble *value,
                              gchar **text);

Gets the current value and the human readable text alternative of obj . text is a newly created string, that must be freed by the caller. Can be NULL if no descriptor is available.

Since: 2.12

atk_value_get_range ()

AtkRange *
atk_value_get_range (AtkValue *obj);

Gets the range of this object.

Since: 2.12

atk_value_get_increment ()

gdouble
atk_value_get_increment (AtkValue *obj);

Gets the minimum increment by which the value of this object may be changed. If zero, the minimum increment is undefined, which may mean that it is limited only by the floating point precision of the platform.

Since: 2.12

atk_value_get_sub_ranges ()

GSList *
atk_value_get_sub_ranges (AtkValue *obj);

Gets the list of subranges defined for this object. See AtkValue introduction for examples of subranges and when to expose them.

Since: 2.12

atk_value_set_value ()

void
atk_value_set_value (AtkValue *obj,
                     const gdouble new_value);

Sets the value of this object.

This method is intended to provide a way to change the value of the object. In any case, it is possible that the value can't be modified (ie: a read-only component). If the value changes due this call, it is possible that the text could change, and will trigger an “value-changed” signal emission.

Note for implementors: the deprecated atk_value_set_current_value() method returned TRUE or FALSE depending if the value was assigned or not. In the practice several implementors were not able to decide it, and returned TRUE in any case. For that reason it is not required anymore to return if the value was properly assigned or not.

Since: 2.12

atk_value_type_get_localized_name ()

const gchar *
atk_value_type_get_localized_name (AtkValueType value_type);

Gets the localized description string describing the AtkValueType value_type .

atk_value_type_get_name ()

const gchar *
atk_value_type_get_name (AtkValueType value_type);

Gets the description string describing the AtkValueType value_type .

AtkValue

typedef struct _AtkValue AtkValue;

enum AtkValueType

Default types for a given value. Those are defined in order to easily get localized strings to describe a given value or a given subrange, using atk_value_type_get_localized_name().

The “value-changed” signal

void
user_function (AtkValue *atkvalue,
               double    value,
               char     *text,
               gpointer  user_data)

The 'value-changed' signal is emitted when the current value that represent the object changes. value is the numerical representation of this new value. text is the human readable text alternative of value , and can be NULL if it is not available. Note that if there is a textual description associated with the new numeric value, that description should be included regardless of whether or not it has also changed.

Example: a password meter whose value changes as the user types their new password. Appropiate value text would be "weak", "acceptable" and "strong".

Flags: Run Last

Since: 2.12