[gtk/wip/otte/listview: 882/1040] Add GtkExpression



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 (&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;
+
+  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 (&GTK_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 (&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);
+}
+
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]