1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD 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
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gobject.Binding;
26 
27 private import glib.Str;
28 private import gobject.ObjectG;
29 private import gobject.c.functions;
30 public  import gobject.c.types;
31 public  import gtkc.gobjecttypes;
32 
33 
34 /**
35  * #GBinding is the representation of a binding between a property on a
36  * #GObject instance (or source) and another property on another #GObject
37  * instance (or target). Whenever the source property changes, the same
38  * value is applied to the target property; for instance, the following
39  * binding:
40  * 
41  * |[<!-- language="C" -->
42  * g_object_bind_property (object1, "property-a",
43  * object2, "property-b",
44  * G_BINDING_DEFAULT);
45  * ]|
46  * 
47  * will cause the property named "property-b" of @object2 to be updated
48  * every time g_object_set() or the specific accessor changes the value of
49  * the property "property-a" of @object1.
50  * 
51  * It is possible to create a bidirectional binding between two properties
52  * of two #GObject instances, so that if either property changes, the
53  * other is updated as well, for instance:
54  * 
55  * |[<!-- language="C" -->
56  * g_object_bind_property (object1, "property-a",
57  * object2, "property-b",
58  * G_BINDING_BIDIRECTIONAL);
59  * ]|
60  * 
61  * will keep the two properties in sync.
62  * 
63  * It is also possible to set a custom transformation function (in both
64  * directions, in case of a bidirectional binding) to apply a custom
65  * transformation from the source value to the target value before
66  * applying it; for instance, the following binding:
67  * 
68  * |[<!-- language="C" -->
69  * g_object_bind_property_full (adjustment1, "value",
70  * adjustment2, "value",
71  * G_BINDING_BIDIRECTIONAL,
72  * celsius_to_fahrenheit,
73  * fahrenheit_to_celsius,
74  * NULL, NULL);
75  * ]|
76  * 
77  * will keep the "value" property of the two adjustments in sync; the
78  * @celsius_to_fahrenheit function will be called whenever the "value"
79  * property of @adjustment1 changes and will transform the current value
80  * of the property before applying it to the "value" property of @adjustment2.
81  * 
82  * Vice versa, the @fahrenheit_to_celsius function will be called whenever
83  * the "value" property of @adjustment2 changes, and will transform the
84  * current value of the property before applying it to the "value" property
85  * of @adjustment1.
86  * 
87  * Note that #GBinding does not resolve cycles by itself; a cycle like
88  * 
89  * |[
90  * object1:propertyA -> object2:propertyB
91  * object2:propertyB -> object3:propertyC
92  * object3:propertyC -> object1:propertyA
93  * ]|
94  * 
95  * might lead to an infinite loop. The loop, in this particular case,
96  * can be avoided if the objects emit the #GObject::notify signal only
97  * if the value has effectively been changed. A binding is implemented
98  * using the #GObject::notify signal, so it is susceptible to all the
99  * various ways of blocking a signal emission, like g_signal_stop_emission()
100  * or g_signal_handler_block().
101  * 
102  * A binding will be severed, and the resources it allocates freed, whenever
103  * either one of the #GObject instances it refers to are finalized, or when
104  * the #GBinding instance loses its last reference.
105  * 
106  * Bindings for languages with garbage collection can use
107  * g_binding_unbind() to explicitly release a binding between the source
108  * and target properties, instead of relying on the last reference on the
109  * binding, source, and target instances to drop.
110  * 
111  * #GBinding is available since GObject 2.26
112  *
113  * Since: 2.26
114  */
115 public class Binding : ObjectG
116 {
117 	/** the main Gtk struct */
118 	protected GBinding* gBinding;
119 
120 	/** Get the main Gtk struct */
121 	public GBinding* getBindingStruct(bool transferOwnership = false)
122 	{
123 		if (transferOwnership)
124 			ownedRef = false;
125 		return gBinding;
126 	}
127 
128 	/** the main Gtk struct as a void* */
129 	protected override void* getStruct()
130 	{
131 		return cast(void*)gBinding;
132 	}
133 
134 	/**
135 	 * Sets our main struct and passes it to the parent class.
136 	 */
137 	public this (GBinding* gBinding, bool ownedRef = false)
138 	{
139 		this.gBinding = gBinding;
140 		super(cast(GObject*)gBinding, ownedRef);
141 	}
142 
143 
144 	/** */
145 	public static GType getType()
146 	{
147 		return g_binding_get_type();
148 	}
149 
150 	/**
151 	 * Retrieves the flags passed when constructing the #GBinding.
152 	 *
153 	 * Returns: the #GBindingFlags used by the #GBinding
154 	 *
155 	 * Since: 2.26
156 	 */
157 	public GBindingFlags getFlags()
158 	{
159 		return g_binding_get_flags(gBinding);
160 	}
161 
162 	/**
163 	 * Retrieves the #GObject instance used as the source of the binding.
164 	 *
165 	 * Returns: the source #GObject
166 	 *
167 	 * Since: 2.26
168 	 */
169 	public ObjectG getSource()
170 	{
171 		auto p = g_binding_get_source(gBinding);
172 
173 		if(p is null)
174 		{
175 			return null;
176 		}
177 
178 		return ObjectG.getDObject!(ObjectG)(cast(GObject*) p);
179 	}
180 
181 	/**
182 	 * Retrieves the name of the property of #GBinding:source used as the source
183 	 * of the binding.
184 	 *
185 	 * Returns: the name of the source property
186 	 *
187 	 * Since: 2.26
188 	 */
189 	public string getSourceProperty()
190 	{
191 		return Str.toString(g_binding_get_source_property(gBinding));
192 	}
193 
194 	/**
195 	 * Retrieves the #GObject instance used as the target of the binding.
196 	 *
197 	 * Returns: the target #GObject
198 	 *
199 	 * Since: 2.26
200 	 */
201 	public ObjectG getTarget()
202 	{
203 		auto p = g_binding_get_target(gBinding);
204 
205 		if(p is null)
206 		{
207 			return null;
208 		}
209 
210 		return ObjectG.getDObject!(ObjectG)(cast(GObject*) p);
211 	}
212 
213 	/**
214 	 * Retrieves the name of the property of #GBinding:target used as the target
215 	 * of the binding.
216 	 *
217 	 * Returns: the name of the target property
218 	 *
219 	 * Since: 2.26
220 	 */
221 	public string getTargetProperty()
222 	{
223 		return Str.toString(g_binding_get_target_property(gBinding));
224 	}
225 
226 	/**
227 	 * Explicitly releases the binding between the source and the target
228 	 * property expressed by @binding.
229 	 *
230 	 * This function will release the reference that is being held on
231 	 * the @binding instance; if you want to hold on to the #GBinding instance
232 	 * after calling g_binding_unbind(), you will need to hold a reference
233 	 * to it.
234 	 *
235 	 * Since: 2.38
236 	 */
237 	public void unbind()
238 	{
239 		g_binding_unbind(gBinding);
240 	}
241 }