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 	public static GType getType()
149 	{
150 		return g_binding_get_type();
151 	}
152 
153 	/**
154 	 * Retrieves the flags passed when constructing the #GBinding.
155 	 *
156 	 * Returns: the #GBindingFlags used by the #GBinding
157 	 *
158 	 * Since: 2.26
159 	 */
160 	public GBindingFlags getFlags()
161 	{
162 		return g_binding_get_flags(gBinding);
163 	}
164 
165 	/**
166 	 * Retrieves the #GObject instance used as the source of the binding.
167 	 *
168 	 * Returns: the source #GObject
169 	 *
170 	 * Since: 2.26
171 	 */
172 	public ObjectG getSource()
173 	{
174 		auto p = g_binding_get_source(gBinding);
175 		
176 		if(p is null)
177 		{
178 			return null;
179 		}
180 		
181 		return ObjectG.getDObject!(ObjectG)(cast(GObject*) p);
182 	}
183 
184 	/**
185 	 * Retrieves the name of the property of #GBinding:source used as the source
186 	 * of the binding.
187 	 *
188 	 * Returns: the name of the source property
189 	 *
190 	 * Since: 2.26
191 	 */
192 	public string getSourceProperty()
193 	{
194 		return Str.toString(g_binding_get_source_property(gBinding));
195 	}
196 
197 	/**
198 	 * Retrieves the #GObject instance used as the target of the binding.
199 	 *
200 	 * Returns: the target #GObject
201 	 *
202 	 * Since: 2.26
203 	 */
204 	public ObjectG getTarget()
205 	{
206 		auto p = g_binding_get_target(gBinding);
207 		
208 		if(p is null)
209 		{
210 			return null;
211 		}
212 		
213 		return ObjectG.getDObject!(ObjectG)(cast(GObject*) p);
214 	}
215 
216 	/**
217 	 * Retrieves the name of the property of #GBinding:target used as the target
218 	 * of the binding.
219 	 *
220 	 * Returns: the name of the target property
221 	 *
222 	 * Since: 2.26
223 	 */
224 	public string getTargetProperty()
225 	{
226 		return Str.toString(g_binding_get_target_property(gBinding));
227 	}
228 
229 	/**
230 	 * Explicitly releases the binding between the source and the target
231 	 * property expressed by @binding.
232 	 *
233 	 * This function will release the reference that is being held on
234 	 * the @binding instance; if you want to hold on to the #GBinding instance
235 	 * after calling g_binding_unbind(), you will need to hold a reference
236 	 * to it.
237 	 *
238 	 * Since: 2.38
239 	 */
240 	public void unbind()
241 	{
242 		g_binding_unbind(gBinding);
243 	}
244 }