Struct gtk4::Expression
source · #[repr(transparent)]pub struct Expression { /* private fields */ }
Expand description
Expression
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()
for evaluating an expression.
Various methods for defining expressions exist, from simple constants via
ConstantExpression::new()
to looking up properties in a GObject
(even recursively) via PropertyExpression::new()
or providing
custom functions to transform and combine expressions via
ClosureExpression::new()
.
Here is an example of a complex expression:
⚠️ The following code is in 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
, it will obtain the
“item” property from the 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
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
is
evaluating a 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
is using a 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
,
which will cause a callback to be called whenever the value of the expression may
have changed; watch()
starts watching an expression, and
ExpressionWatch::unwatch()
stops.
Watches can be created for automatically updating the property of an object,
similar to GObject’s GBinding
mechanism, by using bind()
.
GtkExpression in GObject properties
In order to use a Expression
as a GObject
property, you must use the
gtk_param_spec_expression
when creating a GParamSpec
to install in the
GObject
class being defined; for instance:
⚠️ The following code is in 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 gtk_value_get_expression
, to retrieve the
stored Expression
from the GValue
container, and gtk_value_set_expression
,
to store the Expression
into the GValue
; for instance:
⚠️ The following code is in 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
has support for creating expressions. The syntax here can be used where
a 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 an element specfiying the expression
to use the object, or a string that specifies the name of the object to use.
Example:
<lookup name='search'>string_filter</lookup>
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. Otherwise,
it is assumed to be an object. For instance:
<constant>string_filter</constant>
<constant type='gchararray'>Hello, world</constant>
To create a closure expression, use the <closure>
element. The type
and function
attributes specify what function to use for the closure, the content of the element
contains the expressions for the parameters. For instance:
<closure type='gchararray' function='combine_args_somehow'>
<constant type='gchararray'>File size:</constant>
<lookup type='GFile' name='size'>myfile</lookup>
</closure>
This is an Abstract Base Class, you cannot instantiate it.
Implementations§
source§impl Expression
impl Expression
sourcepub fn as_ptr(&self) -> *mut GtkExpression
pub fn as_ptr(&self) -> *mut GtkExpression
Return the inner pointer to the underlying C value.
sourcepub unsafe fn from_glib_ptr_borrow<'a>(
ptr: *const *const GtkExpression
) -> &'a Self
pub unsafe fn from_glib_ptr_borrow<'a>( ptr: *const *const GtkExpression ) -> &'a Self
Borrows the underlying C value.
source§impl Expression
impl Expression
pub const NONE: Option<&'static Expression> = None
sourcepub fn bind(
&self,
target: &impl IsA<Object>,
property: &str,
this_: Option<&impl IsA<Object>>
) -> ExpressionWatch
pub fn bind( &self, target: &impl IsA<Object>, property: &str, this_: Option<&impl IsA<Object>> ) -> ExpressionWatch
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.
You can ensure that this doesn’t happen by using a fallback
expression.
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
sourcepub fn value_type(&self) -> Type
pub fn value_type(&self) -> Type
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()
sourcepub fn is_static(&self) -> bool
pub fn is_static(&self) -> bool
Checks if the expression is static.
A static expression will never change its result when
evaluate()
is called on it with the same arguments.
That means a call to watch()
is not necessary because
it will never trigger a notify.
Returns
TRUE
if the expression is static
sourcepub fn watch<P: Fn() + 'static>(
&self,
this_: Option<&impl IsA<Object>>,
notify: P
) -> ExpressionWatch
pub fn watch<P: Fn() + 'static>( &self, this_: Option<&impl IsA<Object>>, notify: P ) -> ExpressionWatch
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()
. You should call Gtk::ExpressionWatch::ref()
if you want to keep the watch around.
source§impl Expression
impl Expression
pub fn upcast(self) -> Self
pub fn upcast_ref(&self) -> &Self
pub fn is<E: IsExpression>(&self) -> bool
pub fn downcast<E: IsExpression>(self) -> Result<E, Expression>
pub fn downcast_ref<E: IsExpression>(&self) -> Option<&E>
pub fn type_(&self) -> Type
pub fn evaluate(&self, this: Option<&impl IsA<Object>>) -> Option<Value>
sourcepub fn evaluate_as<V: for<'b> FromValue<'b> + 'static, T: IsA<Object>>(
&self,
this: Option<&T>
) -> Option<V>
pub fn evaluate_as<V: for<'b> FromValue<'b> + 'static, T: IsA<Object>>( &self, this: Option<&T> ) -> Option<V>
Similar to Self::evaluate
but panics if the value is of a different type.
sourcepub fn chain_property<T: IsA<Object>>(
&self,
property_name: &str
) -> PropertyExpression
pub fn chain_property<T: IsA<Object>>( &self, property_name: &str ) -> PropertyExpression
Create a PropertyExpression
that looks up for
property_name
with self as parameter. This is useful in long chains of
Expression
s.
sourcepub fn chain_closure<R>(&self, closure: RustClosure) -> ClosureExpressionwhere
R: ValueType,
pub fn chain_closure<R>(&self, closure: RustClosure) -> ClosureExpressionwhere R: ValueType,
Create a ClosureExpression
from a glib::Closure
with self
as the second parameter and R
as the return type. The return type is checked at run-time
and must always be specified. This is useful in long chains of
Expression
s when using the [glib::closure!
] macro.
Note that the first parameter will always be the this
object bound to the expression. If
None
is passed as this
then the type of the first parameter must be
Option<glib::Object>
otherwise type checking will panic.
use gtk::prelude::*;
use gtk::glib;
use glib::{closure, Object};
let button = gtk::Button::new();
button.set_label("Hello");
let label = button
.property_expression("label")
.chain_closure::<String>(closure!(|_: Option<Object>, label: &str| {
format!("{} World", label)
}))
.evaluate_as::<String, _>(gtk::Widget::NONE);
assert_eq!(label.unwrap(), "Hello World");
sourcepub fn chain_closure_with_callback<F, R>(&self, f: F) -> ClosureExpressionwhere
F: Fn(&[Value]) -> R + 'static,
R: ValueType,
pub fn chain_closure_with_callback<F, R>(&self, f: F) -> ClosureExpressionwhere F: Fn(&[Value]) -> R + 'static, R: ValueType,
Create a ClosureExpression
with self as the second parameter.
This is useful in long chains of Expression
s.
Trait Implementations§
source§impl AsRef<Expression> for ClosureExpression
impl AsRef<Expression> for ClosureExpression
source§fn as_ref(&self) -> &Expression
fn as_ref(&self) -> &Expression
source§impl AsRef<Expression> for ConstantExpression
impl AsRef<Expression> for ConstantExpression
source§fn as_ref(&self) -> &Expression
fn as_ref(&self) -> &Expression
source§impl AsRef<Expression> for ObjectExpression
impl AsRef<Expression> for ObjectExpression
source§fn as_ref(&self) -> &Expression
fn as_ref(&self) -> &Expression
source§impl AsRef<Expression> for PropertyExpression
impl AsRef<Expression> for PropertyExpression
source§fn as_ref(&self) -> &Expression
fn as_ref(&self) -> &Expression
source§impl Clone for Expression
impl Clone for Expression
source§impl Debug for Expression
impl Debug for Expression
source§impl Display for Expression
impl Display for Expression
source§impl From<Expression> for Value
impl From<Expression> for Value
source§fn from(e: Expression) -> Self
fn from(e: Expression) -> Self
source§impl<'a> FromValue<'a> for Expression
impl<'a> FromValue<'a> for Expression
§type Checker = GenericValueTypeOrNoneChecker<Expression>
type Checker = GenericValueTypeOrNoneChecker<Expression>
source§unsafe fn from_value(value: &'a Value) -> Self
unsafe fn from_value(value: &'a Value) -> Self
Value
. Read moresource§impl HasParamSpec for Expression
impl HasParamSpec for Expression
type ParamSpec = ParamSpecExpression
§type SetValue = Expression
type SetValue = Expression
type BuilderFn = fn(_: &'a str) -> ParamSpecExpressionBuilder<'a>
fn param_spec_builder() -> Self::BuilderFn
source§impl StaticType for Expression
impl StaticType for Expression
source§fn static_type() -> Type
fn static_type() -> Type
Self
.source§impl ToValue for Expression
impl ToValue for Expression
source§impl ToValueOptional for Expression
impl ToValueOptional for Expression
source§impl ValueType for Expression
impl ValueType for Expression
§type Type = Expression
type Type = Expression
Type
from. Read more