AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

Add GtkExpression

Browse Source 
GtkExpressions allow looking up values from objects.

There are a few simple expressions, but the main one is the closure
expression that just calls a user-provided closure.
This commit is contained in:
Benjamin Otte 2019-11-16 21:52:18 +01:00 committed by Matthias Clasen
parent 4abdf695e3
commit e9f1ee5aab
6 changed files with 721 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/gtk/gtk4-docs.xml
View File

@ -48,6 +48,7 @@
<chapter id="Lists">
<title>GListModel support</title>
<xi:include href="xml/gtkexpression.xml" />
<xi:include href="xml/gtkfilterlistmodel.xml" />
<section>
<xi:include href="xml/gtkfilter.xml" />

36
docs/reference/gtk/gtk4-sections.txt
View File

@ -7066,6 +7066,38 @@ gtk_overlay_layout_child_get_clip_overlay
GTK_TYPE_OVERLAY_LAYOUT
gtk_overlay_layout_get_type
GTK_TYPE_OVERLAY_LAYOUT_CHLD
gtk_overlay_layout_child_
get_type
gtk_overlay_layout_child_get_type
</SECTION>
<SECTION>
<FILE>gtkexpression</FILE>
GtkExpression
GtkExpressionWatch
GtkExpressionNotify
gtk_expression_ref
gtk_expression_unref
gtk_expression_get_value_type
gtk_expression_is_static
gtk_expression_evaluate
gtk_expression_watch
gtk_expression_bind
gtk_expression_watch_ref
gtk_expression_watch_unref
gtk_expression_watch_evaluate
gtk_expression_watch_unwatch
<SUBSECTION>
gtk_property_expression_new
gtk_property_expression_new_for_pspec
gtk_constant_expression_new
gtk_constant_expression_new_for_value
gtk_object_expression
gtk_closure_expression_new
gtk_cclosure_expression_new
<SUBSECTION Standard>
GTK_IS_EXPRESSION
GTK_TYPE_EXPRESSION
<SUBSECTION Private>
gtk_expression_get_type
</SECTION>

1
gtk/gtk.h
View File

@ -106,6 +106,7 @@
#include <gtk/gtkeventcontrollermotion.h>
#include <gtk/gtkeventcontrollerscroll.h>
#include <gtk/gtkexpander.h>
#include <gtk/gtkexpression.h>
#include <gtk/gtkfixed.h>
#include <gtk/gtkfixedlayout.h>
#include <gtk/gtkfilechooser.h>

606
gtk/gtkexpression.c Normal file
View File

@ -0,0 +1,606 @@
/*
* Copyright © 2019 Benjamin Otte
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library. If not, see <http://www.gnu.org/licenses/>.
*
* Authors: Benjamin Otte <otte@gnome.org>
*/
#include "config.h"
#include "gtkexpression.h"
#include <gobject/gvaluecollector.h>
/**
* SECTION:gtkexpression
* @Short_description: Expressions to values
* @Title: GtkExpression
*
* 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().
*/
typedef struct _GtkExpressionClass GtkExpressionClass;
struct _GtkExpression
{
const GtkExpressionClass *expression_class;
GType value_type;
GtkExpression *owner;
};
struct _GtkExpressionClass
{
gsize struct_size;
const char *type_name;
void (* finalize) (GtkExpression *expr);
gboolean (* evaluate) (GtkExpression *expr,
gpointer this,
GValue *value);
};
/**
* GtkExpression: (ref-func gtk_expression_ref) (unref-func gtk_expression_unref)
*
* The `GtkExpression` structure contains only private data.
*/
G_DEFINE_BOXED_TYPE (GtkExpression, gtk_expression,
gtk_expression_ref,
gtk_expression_unref)
/*< private >
* gtk_expression_alloc:
* @expression_class: class structure for this expression
* @value_type: the type of the value returned by this expression
*
* Returns: (transfer full): the newly created #GtkExpression
*/
static gpointer
gtk_expression_alloc (const GtkExpressionClass *expression_class,
GType value_type)
{
GtkExpression *self;
g_return_val_if_fail (expression_class != NULL, NULL);
self = g_atomic_rc_box_alloc0 (expression_class->struct_size);
self->expression_class = expression_class;
self->value_type = value_type;
return self;
}
/*** CONSTANT ***/
typedef struct _GtkConstantExpression GtkConstantExpression;
struct _GtkConstantExpression
{
GtkExpression parent;
GValue value;
};
static void
gtk_constant_expression_finalize (GtkExpression *expr)
{
GtkConstantExpression *self = (GtkConstantExpression *) expr;
g_value_unset (&self->value);
}
static gboolean
gtk_constant_expression_evaluate (GtkExpression *expr,
gpointer this,
GValue *value)
{
GtkConstantExpression *self = (GtkConstantExpression *) expr;
g_value_init (value, G_VALUE_TYPE (&self->value));
g_value_copy (&self->value, value);
return TRUE;
}
static const GtkExpressionClass GTK_CONSTANT_EXPRESSION_CLASS =
{
sizeof (GtkConstantExpression),
"GtkConstantExpression",
gtk_constant_expression_finalize,
gtk_constant_expression_evaluate,
};
/**
* gtk_constant_expression_new:
* @value_type: The type of the object
* @...: arguments to create the object from
*
* Creates a GtkExpression that evaluates to the
* object given by the arguments.
*
* Returns: a new #GtkExpression
*/
GtkExpression *
gtk_constant_expression_new (GType value_type,
...)
{
GValue value = G_VALUE_INIT;
GtkExpression *result;
va_list args;
char *error;
va_start (args, value_type);
G_VALUE_COLLECT_INIT (&value, value_type,
args, G_VALUE_NOCOPY_CONTENTS,
&error);
if (error)
{
g_critical ("%s: %s", G_STRLOC, error);
g_free (error);
/* we purposely leak the value here, it might not be
* in a sane state if an error condition occurred
*/
return NULL;
}
result = gtk_constant_expression_new_for_value (&value);
g_value_unset (&value);
va_end (args);
return result;
}
/**
* gtk_constant_expression_new_for_value:
* @value: a #GValue
*
* Creates an expression that always evaluates to the given @value.
*
* Returns: a new #GtkExpression
**/
GtkExpression *
gtk_constant_expression_new_for_value (const GValue *value)
{
GtkConstantExpression *result;
g_return_val_if_fail (G_IS_VALUE (value), NULL);
result = gtk_expression_alloc (&GTK_CONSTANT_EXPRESSION_CLASS, G_VALUE_TYPE (value));
g_value_init (&result->value, G_VALUE_TYPE (value));
g_value_copy (value, &result->value);
return (GtkExpression *) result;
}
/*** PROPERTY ***/
typedef struct _GtkPropertyExpression GtkPropertyExpression;
struct _GtkPropertyExpression
{
GtkExpression parent;
GtkExpression *expr;
GParamSpec *pspec;
};
static void
gtk_property_expression_finalize (GtkExpression *expr)
{
GtkPropertyExpression *self = (GtkPropertyExpression *) expr;
g_clear_pointer (&self->expr, gtk_expression_unref);
}
static GObject *
gtk_property_expression_get_object (GtkPropertyExpression *self,
gpointer this)
{
GValue expr_value = G_VALUE_INIT;
GObject *object;
if (self->expr == NULL)
{
if (this)
return g_object_ref (this);
else
return NULL;
}
if (!gtk_expression_evaluate (self->expr, this, &expr_value))
return NULL;
if (!G_VALUE_HOLDS_OBJECT (&expr_value))
{
g_value_unset (&expr_value);
return NULL;
}
object = g_value_dup_object (&expr_value);
g_value_unset (&expr_value);
if (!G_TYPE_CHECK_INSTANCE_TYPE (object, self->pspec->owner_type))
{
g_object_unref (object);
return NULL;
}
return object;
}
static gboolean
gtk_property_expression_evaluate (GtkExpression *expr,
gpointer this,
GValue *value)
{
GtkPropertyExpression *self = (GtkPropertyExpression *) expr;
GObject *object;
object = gtk_property_expression_get_object (self, this);
if (object == NULL)
return FALSE;
g_object_get_property (object, self->pspec->name, value);
g_object_unref (object);
return TRUE;
}
static const GtkExpressionClass GTK_PROPERTY_EXPRESSION_CLASS =
{
sizeof (GtkPropertyExpression),
"GtkPropertyExpression",
gtk_property_expression_finalize,
gtk_property_expression_evaluate,
};
/**
* gtk_property_expression_new:
* @this_type: The type to expect for the this type
* @expression: (nullable) (transfer full): Expression to
* evaluate to get the object to query or %NULL to
* query the `this` object
* @property_name: name of the property
*
* 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.
*
* Returns: a new #GtkExpression
**/
GtkExpression *
gtk_property_expression_new (GType this_type,
GtkExpression *expression,
const char *property_name)
{
GParamSpec *pspec;
if (g_type_is_a (this_type, G_TYPE_OBJECT))
{
pspec = g_object_class_find_property (g_type_class_peek (this_type), property_name);
}
else if (g_type_is_a (this_type, G_TYPE_INTERFACE))
{
pspec = g_object_interface_find_property (g_type_default_interface_peek (this_type), property_name);
}
else
{
g_critical ("Type `%s` does not support properties", g_type_name (this_type));
return NULL;
}
if (pspec == NULL)
{
g_critical ("Type `%s` does not have a property named `%s`", g_type_name (this_type), property_name);
return NULL;
}
return gtk_property_expression_new_for_pspec (expression, pspec);
}
/**
* gtk_property_expression_new_for_pspec:
* @expression: (nullable) (transfer full): Expression to
* evaluate to get the object to query or %NULL to
* query the `this` object
* @pspec: the #GParamSpec for the property to query
*
* 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.
*
* Returns: a new #GtkExpression
**/
GtkExpression *
gtk_property_expression_new_for_pspec (GtkExpression *expression,
GParamSpec *pspec)
{
GtkPropertyExpression *result;
result = gtk_expression_alloc (&GTK_PROPERTY_EXPRESSION_CLASS, pspec->value_type);
result->pspec = pspec;
result->expr = expression;
return (GtkExpression *) result;
}
/*** CLOSURE ***/
typedef struct _GtkClosureExpression GtkClosureExpression;
struct _GtkClosureExpression
{
GtkExpression parent;
GClosure *closure;
guint n_params;
GtkExpression **params;
};
static void
gtk_closure_expression_finalize (GtkExpression *expr)
{
GtkClosureExpression *self = (GtkClosureExpression *) expr;
guint i;
for (i = 0; i < self->n_params; i++)
{
gtk_expression_unref (self->params[i]);
}
g_free (self->params);
g_closure_unref (self->closure);
}
static gboolean
gtk_closure_expression_evaluate (GtkExpression *expr,
gpointer this,
GValue *value)
{
GtkClosureExpression *self = (GtkClosureExpression *) expr;
GValue *instance_and_params;
gboolean result = TRUE;
guint i;
instance_and_params = g_alloca (sizeof (GValue) * (self->n_params + 1));
memset (instance_and_params, 0, sizeof (GValue) * (self->n_params + 1));
for (i = 0; i < self->n_params; i++)
{
if (!gtk_expression_evaluate (self->params[i], this, &instance_and_params[i + 1]))
{
result = FALSE;
goto out;
}
}
if (this)
g_value_init_from_instance (instance_and_params, this);
else
g_value_init (instance_and_params, G_TYPE_OBJECT);
g_value_init (value, expr->value_type);
g_closure_invoke (self->closure,
value,
self->n_params + 1,
instance_and_params,
NULL);
out:
for (i = 0; i < self->n_params + 1; i++)
g_value_unset (&instance_and_params[i]);
return result;
}
static const GtkExpressionClass GTK_CLOSURE_EXPRESSION_CLASS =
{
sizeof (GtkClosureExpression),
"GtkClosureExpression",
gtk_closure_expression_finalize,
gtk_closure_expression_evaluate,
};
/**
* gtk_closure_expression_new:
* @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: (array length=n_params) (transfer full): expressions for each parameter
*
* 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.
*
* Returns: a new #GtkExpression
*/
GtkExpression *
gtk_closure_expression_new (GType value_type,
GClosure *closure,
guint n_params,
GtkExpression **params)
{
GtkClosureExpression *result;
guint i;
g_return_val_if_fail (closure != NULL, NULL);
g_return_val_if_fail (n_params == 0 || params != NULL, NULL);
result = gtk_expression_alloc (&GTK_CLOSURE_EXPRESSION_CLASS, value_type);
result->closure = g_closure_ref (closure);
g_closure_sink (closure);
if (G_CLOSURE_NEEDS_MARSHAL (closure))
g_closure_set_marshal (closure, g_cclosure_marshal_generic);
result->n_params = n_params;
result->params = g_new (GtkExpression *, n_params);
for (i = 0; i < n_params; i++)
result->params[i] = params[i];
return (GtkExpression *) result;
}
/**
* gtk_cclosure_expression_new:
* @type: the type of the value that this expression evaluates to
* @marshal: marshaller used for creating a closure
* @n_params: the number of params needed for evaluating @closure
* @params: (array length=n_params) (transfer full): expressions for each parameter
* @callback_func: callback used for creating a closure
* @user_data: user data used for creating a closure
* @user_destroy: destroy notify for @user_data
*
* 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.
*
* Returns: a new #GtkExpression
*/
GtkExpression *
gtk_cclosure_expression_new (GType value_type,
GClosureMarshal marshal,
guint n_params,
GtkExpression **params,
GCallback callback_func,
gpointer user_data,
GClosureNotify user_destroy)
{
GClosure *closure;
closure = g_cclosure_new (callback_func, user_data, user_destroy);
if (marshal)
g_closure_set_marshal (closure, marshal);
return gtk_closure_expression_new (value_type, closure, n_params, params);
}
/*** PUBLIC API ***/
static void
gtk_expression_finalize (GtkExpression *self)
{
self->expression_class->finalize (self);
}
/**
* gtk_expression_ref:
* @self: (allow-none): a #GtkExpression
*
* Acquires a reference on the given #GtkExpression.
*
* Returns: (transfer none): the #GtkExpression with an additional reference
*/
GtkExpression *
gtk_expression_ref (GtkExpression *self)
{
return g_atomic_rc_box_acquire (self);
}
/**
* gtk_expression_unref:
* @self: (allow-none): a #GtkExpression
*
* Releases a reference on the given #GtkExpression.
*
* If the reference was the last, the resources associated to the @self are
* freed.
*/
void
gtk_expression_unref (GtkExpression *self)
{
g_atomic_rc_box_release_full (self, (GDestroyNotify) gtk_expression_finalize);
}
/**
* gtk_expression_get_value_type:
* @self: a #GtkExpression
*
* Gets the #GType that this expression evaluates to. This type
* is constant and will not change over the lifetime of this expression.
*
* Returns: The type returned from gtk_expression_evaluate()
**/
GType
gtk_expression_get_value_type (GtkExpression *self)
{
g_return_val_if_fail (GTK_IS_EXPRESSION (self), G_TYPE_INVALID);
return self->value_type;
}
/**
* gtk_expression_evaluate:
* @self: a #GtkExpression
* @this_: (transfer none) (type GObject) (nullable): the this argument for the evaluation
* @value: an empty #GValue
*
* 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.
*
* Returns: %TRUE if the expression could be evaluated
**/
gboolean
gtk_expression_evaluate (GtkExpression *self,
gpointer this_,
GValue *value)
{
g_return_val_if_fail (GTK_IS_EXPRESSION (self), FALSE);
g_return_val_if_fail (this_ == NULL || G_IS_OBJECT (this_), FALSE);
g_return_val_if_fail (value != NULL, FALSE);
return self->expression_class->evaluate (self, this_, value);
}

77
gtk/gtkexpression.h Normal file
View File

@ -0,0 +1,77 @@
/*
* Copyright © 2019 Benjamin Otte
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library. If not, see <http://www.gnu.org/licenses/>.
*
* Authors: Benjamin Otte <otte@gnome.org>
*/
#ifndef __GTK_EXPRESSION_H__
#define __GTK_EXPRESSION_H__
#include <gtk/gtktypes.h>
G_BEGIN_DECLS
typedef struct _GtkExpression GtkExpression;
#define GTK_IS_EXPRESSION(expr) ((expr) != NULL)
#define GTK_TYPE_EXPRESSION (gtk_expression_get_type ())
GDK_AVAILABLE_IN_ALL
GType gtk_expression_get_type (void) G_GNUC_CONST;
GDK_AVAILABLE_IN_ALL
GtkExpression * gtk_expression_ref (GtkExpression *self);
GDK_AVAILABLE_IN_ALL
void gtk_expression_unref (GtkExpression *self);
GDK_AVAILABLE_IN_ALL
GType gtk_expression_get_value_type (GtkExpression *self);
GDK_AVAILABLE_IN_ALL
gboolean gtk_expression_evaluate (GtkExpression *self,
gpointer this_,
GValue *value);
GDK_AVAILABLE_IN_ALL
GtkExpression * gtk_property_expression_new (GType this_type,
GtkExpression *expression,
const char *property_name);
GDK_AVAILABLE_IN_ALL
GtkExpression * gtk_property_expression_new_for_pspec (GtkExpression *expression,
GParamSpec *pspec);
GDK_AVAILABLE_IN_ALL
GtkExpression * gtk_constant_expression_new (GType value_type,
...);
GDK_AVAILABLE_IN_ALL
GtkExpression * gtk_constant_expression_new_for_value (const GValue *value);
GDK_AVAILABLE_IN_ALL
GtkExpression * gtk_closure_expression_new (GType value_type,
GClosure *closure,
guint n_params,
GtkExpression **params);
GDK_AVAILABLE_IN_ALL
GtkExpression * gtk_cclosure_expression_new (GType value_type,
GClosureMarshal marshal,
guint n_params,
GtkExpression **params,
GCallback callback_func,
gpointer user_data,
GClosureNotify user_destroy);
G_END_DECLS
#endif /* __GTK_EXPRESSION_H__ */

2
gtk/meson.build
View File

@ -222,6 +222,7 @@ gtk_public_sources = files([
'gtkeventcontrollermotion.c',
'gtkeventcontrollerscroll.c',
'gtkexpander.c',
'gtkexpression.c',
'gtkfilechooser.c',
'gtkfilechooserbutton.c',
'gtkfilechooserdialog.c',
@ -479,6 +480,7 @@ gtk_public_headers = files([
'gtkeventcontrollermotion.h',
'gtkeventcontrollerlegacy.h',
'gtkexpander.h',
'gtkexpression.h',
'gtkfilechooser.h',
'gtkfilechooserbutton.h',
'gtkfilechooserdialog.h',