GtkExpression

GtkExpression — Expressions to values

Types and Values

Includes

#include <gtk/gtk.h>

Description

GtkExpression provides a way to describe references to GValues.

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 gtk_expression_evaluate() for evaluating an expression.

Various methods for defining expressions exist, from simple constants via gtk_constant_expression_new() to looking up properties in a GObject (even recursively) via gtk_property_expression_new() or providing custom functions to transform and combine expressions via gtk_closure_expression_new().

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 GtkExpressionWatch, which will cause a callback to be called whenever the value of the expression may have changed. gtk_expression_watch() starts watching an expression, and gtk_expression_watch_unwatch() stops.

Watches can be created for automatically updating the propery of an object, similar to GObject's GBinding mechanism, by using gtk_expression_bind().

GtkExpression in GObject properties

In order to use a GtkExpression 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:

1
2
3
4
5
6
7
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 GtkExpression from the GValue container, and gtk_value_set_expression(), to store the GtkExpression into the GValue; for instance:

1
2
3
4
5
6
7
8
9
// 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

GtkBuilder has support for creating expressions. The syntax here can be used where a GtkExpression object is needed like in a <property> tag for an expression property, or in a <binding> tag to bind a property to an expression.

To create an 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:

1
2
3
4
5
6
7
8
9
10
11
<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.

Example:
|[
<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.

Example:

1
2
3
4
<closure type='gchararray' function='combine_args_somehow'>
  <constant type='gchararray'>File size:</constant>
  <lookup type='GFile' name='size'>myfile</lookup>
</closure>

Functions

GtkExpressionNotify ()

void
(*GtkExpressionNotify) (gpointer user_data);

Callback called by gtk_expression_watch() when the expression value changes.

Parameters

user_data

data passed to gtk_expression_watch()

 

gtk_expression_ref ()

GtkExpression *
gtk_expression_ref (GtkExpression *self);

Acquires a reference on the given GtkExpression.

Parameters

self

a GtkExpression.

[allow-none]

Returns

the GtkExpression with an additional reference.

[transfer none]


gtk_expression_unref ()

void
gtk_expression_unref (GtkExpression *self);

Releases a reference on the given GtkExpression.

If the reference was the last, the resources associated to the self are freed.

Parameters

self

a GtkExpression.

[allow-none]

gtk_expression_get_value_type ()

GType
gtk_expression_get_value_type (GtkExpression *self);

Gets the GType that this expression evaluates to. This type is constant and will not change over the lifetime of this expression.

Parameters

self

a GtkExpression

 

Returns

The type returned from gtk_expression_evaluate()


gtk_expression_is_static ()

gboolean
gtk_expression_is_static (GtkExpression *self);

Checks if the expression is static.

A static expression will never change its result when gtk_expression_evaluate() is called on it with the same arguments.

That means a call to gtk_expression_watch() is not necessary because it will never trigger a notify.

Parameters

self

a GtkExpression

 

Returns

TRUE if the expression is static


gtk_expression_evaluate ()

gboolean
gtk_expression_evaluate (GtkExpression *self,
                         gpointer this_,
                         GValue *value);

Evaluates the given expression and on success stores the result in value . The GType of value will be the type given by gtk_expression_get_value_type().

It is possible that expressions cannot be evaluated - for example when the expression references objects that have been destroyed or set to NULL. In that case value will remain empty and FALSE will be returned.

Parameters

self

a GtkExpression

 

this_

the this argument for the evaluation.

[transfer none][type GObject][nullable]

value

an empty GValue

 

Returns

TRUE if the expression could be evaluated


gtk_expression_watch ()

GtkExpressionWatch *
gtk_expression_watch (GtkExpression *self,
                      gpointer this_,
                      GtkExpressionNotify notify,
                      gpointer user_data,
                      GDestroyNotify user_destroy);

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

Parameters

self

a GtkExpression

 

this_

the this argument to watch.

[transfer none][type GObject][nullable]

notify

callback to invoke when the expression changes.

[closure user_data]

user_data

user data to pass to notify callback

 

user_destroy

destroy notify for user_data

 

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 gtk_expression_watch_unwatch(). You should call gtk_expression_watch_ref() if you want to keep the watch around.

[transfer none]


gtk_expression_bind ()

GtkExpressionWatch *
gtk_expression_bind (GtkExpression *self,
                     gpointer target,
                     const char *property,
                     gpointer this_);

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.

Parameters

self

a GtkExpression.

[transfer full]

target

the target object to bind to.

[transfer none][type GObject]

property

name of the property on target to bind to

 

this_

the this argument for the evaluation of self .

[transfer none][type GObject]

Returns

a GtkExpressionWatch.

[transfer none]


gtk_expression_watch_ref ()

GtkExpressionWatch *
gtk_expression_watch_ref (GtkExpressionWatch *watch);

Acquires a reference on the given GtkExpressionWatch.

Parameters

watch

a GtkExpressionWatch.

[allow-none]

Returns

the GtkExpression with an additional reference.

[transfer none]


gtk_expression_watch_unref ()

void
gtk_expression_watch_unref (GtkExpressionWatch *watch);

Releases a reference on the given GtkExpressionWatch.

If the reference was the last, the resources associated to self are freed.

Parameters

watch

a GtkExpressionWatch.

[allow-none]

gtk_expression_watch_evaluate ()

gboolean
gtk_expression_watch_evaluate (GtkExpressionWatch *watch,
                               GValue *value);

Evaluates the watched expression and on success stores the result in value .

This is equivalent to calling gtk_expression_evaluate() with the expression and this pointer originally used to create watch .

Parameters

watch

a GtkExpressionWatch

 

value

an empty GValue to be set

 

Returns

TRUE if the expression could be evaluated and value was set


gtk_expression_watch_unwatch ()

void
gtk_expression_watch_unwatch (GtkExpressionWatch *watch);

Stops watching an expression that was established via gtk_expression_watch().

Parameters

watch

watch to release.

[transfer none]

gtk_property_expression_new ()

GtkExpression *
gtk_property_expression_new (GType this_type,
                             GtkExpression *expression,
                             const char *property_name);

Creates an expression that looks up a property via the given expression or the this argument when expression is NULL.

If the resulting object conforms to this_type , its property named property_name will be queried. Otherwise, this expression's evaluation will fail.

The given this_type must have a property with property_name .

Parameters

this_type

The type to expect for the this type

 

expression

Expression to evaluate to get the object to query or NULL to query the this object.

[nullable][transfer full]

property_name

name of the property

 

Returns

a new GtkExpression


gtk_property_expression_new_for_pspec ()

GtkExpression *
gtk_property_expression_new_for_pspec (GtkExpression *expression,
                                       GParamSpec *pspec);

Creates an expression that looks up a property via the given expression or the this argument when expression is NULL.

If the resulting object conforms to this_type , its property specified by pspec will be queried. Otherwise, this expression's evaluation will fail.

Parameters

expression

Expression to evaluate to get the object to query or NULL to query the this object.

[nullable][transfer full]

pspec

the GParamSpec for the property to query

 

Returns

a new GtkExpression


gtk_constant_expression_new ()

GtkExpression *
gtk_constant_expression_new (GType value_type,
                             ...);

Creates a GtkExpression that evaluates to the object given by the arguments.

Parameters

value_type

The type of the object

 

...

arguments to create the object from

 

Returns

a new GtkExpression


gtk_constant_expression_new_for_value ()

GtkExpression *
gtk_constant_expression_new_for_value (const GValue *value);

Creates an expression that always evaluates to the given value .

Parameters

value

a GValue

 

Returns

a new GtkExpression


gtk_object_expression_new ()

GtkExpression *
gtk_object_expression_new (GObject *object);

Creates an expression evaluating to the given object with a weak reference. Once the object is disposed, it will fail to evaluate. This expression is meant to break reference cycles.

If you want to keep a reference to object , use gtk_constant_expression_new().

Parameters

object

object to watch.

[transfer none]

Returns

a new GtkExpression


gtk_closure_expression_new ()

GtkExpression *
gtk_closure_expression_new (GType value_type,
                            GClosure *closure,
                            guint n_params,
                            GtkExpression **params);

Creates a GtkExpression that calls closure when it is evaluated. closure is called with the this object and the results of evaluating the params expressions.

Parameters

value_type

the type of the value that this expression evaluates to

 

closure

closure to call when evaluating this expression. If closure is floating, it is adopted

 

n_params

the number of params needed for evaluating closure

 

params

expressions for each parameter.

[array length=n_params][transfer full]

Returns

a new GtkExpression


gtk_cclosure_expression_new ()

GtkExpression *
gtk_cclosure_expression_new (GType value_type,
                             GClosureMarshal marshal,
                             guint n_params,
                             GtkExpression **params,
                             GCallback callback_func,
                             gpointer user_data,
                             GClosureNotify user_destroy);

This function is a variant of gtk_closure_expression_new() that creates a GClosure by calling gtk_cclosure_new() with the given callback_func , user_data and user_destroy .

Parameters

value_type

the type of the value that this expression evaluates to

 

marshal

marshaller used for creating a closure.

[scope call]

n_params

the number of params needed for evaluating closure

 

params

expressions for each parameter.

[array length=n_params][transfer full]

callback_func

callback used for creating a closure.

[scope notified][closure user_data][destroy user_destroy]

user_data

user data used for creating a closure

 

user_destroy

destroy notify for user_data

 

Returns

a new GtkExpression

Types and Values

GtkExpression

typedef struct _GtkExpression GtkExpression;

The GtkExpression structure contains only private data.


GtkExpressionWatch

typedef struct _GtkExpressionWatch GtkExpressionWatch;