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