gtkmm: Gtk::Expression< T > Class Template Reference

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 >:
[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
ExpressionBase & | operator= (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)
Related Functions inherited from Gtk::ExpressionBase
Glib::RefPtr< Gtk::ExpressionBase > | wrap (GtkExpression * object, bool take_copy=false)
| A Glib::wrap() method for this object. More...

## 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:

color_expr = Gtk::PropertyExpression<Glib::RefPtr<Glib::ObjectBase>>::create(
Gtk::ListItem::get_type(), "item");
expression = Gtk::PropertyExpression<Glib::ustring>::create(
GTK_TYPE_COLOR, color_expr, "name");
Gtk::ListItem::get_type
static GType get_type()
Get the GType for this class, for use with the underlying GObject type system.
Gtk::PropertyExpression
Definition: expression.h:230
Gtk::PropertyExpression::create
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

  property | Property 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

  property | Property 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.
  notify | Callback to invoke when the expression changes.

Returns
  The newly installed watch.