[gtk/wip/otte/listview: 882/1040] Add GtkExpression
- From: Benjamin Otte <otte src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk/wip/otte/listview: 882/1040] Add GtkExpression
- Date: Sun, 2 Feb 2020 23:36:45 +0000 (UTC)
commit b4b95f9fe65fa0f9484596e88c2c8f6d9069d42a
Author: Benjamin Otte <otte redhat com>
Date: Sat Nov 16 21:52:18 2019 +0100
Add GtkExpression
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.
docs/reference/gtk/gtk4-docs.xml | 1 +
docs/reference/gtk/gtk4-sections.txt | 32 +++
gtk/gtk.h | 1 +
gtk/gtkexpression.c | 529 +++++++++++++++++++++++++++++++++++
gtk/gtkexpression.h | 73 +++++
gtk/meson.build | 2 +
6 files changed, 638 insertions(+)
---
diff --git a/docs/reference/gtk/gtk4-docs.xml b/docs/reference/gtk/gtk4-docs.xml
index 83b6b1672c..cb93447ed0 100644
--- a/docs/reference/gtk/gtk4-docs.xml
+++ b/docs/reference/gtk/gtk4-docs.xml
@@ -44,6 +44,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" />
diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index dbd2d810b1..4497825b34 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -7208,3 +7208,35 @@ GTK_DRAG_ICON_GET_CLASS
<SUBSECTION Private>
gtk_drag_icon_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_unwatch
+
+<SUBSECTION>
+gtk_property_expression_new
+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>
diff --git a/gtk/gtk.h b/gtk/gtk.h
index 78534ebf51..eb145dc0f4 100644
--- a/gtk/gtk.h
+++ b/gtk/gtk.h
@@ -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>
diff --git a/gtk/gtkexpression.c b/gtk/gtkexpression.c
new file mode 100644
index 0000000000..4aaf575ef2
--- /dev/null
+++ b/gtk/gtkexpression.c
@@ -0,0 +1,529 @@
+/*
+ * 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 (>K_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;
+
+ GParamSpec *pspec;
+};
+
+static void
+gtk_property_expression_finalize (GtkExpression *expr)
+{
+}
+
+static gboolean
+gtk_property_expression_evaluate (GtkExpression *expr,
+ gpointer this,
+ GValue *value)
+{
+ GtkPropertyExpression *self = (GtkPropertyExpression *) expr;
+
+ if (!G_TYPE_CHECK_INSTANCE_TYPE (this, self->pspec->owner_type))
+ return FALSE;
+
+ g_object_get_property (this, self->pspec->name, value);
+ 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
+ * @property_name: name of the property
+ *
+ * Creates an expression that looks up a property on the
+ * passed in object when it is evaluated.
+ * If gtk_expresson_evaluate() is called with an object of
+ * another type, 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,
+ const char *property_name)
+{
+ GtkPropertyExpression *result;
+ 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;
+ }
+
+ result = gtk_expression_alloc (>K_PROPERTY_EXPRESSION_CLASS, pspec->value_type);
+
+ result->pspec = pspec;
+
+ 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 (>K_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);
+}
+
diff --git a/gtk/gtkexpression.h b/gtk/gtkexpression.h
new file mode 100644
index 0000000000..c65cba336a
--- /dev/null
+++ b/gtk/gtkexpression.h
@@ -0,0 +1,73 @@
+/*
+ * 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,
+ const char
*property_name);
+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__ */
diff --git a/gtk/meson.build b/gtk/meson.build
index 9f71c9c82f..35361cdaec 100644
--- a/gtk/meson.build
+++ b/gtk/meson.build
@@ -226,6 +226,7 @@ gtk_public_sources = files([
'gtkeventcontrollermotion.c',
'gtkeventcontrollerscroll.c',
'gtkexpander.c',
+ 'gtkexpression.c',
'gtkfilechooser.c',
'gtkfilechooserbutton.c',
'gtkfilechooserdialog.c',
@@ -485,6 +486,7 @@ gtk_public_headers = files([
'gtkeventcontrollermotion.h',
'gtkeventcontrollerlegacy.h',
'gtkexpander.h',
+ 'gtkexpression.h',
'gtkfilechooser.h',
'gtkfilechooserbutton.h',
'gtkfilechooserdialog.h',
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
