Gtk::Expression< T > Class Template Reference

Expressions to values. More...

#include <gtkmm/expression.h>

Inheritance diagram for Gtk::Expression< T >:

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

Public Member Functions
std::optional< T >	evaluate (const Glib::RefPtr< Glib::ObjectBase > &this_)
	Evaluates the given expression and on success returns the result.
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.
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.
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.
Public Member Functions inherited from Gtk::ExpressionBase
void	reference () const
	Increment the reference count for this object.
void	unreference () const
	Decrement the reference count for this object.
GtkExpression *	gobj ()
	Provides access to the underlying C instance.
const GtkExpression *	gobj () const
	Provides access to the underlying C instance.
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.
	ExpressionBase ()=delete
	ExpressionBase (const ExpressionBase &)=delete
ExpressionBase &	operator= (const ExpressionBase &)=delete
GType	get_value_type () const
	Gets the GType that this expression evaluates to.
bool	is_static () const
	Checks if the expression is static.

Additional Inherited Members
Protected Member Functions inherited from Gtk::ExpressionBase
void	operator delete (void *, std::size_t)
Related Symbols inherited from Gtk::ExpressionBase
Glib::RefPtr< Gtk::ExpressionBase >	wrap (GtkExpression *object, bool take_copy=false)
	A Glib::wrap() method for this object.

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");

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.