Top |
Functions
Description
GtkExpression 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
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()
.
Here is an example of a complex expression:
1 2 3 4 |
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 GtkListItem, it will obtain the
"item" property from the GtkListItem, 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
1 |
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, GtkDropDown is evaluating a GtkExpression to obtain strings from the items in its model that it can then use to match against the contents of its search entry. GtkStringFilter is using a GtkExpression 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 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 property 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 |
<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:
1 2 |
<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.
gtk_expression_ref ()
GtkExpression *
gtk_expression_ref (GtkExpression *self
);
Acquires a reference on the given GtkExpression.
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.
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.
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.
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.
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 |
||
this_ |
the |
[transfer none][type GObject][nullable] |
notify |
callback to invoke when the expression changes. |
[closure user_data] |
user_data |
user data to pass to |
|
user_destroy |
destroy notify for |
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.
gtk_expression_watch_ref ()
GtkExpressionWatch *
gtk_expression_watch_ref (GtkExpressionWatch *watch
);
Acquires a reference on the given GtkExpressionWatch.
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.
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
.
gtk_expression_watch_unwatch ()
void
gtk_expression_watch_unwatch (GtkExpressionWatch *watch
);
Stops watching an expression that was established via gtk_expression_watch()
.
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
.
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.
gtk_property_expression_get_expression ()
GtkExpression *
gtk_property_expression_get_expression
(GtkExpression *expression
);
Gets the expression specifying the object of a property expression.
gtk_property_expression_get_pspec ()
GParamSpec *
gtk_property_expression_get_pspec (GtkExpression *expression
);
Gets the GParamSpec specifying the property of a property expression.
gtk_constant_expression_new ()
GtkExpression * gtk_constant_expression_new (GType value_type
,...
);
Creates a GtkExpression that evaluates to the object given by the arguments.
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
.
gtk_constant_expression_get_value ()
const GValue *
gtk_constant_expression_get_value (GtkExpression *expression
);
Gets the value that a constant expression evaluates to.
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()
.
gtk_object_expression_get_object ()
GObject *
gtk_object_expression_get_object (GtkExpression *expression
);
Gets the object that the expression evaluates to.
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 |
|
params |
expressions for each parameter. |
[nullable][array length=n_params][transfer full] |
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 g_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][nullable] |
n_params |
the number of params needed for evaluating |
|
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. |
[nullable] |
user_destroy |
destroy notify for |
[nullable] |
GTK_VALUE_HOLDS_EXPRESSION()
#define GTK_VALUE_HOLDS_EXPRESSION(value) (G_VALUE_HOLDS ((value), GTK_TYPE_EXPRESSION))
Evaluates to TRUE
if value
was initialized with GTK_TYPE_EXPRESSION
.
gtk_value_set_expression ()
void gtk_value_set_expression (GValue *value
,GtkExpression *expression
);
Stores the given GtkExpression inside value
.
The GValue will acquire a reference to the expression
.
gtk_value_take_expression ()
void gtk_value_take_expression (GValue *value
,GtkExpression *expression
);
Stores the given GtkExpression inside value
.
This function transfers the ownership of the expression
to the GValue.
gtk_value_get_expression ()
GtkExpression *
gtk_value_get_expression (const GValue *value
);
Retrieves the GtkExpression stored inside the given value
.
gtk_value_dup_expression ()
GtkExpression *
gtk_value_dup_expression (const GValue *value
);
Retrieves the GtkExpression stored inside the given value
, and acquires
a reference to it.
gtk_param_spec_expression ()
GParamSpec * gtk_param_spec_expression (const char *name
,const char *nick
,const char *blurb
,GParamFlags flags
);
Creates a new GParamSpec instance for a property holding a GtkExpression.
See g_param_spec_internal()
for details on the property strings.
Types and Values
GtkExpression
typedef struct _GtkExpression GtkExpression;
The GtkExpression
structure contains only private data.
GtkParamSpecExpression
typedef struct { } GtkParamSpecExpression;
A GParamSpec for properties holding a GtkExpression.