Revert "Remove all uses of G_CONST_RETURN"
[platform/upstream/glib.git] / gobject / gbinding.h
1 /* gbinding.h: Binding for object properties
2  *
3  * Copyright (C) 2010  Intel Corp.
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2 of the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General
16  * Public License along with this library; if not, write to the
17  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
18  * Boston, MA 02111-1307, USA.
19  *
20  * Author: Emmanuele Bassi <ebassi@linux.intel.com>
21  */
22
23 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
24 #error "Only <glib-object.h> can be included directly."
25 #endif
26
27 #ifndef __G_BINDING_H__
28 #define __G_BINDING_H__
29
30 #include <glib.h>
31 #include <gobject/gobject.h>
32
33 G_BEGIN_DECLS
34
35 #define G_TYPE_BINDING_FLAGS    (g_binding_flags_get_type ())
36
37 #define G_TYPE_BINDING          (g_binding_get_type ())
38 #define G_BINDING(obj)          (G_TYPE_CHECK_INSTANCE_CAST ((obj), G_TYPE_BINDING, GBinding))
39 #define G_IS_BINDING(obj)       (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_BINDING))
40
41 /**
42  * GBinding:
43  *
44  * <structname>GBinding</structname> is an opaque structure whose members
45  * cannot be accessed directly.
46  *
47  * Since: 2.26
48  */
49 typedef struct _GBinding        GBinding;
50
51 /**
52  * GBindingTransformFunc:
53  * @binding: a #GBinding
54  * @source_value: the value of the source property
55  * @target_value: the value of the target property
56  * @user_data: data passed to the transform function
57  *
58  * A function to be called to transform the source property of @source
59  * from @source_value into the target property of @target
60  * using @target_value.
61  *
62  * Return value: %TRUE if the transformation was successful, and %FALSE
63  *   otherwise
64  *
65  * Since: 2.26
66  */
67 typedef gboolean (* GBindingTransformFunc) (GBinding     *binding,
68                                             const GValue *source_value,
69                                             GValue       *target_value,
70                                             gpointer      user_data);
71
72 /**
73  * GBindingFlags:
74  * @G_BINDING_DEFAULT: The default binding; if the source property
75  *   changes, the target property is updated with its value.
76  * @G_BINDING_BIDIRECTIONAL: Bidirectional binding; if either the
77  *   property of the source or the property of the target changes,
78  *   the other is updated.
79  * @G_BINDING_SYNC_CREATE: Synchronize the values of the source and
80  *   target properties when creating the binding; the direction of
81  *   the synchronization is always from the source to the target.
82  * @G_BINDING_INVERT_BOOLEAN: If the two properties being bound are
83  *   booleans, setting one to %TRUE will result in the other being
84  *   set to %FALSE and vice versa. This flag will only work for
85  *   boolean properties, and cannot be used when passing custom
86  *   transformation functions to g_object_bind_property_full().
87  *
88  * Flags to be passed to g_object_bind_property() or
89  * g_object_bind_property_full().
90  *
91  * This enumeration can be extended at later date.
92  *
93  * Since: 2.26
94  */
95 typedef enum { /*< prefix=G_BINDING >*/
96   G_BINDING_DEFAULT        = 0,
97
98   G_BINDING_BIDIRECTIONAL  = 1 << 0,
99   G_BINDING_SYNC_CREATE    = 1 << 1,
100   G_BINDING_INVERT_BOOLEAN = 1 << 2
101 } GBindingFlags;
102
103 GType                 g_binding_flags_get_type      (void) G_GNUC_CONST;
104 GType                 g_binding_get_type            (void) G_GNUC_CONST;
105
106 GBindingFlags         g_binding_get_flags           (GBinding *binding);
107 GObject *             g_binding_get_source          (GBinding *binding);
108 GObject *             g_binding_get_target          (GBinding *binding);
109 G_CONST_RETURN gchar *g_binding_get_source_property (GBinding *binding);
110 G_CONST_RETURN gchar *g_binding_get_target_property (GBinding *binding);
111
112 GBinding *g_object_bind_property               (gpointer               source,
113                                                 const gchar           *source_property,
114                                                 gpointer               target,
115                                                 const gchar           *target_property,
116                                                 GBindingFlags          flags);
117 GBinding *g_object_bind_property_full          (gpointer               source,
118                                                 const gchar           *source_property,
119                                                 gpointer               target,
120                                                 const gchar           *target_property,
121                                                 GBindingFlags          flags,
122                                                 GBindingTransformFunc  transform_to,
123                                                 GBindingTransformFunc  transform_from,
124                                                 gpointer               user_data,
125                                                 GDestroyNotify         notify);
126 GBinding *g_object_bind_property_with_closures (gpointer               source,
127                                                 const gchar           *source_property,
128                                                 gpointer               target,
129                                                 const gchar           *target_property,
130                                                 GBindingFlags          flags,
131                                                 GClosure              *transform_to,
132                                                 GClosure              *transform_from);
133
134 G_END_DECLS
135
136 #endif /* __G_BINDING_H__ */