gtkmm  4.8.0
Public Types | Public Member Functions | List of all members
Gtk::Expression< T > Class Template Reference

Expressions to values. More...

#include <gtkmm/expression.h>

Inheritance diagram for Gtk::Expression< T >:
Inheritance graph
[legend]

Public Types

using ValueType = T
 
- Public Types inherited from Gtk::ExpressionBase
using SlotNotify = sigc::slot< void()>
 For instance: void on_notify();. More...
 

Public Member Functions

std::optional< T > evaluate (const Glib::RefPtr< Glib::ObjectBase > & this_)
 Evaluates the given expression and on success returns the result. More...
 
Glib::RefPtr< ExpressionWatch< T > > watch (const Glib::RefPtr< Glib::ObjectBase > & this_, const SlotNotify & notify)
 Installs a watch for the expression that calls the notify function whenever the evaluation of the expression may have changed. More...
 
template<class T2 >
Glib::RefPtr< ExpressionWatch< T > > bind (const Glib::PropertyProxy< T2 > & property, const Glib::RefPtr< Glib::ObjectBase > & this_=nullptr)
 Bind a target's property to the expression. More...
 
template<class T2 >
Glib::RefPtr< ExpressionWatch< T > > bind (const Glib::PropertyProxy_WriteOnly< T2 > & property, const Glib::RefPtr< Glib::ObjectBase > & this_=nullptr)
 Bind a target's property to the expression. More...
 
- Public Member Functions inherited from Gtk::ExpressionBase
void reference () const
 Increment the reference count for this object. More...
 
void unreference () const
 Decrement the reference count for this object. More...
 
GtkExpression * gobj ()
 Provides access to the underlying C instance. More...
 
const GtkExpression * gobj () const
 Provides access to the underlying C instance. More...
 
GtkExpression * gobj_copy () const
 Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
 
 ExpressionBase ()=delete
 
 ExpressionBase (const ExpressionBase &)=delete
 
ExpressionBaseoperator= (const ExpressionBase &)=delete
 
GType get_value_type () const
 Gets the GType that this expression evaluates to. More...
 
bool is_static () const
 Checks if the expression is static. More...
 

Additional Inherited Members

- Protected Member Functions inherited from Gtk::ExpressionBase
void operator delete (void *, std::size_t)
 

Detailed Description

template<class T>
class Gtk::Expression< T >

Expressions to values.

Gtk::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 Glib::Binding, 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 Gtk::ConstantExpression() to looking up properties in an object (even recursively) via Gtk::PropertyExpression() or providing custom functions to transform and combine expressions via Gtk::ClosureExpression().

Here is an example of a complex expression:

GTK_TYPE_COLOR, color_expr, "name");
static GType get_type()
Get the GType for this class, for use with the underlying GObject type system.
Definition: expression.h:230
static Glib::RefPtr< PropertyExpression > create(GType this_type, const Glib::ustring &property_name)
Creates an expression that looks up a property via the this argument.

when evaluated with this being a Gtk::ListItem, it will obtain the "item" property from the Gtk::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, Gtk::DropDown is evaluating a Gtk::Expression to obtain strings from the items in its model that it can then use to match against the contents of its search entry. Gtk::StringFilter is using a Gtk::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 Gtk::ExpressionWatch, which will cause a callback to be called whenever the value of the expression may have changed. watch() starts watching an expression, and Gtk::ExpressionWatch::unwatch() stops.

Watches can be created for automatically updating the propery of an object, similar to the Glib::Binding mechanism, by using bind().

Since gtkmm 3.98:

Member Typedef Documentation

◆ ValueType

template <class T >
using Gtk::Expression< T >::ValueType = T

Member Function Documentation

◆ bind() [1/2]

template <class T >
template <class T2 >
Glib::RefPtr<ExpressionWatch<T> > Gtk::Expression< T >::bind ( const Glib::PropertyProxy< T2 > &  property,
const Glib::RefPtr< Glib::ObjectBase > &  this_ = nullptr 
)

Bind a target's property to the expression.

The value that the expression evaluates to is set on the target. This is repeated whenever the expression changes to ensure that the object's property stays synchronized with the expression.

If the expression's evaluation fails, target's property is not updated. You can ensure that this doesn't happen by using a fallback expression.

Parameters
propertyProperty on the target to bind to.
this_The this argument for the evaluation of the expression.
Returns
A Gtk::ExpressionWatch.

◆ bind() [2/2]

template <class T >
template <class T2 >
Glib::RefPtr<ExpressionWatch<T> > Gtk::Expression< T >::bind ( const Glib::PropertyProxy_WriteOnly< T2 > &  property,
const Glib::RefPtr< Glib::ObjectBase > &  this_ = nullptr 
)

Bind a target's property to the expression.

The value that the expression evaluates to is set on the target. This is repeated whenever the expression changes to ensure that the object's property stays synchronized with the expression.

If the expression's evaluation fails, target's property is not updated. You can ensure that this doesn't happen by using a fallback expression.

Parameters
propertyProperty on the target to bind to.
this_The this argument for the evaluation of the expression.
Returns
A Gtk::ExpressionWatch.

◆ evaluate()

template <class T >
std::optional<T> Gtk::Expression< T >::evaluate ( const Glib::RefPtr< Glib::ObjectBase > &  this_)

Evaluates the given expression and on success returns the result.

It is possible that expressions cannot be evaluated - for example when the expression references objects that have been destroyed or set to nullptr. In that case the returned std::optional will not contain a value.

Parameters
this_The this argument for the evaluation.
Returns
The optional result of the evaluation.

◆ watch()

template <class T >
Glib::RefPtr<ExpressionWatch<T> > Gtk::Expression< T >::watch ( const Glib::RefPtr< Glib::ObjectBase > &  this_,
const SlotNotify notify 
)

Installs a watch for the expression that calls the notify function whenever the evaluation of the expression 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.

Parameters
this_The this argument to watch.
notifyCallback to invoke when the expression changes.
Returns
The newly installed watch.