glib-2.0/gobject/gbinding.h

0001 /* gbinding.h: Binding for object properties
0002  *
0003  * Copyright (C) 2010  Intel Corp.
0004  *
0005  * SPDX-License-Identifier: LGPL-2.1-or-later
0006  *
0007  * This library is free software; you can redistribute it and/or
0008  * modify it under the terms of the GNU Lesser General Public
0009  * License as published by the Free Software Foundation; either
0010  * version 2.1 of the License, or (at your option) any later version.
0011  *
0012  * This library is distributed in the hope that it will be useful,
0013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0015  * Lesser General Public License for more details.
0016  *
0017  * You should have received a copy of the GNU Lesser General
0018  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
0019  *
0020  * Author: Emmanuele Bassi <ebassi@linux.intel.com>
0021  */
0022
0023 #ifndef __G_BINDING_H__
0024 #define __G_BINDING_H__
0025
0026 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
0027 #error "Only <glib-object.h> can be included directly."
0028 #endif
0029
0030 #include <glib.h>
0031 #include <gobject/gobject.h>
0032
0033 G_BEGIN_DECLS
0034
0035 #define G_TYPE_BINDING_FLAGS    (g_binding_flags_get_type ())
0036
0037 #define G_TYPE_BINDING          (g_binding_get_type ())
0038 #define G_BINDING(obj)          (G_TYPE_CHECK_INSTANCE_CAST ((obj), G_TYPE_BINDING, GBinding))
0039 #define G_IS_BINDING(obj)       (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_BINDING))
0040
0041 typedef struct _GBinding        GBinding;
0042
0043 /**
0044  * GBindingTransformFunc:
0045  * @binding: a #GBinding
0046  * @from_value: the #GValue containing the value to transform
0047  * @to_value: the #GValue in which to store the transformed value
0048  * @user_data: data passed to the transform function
0049  *
0050  * A function to be called to transform @from_value to @to_value.
0051  *
0052  * If this is the @transform_to function of a binding, then @from_value
0053  * is the @source_property on the @source object, and @to_value is the
0054  * @target_property on the @target object. If this is the
0055  * @transform_from function of a %G_BINDING_BIDIRECTIONAL binding,
0056  * then those roles are reversed.
0057  *
0058  * Returns: %TRUE if the transformation was successful, and %FALSE
0059  *   otherwise
0060  *
0061  * Since: 2.26
0062  */
0063 typedef gboolean (* GBindingTransformFunc) (GBinding     *binding,
0064                                             const GValue *from_value,
0065                                             GValue       *to_value,
0066                                             gpointer      user_data);
0067
0068 /**
0069  * GBindingFlags:
0070  * @G_BINDING_DEFAULT: The default binding; if the source property
0071  *   changes, the target property is updated with its value.
0072  * @G_BINDING_BIDIRECTIONAL: Bidirectional binding; if either the
0073  *   property of the source or the property of the target changes,
0074  *   the other is updated.
0075  * @G_BINDING_SYNC_CREATE: Synchronize the values of the source and
0076  *   target properties when creating the binding; the direction of
0077  *   the synchronization is always from the source to the target.
0078  * @G_BINDING_INVERT_BOOLEAN: If the two properties being bound are
0079  *   booleans, setting one to %TRUE will result in the other being
0080  *   set to %FALSE and vice versa. This flag will only work for
0081  *   boolean properties, and cannot be used when passing custom
0082  *   transformation functions to g_object_bind_property_full().
0083  *
0084  * Flags to be passed to g_object_bind_property() or
0085  * g_object_bind_property_full().
0086  *
0087  * This enumeration can be extended at later date.
0088  *
0089  * Since: 2.26
0090  */
0091 typedef enum { /*< prefix=G_BINDING >*/
0092   G_BINDING_DEFAULT        = 0,
0093
0094   G_BINDING_BIDIRECTIONAL  = 1 << 0,
0095   G_BINDING_SYNC_CREATE    = 1 << 1,
0096   G_BINDING_INVERT_BOOLEAN = 1 << 2
0097 } GBindingFlags;
0098
0099 GOBJECT_AVAILABLE_IN_ALL
0100 GType                 g_binding_flags_get_type      (void) G_GNUC_CONST;
0101 GOBJECT_AVAILABLE_IN_ALL
0102 GType                 g_binding_get_type            (void) G_GNUC_CONST;
0103
0104 GOBJECT_AVAILABLE_IN_ALL
0105 GBindingFlags         g_binding_get_flags           (GBinding *binding);
0106 GOBJECT_DEPRECATED_IN_2_68_FOR(g_binding_dup_source)
0107 GObject *             g_binding_get_source          (GBinding *binding);
0108 GOBJECT_AVAILABLE_IN_2_68
0109 GObject *             g_binding_dup_source          (GBinding *binding);
0110 GOBJECT_DEPRECATED_IN_2_68_FOR(g_binding_dup_target)
0111 GObject *             g_binding_get_target          (GBinding *binding);
0112 GOBJECT_AVAILABLE_IN_2_68
0113 GObject *             g_binding_dup_target          (GBinding *binding);
0114 GOBJECT_AVAILABLE_IN_ALL
0115 const gchar *         g_binding_get_source_property (GBinding *binding);
0116 GOBJECT_AVAILABLE_IN_ALL
0117 const gchar *         g_binding_get_target_property (GBinding *binding);
0118 GOBJECT_AVAILABLE_IN_2_38
0119 void                  g_binding_unbind              (GBinding *binding);
0120
0121 GOBJECT_AVAILABLE_IN_ALL
0122 GBinding *g_object_bind_property               (gpointer               source,
0123                                                 const gchar           *source_property,
0124                                                 gpointer               target,
0125                                                 const gchar           *target_property,
0126                                                 GBindingFlags          flags);
0127 GOBJECT_AVAILABLE_IN_ALL
0128 GBinding *g_object_bind_property_full          (gpointer               source,
0129                                                 const gchar           *source_property,
0130                                                 gpointer               target,
0131                                                 const gchar           *target_property,
0132                                                 GBindingFlags          flags,
0133                                                 GBindingTransformFunc  transform_to,
0134                                                 GBindingTransformFunc  transform_from,
0135                                                 gpointer               user_data,
0136                                                 GDestroyNotify         notify);
0137 GOBJECT_AVAILABLE_IN_ALL
0138 GBinding *g_object_bind_property_with_closures (gpointer               source,
0139                                                 const gchar           *source_property,
0140                                                 gpointer               target,
0141                                                 const gchar           *target_property,
0142                                                 GBindingFlags          flags,
0143                                                 GClosure              *transform_to,
0144                                                 GClosure              *transform_from);
0145
0146 G_END_DECLS
0147
0148 #endif /* __G_BINDING_H__ */