atk/auto/

value.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::Range;
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::{boxed::Box as Box_, fmt, mem, mem::transmute, ptr};

glib::wrapper! {
    /// The ATK interface implemented by valuators and components which display or select a value from a bounded range of values.
    ///
    /// [`Value`][crate::Value] should be implemented for components which either display
    /// a value from a bounded range, or which allow the user to specify a
    /// value from a bounded range, or both. For instance, most sliders and
    /// range controls, as well as dials, should have [`Object`][crate::Object]
    /// representations which implement [`Value`][crate::Value] on the component's
    /// behalf. `AtKValues` may be read-only, in which case attempts to
    /// alter the value return would fail.
    ///
    /// <refsect1 id="current-value-text">
    /// `<title>`On the subject of current value text`</title>`
    /// `<para>`
    /// 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.
    /// `</para>`
    ///
    /// `<example>`
    /// `<title>`Password strength`</title>`
    /// A password strength meter whose value changes as the user types
    /// their new password. Red is used for values less than 4.0, yellow
    /// for values between 4.0 and 7.0, and green for values greater than
    /// 7.0. In this instance, value text should be provided by the
    /// implementor. Appropriate value text would be "weak", "acceptable,"
    /// and "strong" respectively.
    /// `</example>`
    ///
    /// 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.
    ///
    /// <refsect2 id="implementor-notes">
    /// `<title>`Implementor Notes`</title>`
    /// `<para>`
    /// Implementors should bear in mind that assistive technologies will
    /// likely prefer the value text provided over the numeric value when
    /// presenting a widget's value. As a result, strings not intended for
    /// end users should not be exposed in the value text, and strings
    /// which are exposed should be localized. In the case of widgets which
    /// display value text on screen, for instance through a separate label
    /// in close proximity to the value-displaying widget, it is still
    /// expected that implementors will expose the value text using the
    /// above API.
    /// `</para>`
    ///
    /// `<para>`
    /// [`Value`][crate::Value] should NOT be implemented for widgets whose displayed
    /// value is not reflective of a meaningful amount. For instance, a
    /// progress pulse indicator whose value alternates between 0.0 and 1.0
    /// to indicate that some process is still taking place should not
    /// implement [`Value`][crate::Value] because the current value does not reflect
    /// progress towards completion.
    /// `</para>`
    /// `</refsect2>`
    /// `</refsect1>`
    ///
    /// <refsect1 id="ranges">
    /// `<title>`On the subject of ranges`</title>`
    /// `<para>`
    /// 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:
    /// `</para>`
    /// `<itemizedlist>`
    ///  `<listitem>`The existence of distinct ranges such as "weak",
    ///  "acceptable", and "strong" indicated by color, bar tick marks,
    ///  and/or on-screen text.`</listitem>`
    ///  `<listitem>`Where the current value stands within a given subrange,
    ///  for instance illustrating progression from very "weak" towards
    ///  nearly "acceptable" through changes in shade and/or position on
    ///  the bar within the "weak" subrange.`</listitem>`
    /// `</itemizedlist>`
    /// `<para>`
    /// 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.
    /// `</para>`
    ///
    /// <refsect2 id="ranges-implementor-notes">
    /// `<title>`Implementor Notes`</title>`
    /// `<para>`
    /// If providing subrange details is deemed necessary, all possible
    /// values of the widget are expected to fall within one of the
    /// subranges defined by the implementor.
    /// `</para>`
    /// `</refsect2>`
    /// `</refsect1>`
    ///
    /// <refsect1 id="localization">
    /// `<title>`On the subject of localization of end-user-consumable text
    /// values`</title>`
    /// `<para>`
    /// 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
    /// [`ValueType::localized_name()`][crate::ValueType::localized_name()] with the following
    /// already-localized constants for commonly-needed values can be used:
    /// `</para>`
    ///
    /// `<itemizedlist>`
    ///  `<listitem>`ATK_VALUE_VERY_WEAK`</listitem>`
    ///  `<listitem>`ATK_VALUE_WEAK`</listitem>`
    ///  `<listitem>`ATK_VALUE_ACCEPTABLE`</listitem>`
    ///  `<listitem>`ATK_VALUE_STRONG`</listitem>`
    ///  `<listitem>`ATK_VALUE_VERY_STRONG`</listitem>`
    ///  `<listitem>`ATK_VALUE_VERY_LOW`</listitem>`
    ///  `<listitem>`ATK_VALUE_LOW`</listitem>`
    ///  `<listitem>`ATK_VALUE_MEDIUM`</listitem>`
    ///  `<listitem>`ATK_VALUE_HIGH`</listitem>`
    ///  `<listitem>`ATK_VALUE_VERY_HIGH`</listitem>`
    ///  `<listitem>`ATK_VALUE_VERY_BAD`</listitem>`
    ///  `<listitem>`ATK_VALUE_BAD`</listitem>`
    ///  `<listitem>`ATK_VALUE_GOOD`</listitem>`
    ///  `<listitem>`ATK_VALUE_VERY_GOOD`</listitem>`
    ///  `<listitem>`ATK_VALUE_BEST`</listitem>`
    ///  `<listitem>`ATK_VALUE_SUBSUBOPTIMAL`</listitem>`
    ///  `<listitem>`ATK_VALUE_SUBOPTIMAL`</listitem>`
    ///  `<listitem>`ATK_VALUE_OPTIMAL`</listitem>`
    /// `</itemizedlist>`
    /// `<para>`
    /// Proposals for additional constants, along with their use cases,
    /// should be submitted to the GNOME Accessibility Team.
    /// `</para>`
    /// `</refsect1>`
    ///
    /// <refsect1 id="changes">
    /// `<title>`On the subject of changes`</title>`
    /// `<para>`
    /// 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.
    /// `</para>`
    /// `</refsect1>`
    ///
    /// ## Signals
    ///
    ///
    /// #### `value-changed`
    ///  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".
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`ValueExt`][trait@crate::prelude::ValueExt]
    #[doc(alias = "AtkValue")]
    pub struct Value(Interface<ffi::AtkValue, ffi::AtkValueIface>);

    match fn {
        type_ => || ffi::atk_value_get_type(),
    }
}

impl Value {
    pub const NONE: Option<&'static Value> = None;
}

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::Value>> Sealed for T {}
}

/// Trait containing all [`struct@Value`] methods.
///
/// # Implementors
///
/// [`NoOpObject`][struct@crate::NoOpObject], [`Value`][struct@crate::Value]
pub trait ValueExt: IsA<Value> + sealed::Sealed + 'static {
    /// Gets the value of this object.
    ///
    /// # Deprecated
    ///
    /// Since 2.12. Use [`value_and_text()`][Self::value_and_text()]
    /// instead.
    ///
    /// # Returns
    ///
    ///
    /// ## `value`
    /// a [`glib::Value`][crate::glib::Value] representing the current accessible value
    #[doc(alias = "atk_value_get_current_value")]
    #[doc(alias = "get_current_value")]
    fn current_value(&self) -> glib::Value {
        unsafe {
            let mut value = glib::Value::uninitialized();
            ffi::atk_value_get_current_value(
                self.as_ref().to_glib_none().0,
                value.to_glib_none_mut().0,
            );
            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.
    ///
    /// # Returns
    ///
    /// the minimum increment by which the value of this
    /// object may be changed. zero if undefined.
    #[doc(alias = "atk_value_get_increment")]
    #[doc(alias = "get_increment")]
    fn increment(&self) -> f64 {
        unsafe { ffi::atk_value_get_increment(self.as_ref().to_glib_none().0) }
    }

    /// Gets the maximum value of this object.
    ///
    /// # Deprecated
    ///
    /// Since 2.12. Use [`range()`][Self::range()] instead.
    ///
    /// # Returns
    ///
    ///
    /// ## `value`
    /// a [`glib::Value`][crate::glib::Value] representing the maximum accessible value
    #[doc(alias = "atk_value_get_maximum_value")]
    #[doc(alias = "get_maximum_value")]
    fn maximum_value(&self) -> glib::Value {
        unsafe {
            let mut value = glib::Value::uninitialized();
            ffi::atk_value_get_maximum_value(
                self.as_ref().to_glib_none().0,
                value.to_glib_none_mut().0,
            );
            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.
    ///
    /// # Deprecated
    ///
    /// Since 2.12. Use [`increment()`][Self::increment()] instead.
    ///
    /// # Returns
    ///
    ///
    /// ## `value`
    /// a [`glib::Value`][crate::glib::Value] representing the minimum increment by which the accessible value may be changed
    #[doc(alias = "atk_value_get_minimum_increment")]
    #[doc(alias = "get_minimum_increment")]
    fn minimum_increment(&self) -> glib::Value {
        unsafe {
            let mut value = glib::Value::uninitialized();
            ffi::atk_value_get_minimum_increment(
                self.as_ref().to_glib_none().0,
                value.to_glib_none_mut().0,
            );
            value
        }
    }

    /// Gets the minimum value of this object.
    ///
    /// # Deprecated
    ///
    /// Since 2.12. Use [`range()`][Self::range()] instead.
    ///
    /// # Returns
    ///
    ///
    /// ## `value`
    /// a [`glib::Value`][crate::glib::Value] representing the minimum accessible value
    #[doc(alias = "atk_value_get_minimum_value")]
    #[doc(alias = "get_minimum_value")]
    fn minimum_value(&self) -> glib::Value {
        unsafe {
            let mut value = glib::Value::uninitialized();
            ffi::atk_value_get_minimum_value(
                self.as_ref().to_glib_none().0,
                value.to_glib_none_mut().0,
            );
            value
        }
    }

    /// Gets the range of this object.
    ///
    /// # Returns
    ///
    /// a newly allocated [`Range`][crate::Range]
    /// that represents the minimum, maximum and descriptor (if available)
    /// of `self`. NULL if that range is not defined.
    #[doc(alias = "atk_value_get_range")]
    #[doc(alias = "get_range")]
    fn range(&self) -> Option<Range> {
        unsafe { from_glib_full(ffi::atk_value_get_range(self.as_ref().to_glib_none().0)) }
    }

    /// Gets the list of subranges defined for this object. See [`Value`][crate::Value]
    /// introduction for examples of subranges and when to expose them.
    ///
    /// # Returns
    ///
    /// an `GSList` of
    /// [`Range`][crate::Range] which each of the subranges defined for this object. Free
    /// the returns list with `g_slist_free()`.
    #[doc(alias = "atk_value_get_sub_ranges")]
    #[doc(alias = "get_sub_ranges")]
    fn sub_ranges(&self) -> Vec<Range> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::atk_value_get_sub_ranges(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the current value and the human readable text alternative of
    /// `self`. `text` is a newly created string, that must be freed by the
    /// caller. Can be NULL if no descriptor is available.
    ///
    /// # Returns
    ///
    ///
    /// ## `value`
    /// address of `gdouble` to put the current value of `self`
    ///
    /// ## `text`
    /// address of `gchar` to put the human
    /// readable text alternative for `value`
    #[doc(alias = "atk_value_get_value_and_text")]
    #[doc(alias = "get_value_and_text")]
    fn value_and_text(&self) -> (f64, glib::GString) {
        unsafe {
            let mut value = mem::MaybeUninit::uninit();
            let mut text = ptr::null_mut();
            ffi::atk_value_get_value_and_text(
                self.as_ref().to_glib_none().0,
                value.as_mut_ptr(),
                &mut text,
            );
            (value.assume_init(), from_glib_full(text))
        }
    }

    /// Sets the value of this object.
    ///
    /// # Deprecated
    ///
    /// Since 2.12. Use [`set_value()`][Self::set_value()] instead.
    /// ## `value`
    /// a [`glib::Value`][crate::glib::Value] which is the desired new accessible value.
    ///
    /// # Returns
    ///
    /// [`true`] if new value is successfully set, [`false`] otherwise.
    #[doc(alias = "atk_value_set_current_value")]
    fn set_current_value(&self, value: &glib::Value) -> bool {
        unsafe {
            from_glib(ffi::atk_value_set_current_value(
                self.as_ref().to_glib_none().0,
                value.to_glib_none().0,
            ))
        }
    }

    /// 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`][struct@crate::Value#value-changed] signal emission.
    ///
    /// Note for implementors: the deprecated [`set_current_value()`][Self::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.
    /// ## `new_value`
    /// a double which is the desired new accessible value.
    #[doc(alias = "atk_value_set_value")]
    fn set_value(&self, new_value: f64) {
        unsafe {
            ffi::atk_value_set_value(self.as_ref().to_glib_none().0, new_value);
        }
    }

    /// 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".
    /// ## `value`
    /// the new value in a numerical form.
    /// ## `text`
    /// human readable text alternative (also called
    /// description) of this object. NULL if not available.
    #[doc(alias = "value-changed")]
    fn connect_value_changed<F: Fn(&Self, f64, &str) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn value_changed_trampoline<
            P: IsA<Value>,
            F: Fn(&P, f64, &str) + 'static,
        >(
            this: *mut ffi::AtkValue,
            value: libc::c_double,
            text: *mut libc::c_char,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                Value::from_glib_borrow(this).unsafe_cast_ref(),
                value,
                &glib::GString::from_glib_borrow(text),
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"value-changed\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    value_changed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<Value>> ValueExt for O {}

impl fmt::Display for Value {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str("Value")
    }
}