gtk4/auto/

expression.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::{ExpressionWatch, ffi};
use glib::{prelude::*, translate::*};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// Provides a way to describe references to values.
    ///
    /// An important aspect of expressions is that the value can be obtained
    /// from a source that is several steps away. For example, an expression
    /// may describe ‘the value of property A of `object1`, which is itself the
    /// value of a property of `object2`’. And `object1` may not even exist yet
    /// at the time that the expression is created. This is contrast to `GObject`
    /// property bindings, which can only create direct connections between
    /// the properties of two objects that must both exist for the duration
    /// of the binding.
    ///
    /// An expression needs to be "evaluated" to obtain the value that it currently
    /// refers to. An evaluation always happens in the context of a current object
    /// called `this` (it mirrors the behavior of object-oriented languages),
    /// which may or may not influence the result of the evaluation. Use
    /// [`evaluate()`][Self::evaluate()] for evaluating an expression.
    ///
    /// Various methods for defining expressions exist, from simple constants via
    /// [`ConstantExpression::new()`][crate::ConstantExpression::new()] to looking up properties in a `GObject`
    /// (even recursively) via [`PropertyExpression::new()`][crate::PropertyExpression::new()] or providing
    /// custom functions to transform and combine expressions via
    /// [`ClosureExpression::new()`][crate::ClosureExpression::new()].
    ///
    /// Here is an example of a complex expression:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    ///   color_expr = gtk_property_expression_new (GTK_TYPE_LIST_ITEM,
    ///                                             NULL, "item");
    ///   expression = gtk_property_expression_new (GTK_TYPE_COLOR,
    ///                                             color_expr, "name");
    /// ```
    ///
    /// when evaluated with `this` being a [`ListItem`][crate::ListItem], it will obtain the
    /// "item" property from the [`ListItem`][crate::ListItem], and then obtain the "name" property
    /// from the resulting object (which is assumed to be of type `GTK_TYPE_COLOR`).
    ///
    /// A more concise way to describe this would be
    ///
    /// ```text
    ///   this->item->name
    /// ```
    ///
    /// The most likely place where you will encounter expressions is in the context
    /// of list models and list widgets using them. For example, [`DropDown`][crate::DropDown] is
    /// evaluating a [`Expression`][crate::Expression] to obtain strings from the items in its model
    /// that it can then use to match against the contents of its search entry.
    /// [`StringFilter`][crate::StringFilter] is using a [`Expression`][crate::Expression] for similar reasons.
    ///
    /// By default, expressions are not paying attention to changes and evaluation is
    /// just a snapshot of the current state at a given time. To get informed about
    /// changes, an expression needs to be "watched" via a [`ExpressionWatch`][crate::ExpressionWatch],
    /// which will cause a callback to be called whenever the value of the expression may
    /// have changed; [`watch()`][Self::watch()] starts watching an expression, and
    /// [`ExpressionWatch::unwatch()`][crate::ExpressionWatch::unwatch()] stops.
    ///
    /// Watches can be created for automatically updating the property of an object,
    /// similar to GObject's `GBinding` mechanism, by using [`bind()`][Self::bind()].
    ///
    /// ## GtkExpression in GObject properties
    ///
    /// In order to use a [`Expression`][crate::Expression] as a `GObject` property, you must use the
    /// `param_spec_expression()` when creating a `GParamSpec` to install in the
    /// `GObject` class being defined; for instance:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// obj_props[PROP_EXPRESSION] =
    ///   gtk_param_spec_expression ("expression",
    ///                              "Expression",
    ///                              "The expression used by the widget",
    ///                              G_PARAM_READWRITE |
    ///                              G_PARAM_STATIC_STRINGS |
    ///                              G_PARAM_EXPLICIT_NOTIFY);
    /// ```
    ///
    /// When implementing the `GObjectClass.set_property` and `GObjectClass.get_property`
    /// virtual functions, you must use `value_get_expression()`, to retrieve the
    /// stored [`Expression`][crate::Expression] from the `GValue` container, and `value_set_expression()`,
    /// to store the [`Expression`][crate::Expression] into the `GValue`; for instance:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    ///   // in set_property()...
    ///   case PROP_EXPRESSION:
    ///     foo_widget_set_expression (foo, gtk_value_get_expression (value));
    ///     break;
    ///
    ///   // in get_property()...
    ///   case PROP_EXPRESSION:
    ///     gtk_value_set_expression (value, foo->expression);
    ///     break;
    /// ```
    ///
    /// ## GtkExpression in .ui files
    ///
    /// [`Builder`][crate::Builder] has support for creating expressions. The syntax here can be used where
    /// a [`Expression`][crate::Expression] object is needed like in a `<property>` tag for an expression
    /// property, or in a `<binding name="property">` tag to bind a property to an expression.
    ///
    /// To create a property expression, use the `<lookup>` element. It can have a `type`
    /// attribute to specify the object type, and a `name` attribute to specify the property
    /// to look up. The content of `<lookup>` can either be a string that specifies the name
    /// of the object to use, an element specifying an expression to provide an object, or
    /// empty to use the `this` object.
    ///
    /// Example:
    ///
    /// ```xml
    ///   <lookup name='search'>string_filter</lookup>
    /// ```
    ///
    /// Since the `<lookup>` element creates an expression and its element content can
    /// itself be an expression, this means that `<lookup>` tags can also be nested.
    /// This is a common idiom when dealing with [`ListItem`][crate::ListItem]s. See
    /// [`BuilderListItemFactory`][crate::BuilderListItemFactory] for an example of this technique.
    ///
    /// To create a constant expression, use the `<constant>` element. If the type attribute
    /// is specified, the element content is interpreted as a value of that type, and the
    /// initial attribute can be specified to get the initial value for that type. Otherwise,
    /// it is assumed to be an object. For instance:
    ///
    /// ```xml
    ///   <constant>string_filter</constant>
    ///   <constant type='gchararray'>Hello, world</constant>
    ///   <constant type='gchararray' initial='true' /> <!-- NULL -->
    /// ```
    ///
    /// String (`type='gchararray'`) constants can be marked for translation with the
    /// `translatable=` attribute, and will then be looked up in the
    /// [`translation-domain`][struct@crate::Builder#translation-domain] when the expression is constructed.
    ///
    /// ```xml
    ///   <constant type='gchararray' translatable='yes'>I'm translatable!</constant>
    /// ```
    ///
    /// As with other translatable strings in [type@Gtk.Builder], constants can
    /// also have a context and/or translation comment:
    ///
    /// ```xml
    ///   <constant type='gchararray'
    ///             translatable='yes'
    ///             context='example'
    ///             comments='A sample string'>I'm translatable!</constant>
    /// ```
    ///
    /// To create a closure expression, use the `<closure>` element. The `function`
    /// attribute specifies what function to use for the closure, and the `type`
    /// attribute specifies its return type. The content of the element contains the
    /// expressions for the parameters. For instance:
    ///
    /// ```xml
    ///   <closure type='gchararray' function='combine_args_somehow'>
    ///     <constant type='gchararray'>File size:</constant>
    ///     <lookup type='GFile' name='size'>myfile</lookup>
    ///   </closure>
    /// ```
    ///
    /// If an expression can fail, a `<try>` element can be used to provide fallbacks.
    /// The expressions are tried from top to bottom until one of them succeeds.
    /// If none of the expressions succeed, the expression fails as normal:
    ///
    /// ```xml
    ///   <try>
    ///     <lookup type='GtkWindow' name='title'>
    ///       <lookup type='GtkLabel' name='root'></lookup>
    ///     </lookup>
    ///     <constant type='gchararray'>Hello World</constant>
    ///   </try>
    /// ```
    ///
    /// To create a property binding, use the `<binding>` element in place of where a
    /// `<property>` tag would ordinarily be used. The `name` and `object` attributes are
    /// supported. The `name` attribute is required, and pertains to the applicable property
    /// name. The `object` attribute is optional. If provided, it will use the specified object
    /// as the `this` object when the expression is evaluated. Here is an example in which the
    /// `label` property of a [`Label`][crate::Label] is bound to the `string` property of another arbitrary
    /// object:
    ///
    /// ```xml
    ///   <object class='GtkLabel'>
    ///     <binding name='label'>
    ///       <lookup name='string'>some_other_object</lookup>
    ///     </binding>
    ///   </object>
    /// ```
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    #[doc(alias = "GtkExpression")]
    pub struct Expression(Shared<ffi::GtkExpression>);

    match fn {
        ref => |ptr| ffi::gtk_expression_ref(ptr),
        unref => |ptr| ffi::gtk_expression_unref(ptr),
    }
}

impl StaticType for Expression {
    fn static_type() -> glib::Type {
        unsafe { from_glib(ffi::gtk_expression_get_type()) }
    }
}

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

    /// Bind `target`'s property named `property` to `self`.
    ///
    /// The value that `self` evaluates to is set via `g_object_set()` on
    /// `target`. This is repeated whenever `self` changes to ensure that
    /// the object's property stays synchronized with `self`.
    ///
    /// If `self`'s evaluation fails, `target`'s `property` is not updated.
    /// Use a `Gtk::TryExpression` to provide a fallback for this case.
    ///
    /// Note that this function takes ownership of `self`. If you want
    /// to keep it around, you should `Gtk::Expression::ref()` it beforehand.
    /// ## `target`
    /// the target object to bind to
    /// ## `property`
    /// name of the property on `target` to bind to
    /// ## `this_`
    /// the this argument for
    ///   the evaluation of `self`
    ///
    /// # Returns
    ///
    /// a [`ExpressionWatch`][crate::ExpressionWatch]
    #[doc(alias = "gtk_expression_bind")]
    pub fn bind(
        &self,
        target: &impl IsA<glib::Object>,
        property: &str,
        this_: Option<&impl IsA<glib::Object>>,
    ) -> ExpressionWatch {
        unsafe {
            from_glib_none(ffi::gtk_expression_bind(
                self.as_ref().to_glib_full(),
                target.as_ref().to_glib_none().0,
                property.to_glib_none().0,
                this_.map(|p| p.as_ref()).to_glib_none().0,
            ))
        }
    }

    /// Gets the `GType` that this expression evaluates to.
    ///
    /// This type is constant and will not change over the lifetime
    /// of this expression.
    ///
    /// # Returns
    ///
    /// The type returned from [`evaluate()`][Self::evaluate()]
    #[doc(alias = "gtk_expression_get_value_type")]
    #[doc(alias = "get_value_type")]
    pub fn value_type(&self) -> glib::types::Type {
        unsafe {
            from_glib(ffi::gtk_expression_get_value_type(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Checks if the expression is static.
    ///
    /// A static expression will never change its result when
    /// [`evaluate()`][Self::evaluate()] is called on it with the same arguments.
    ///
    /// That means a call to [`watch()`][Self::watch()] is not necessary because
    /// it will never trigger a notify.
    ///
    /// # Returns
    ///
    /// `TRUE` if the expression is static
    #[doc(alias = "gtk_expression_is_static")]
    pub fn is_static(&self) -> bool {
        unsafe {
            from_glib(ffi::gtk_expression_is_static(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Watch the given `expression` for changes.
    ///
    /// The @notify function will be called whenever the evaluation of `self`
    /// may have changed.
    ///
    /// GTK cannot guarantee that the evaluation did indeed change when the @notify
    /// gets invoked, but it guarantees the opposite: When it did in fact change,
    /// the @notify will be invoked.
    /// ## `this_`
    /// the `this` argument to
    ///   watch
    /// ## `notify`
    /// callback to invoke when the expression changes
    ///
    /// # Returns
    ///
    /// The newly installed watch. Note that the only
    ///   reference held to the watch will be released when the watch is unwatched
    ///   which can happen automatically, and not just via
    ///   [`ExpressionWatch::unwatch()`][crate::ExpressionWatch::unwatch()]. You should call `Gtk::ExpressionWatch::ref()`
    ///   if you want to keep the watch around.
    #[doc(alias = "gtk_expression_watch")]
    pub fn watch<P: Fn() + 'static>(
        &self,
        this_: Option<&impl IsA<glib::Object>>,
        notify: P,
    ) -> ExpressionWatch {
        let notify_data: Box_<P> = Box_::new(notify);
        unsafe extern "C" fn notify_func<P: Fn() + 'static>(user_data: glib::ffi::gpointer) {
            unsafe {
                let callback = &*(user_data as *mut P);
                (*callback)()
            }
        }
        let notify = Some(notify_func::<P> as _);
        unsafe extern "C" fn user_destroy_func<P: Fn() + 'static>(data: glib::ffi::gpointer) {
            unsafe {
                let _callback = Box_::from_raw(data as *mut P);
            }
        }
        let destroy_call4 = Some(user_destroy_func::<P> as _);
        let super_callback0: Box_<P> = notify_data;
        unsafe {
            from_glib_none(ffi::gtk_expression_watch(
                self.as_ref().to_glib_none().0,
                this_.map(|p| p.as_ref()).to_glib_none().0,
                notify,
                Box_::into_raw(super_callback0) as *mut _,
                destroy_call4,
            ))
        }
    }
}