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  * Conversion parameters:
26  * inFile  = gtk-Signals.html
27  * outPack = gtk
28  * outFile = Signals
29  * strct   = 
30  * realStrct=
31  * ctorStrct=
32  * clss    = Signals
33  * interf  = 
34  * class Code: No
35  * interface Code: No
36  * template for:
37  * extend  = 
38  * implements:
39  * prefixes:
40  * 	- gtk_signal_
41  * 	- gtk_
42  * omit structs:
43  * omit prefixes:
44  * omit code:
45  * omit signals:
46  * imports:
47  * 	- glib.Str
48  * 	- gtk.ObjectGtk
49  * structWrap:
50  * 	- GtkObject* -> ObjectGtk
51  * module aliases:
52  * local aliases:
53  * overrides:
54  */
55 
56 module gtk.Signals;
57 
58 public  import gtkc.gtktypes;
59 
60 private import gtkc.gtk;
61 private import glib.ConstructionException;
62 private import gobject.ObjectG;
63 
64 
65 private import glib.Str;
66 private import gtk.ObjectGtk;
67 
68 
69 
70 
71 /**
72  * Description
73  * The GTK+ signal system merely proxies the GLib signal system now. For future
74  * usage, direct use of the GSignal API is recommended, this avoids significant
75  * performance hits where GtkArg structures have to be converted into GValues.
76  * What are signals?
77  * Signals are a way to get notification when something happens
78  * and to customize object behavior according to the
79  * user's needs.
80  * Every signal is uniquely identified by a name,
81  * "class_name::signal_name", where signal_name might be something like
82  * "clicked" and class_name might be "GtkButton". Note that some other class
83  * may also define a "clicked" callback, so long as it doesn't derive from
84  * GtkButton.
85  * When they are created, they are also assigned a unique positive integer,
86  * the signal id (1 is the first signal id- 0 is used to flag an error).
87  * Each is also tied to an array of types that describes
88  * the prototype of the function pointer(s) (handlers) you may
89  * connect to the signal. Finally, every signal has
90  * a default handler that is given by a function pointer
91  * in its class structure: it is run by default whenever the
92  * signal is emitted. (It is possible that a signal will
93  * be emitted and a user-defined handler will prevent the default handler
94  * from being run.)
95  * Signals are used by everyone, but they are only
96  * created on a per class basis -- so you should not call
97  * call gtk_signal_new() unless you are writing
98  * a new GtkObject type. However, if you want to make a new signal
99  * for an existing type, you may use gtk_object_class_user_signal_new()
100  * to create a signal that doesn't correspond to a class's builtin
101  * methods.
102  * <hr>
103  * How are signals used?
104  * There are two basic actions in the signal handling game.
105  * If you want notification of an event, you must connect
106  * a function pointer and a data pointer to that signal; the data pointer
107  * will be passed as the last argument to the function (so long as you
108  * are using the default marshalling functions).
109  * You will receive a connection id, a unique positive integer
110  * corresponding to that attachment.
111  * Functions that want to notify the user of certain actions,
112  * emit signals.
113  * <hr>
114  * Basic Terminology
115  * signal
116  * A class method, e.g. GtkButton::clicked.
117  * More precisely it is a unique class-branch/signal-name pair.
118  * This means you may not define a signal handler for a class which
119  * derives from GtkButton that is called clicked,
120  * but it is okay to share signals names if they are separate in
121  * the class tree.
122  * default handler
123  * The object's internal method which is invoked
124  * when the signal is emitted.
125  * user-defined handler
126  * A function pointer and data connected
127  * to a signal (for a particular object).
128  * There are really two types: those which are connected
129  * normally, and those which are connected by one
130  * of the connect_after functions. The connect_after handlers
131  * are always run after the default handler.
132  * Many toolkits refer to these as callbacks.
133  * emission
134  * the whole process of emitting a signal,
135  * including the invocation of all
136  * the different handler types mentioned above.
137  * signal id
138  * The unique positive (nonzero) integer
139  * used to identify a signal. It can be used instead of
140  * a name to many functions for a slight performance
141  * improvement.
142  * connection id
143  * The unique positive (nonzero) integer
144  * used to identify the connection of a user-defined handler
145  * to a signal. Notice that it is allowed to connect the
146  * same function-pointer/user-data pair twice, so
147  * there is no guarantee that a function-pointer/user-data
148  * maps to a unique connection id.
149  * <hr>
150  * A brief note on how they work.
151  * The functions responsible for translating an array of GtkArgs
152  * to your C compiler's normal semantics are called Marshallers.
153  * They are identified by
154  * gtk_marshal_return_value__parameter_list()
155  * for example a C function returning a gboolean and taking a gint
156  * can be invoked by using gtk_marshal_BOOL__INT().
157  * Not all possibly combinations of return/params are available,
158  * of course, so if you are writing a GtkObject with parameters
159  * you might have to write a marshaller.
160  */
161 public class Signals
162 {
163 	
164 	/**
165 	 */
166 	
167 	/**
168 	 * Warning
169 	 * gtk_signal_newv is deprecated and should not be used in newly-written code. Use g_signal_newv() instead.
170 	 * Creates a new signal type. (This is usually done in a
171 	 * class initializer.)
172 	 * This function take the types as an array, instead of a list
173 	 * following the arguments. Otherwise the same as gtk_signal_new().
174 	 * Params:
175 	 * name = the name of the signal to create.
176 	 * signalFlags = see gtk_signal_new().
177 	 * objectType = the type of GtkObject to associate the signal with.
178 	 * functionOffset = how many bytes the function pointer is in
179 	 * the class structure for this type.
180 	 * returnVal = the type of the return value, or GTK_TYPE_NONE if
181 	 * you don't want a return value.
182 	 * args = an array of GtkTypes, describing the prototype to
183 	 * the callbacks.
184 	 * Returns: the signal id.
185 	 */
186 	public static uint newv(string name, GtkSignalRunType signalFlags, GType objectType, uint functionOffset, GSignalCMarshaller marshaller, GType returnVal, GType[] args)
187 	{
188 		// guint gtk_signal_newv (const gchar *name,  GtkSignalRunType signal_flags,  GType object_type,  guint function_offset,  GSignalCMarshaller marshaller,  GType return_val,  guint n_args,  GType *args);
189 		return gtk_signal_newv(Str.toStringz(name), signalFlags, objectType, functionOffset, marshaller, returnVal, cast(int) args.length, args.ptr);
190 	}
191 	
192 	/**
193 	 * Warning
194 	 * gtk_signal_emitv is deprecated and should not be used in newly-written code. Use g_signal_emitv() instead.
195 	 * Emits a signal. This causes the default handler and user-connected
196 	 * handlers to be run. This differs from gtk_signal_emit() by taking
197 	 * an array of GtkArgs instead of using C's varargs mechanism.
198 	 * Params:
199 	 * object = the object to emit the signal to.
200 	 * signalId = the signal identifier.
201 	 * args = an array of GtkArgs, one for each parameter,
202 	 * followed by one which is a pointer to the return type.
203 	 */
204 	public static void emitv(ObjectGtk object, uint signalId, GtkArg[] args)
205 	{
206 		// void gtk_signal_emitv (GtkObject *object,  guint signal_id,  GtkArg *args);
207 		gtk_signal_emitv((object is null) ? null : object.getObjectGtkStruct(), signalId, args.ptr);
208 	}
209 	
210 	/**
211 	 * Warning
212 	 * gtk_signal_emitv_by_name is deprecated and should not be used in newly-written code. Use g_signal_emitv() and g_signal_lookup() instead.
213 	 * Emits a signal by name. This causes the default handler and user-connected
214 	 * handlers to be run. This differs from gtk_signal_emit() by taking
215 	 * an array of GtkArgs instead of using C's varargs mechanism.
216 	 * Params:
217 	 * object = the object to emit the signal to.
218 	 * name = the name of the signal.
219 	 * args = an array of GtkArgs, one for each parameter,
220 	 * followed by one which is a pointer to the return type.
221 	 */
222 	public static void emitvByName(ObjectGtk object, string name, GtkArg[] args)
223 	{
224 		// void gtk_signal_emitv_by_name (GtkObject *object,  const gchar *name,  GtkArg *args);
225 		gtk_signal_emitv_by_name((object is null) ? null : object.getObjectGtkStruct(), Str.toStringz(name), args.ptr);
226 	}
227 	
228 	/**
229 	 * Warning
230 	 * gtk_signal_emit_stop_by_name is deprecated and should not be used in newly-written code. Use g_signal_stop_emission_by_name() instead.
231 	 * This function aborts a signal's current emission.
232 	 * It is just like gtk_signal_emit_stop()
233 	 * except it will lookup the signal id for you.
234 	 * Params:
235 	 * object = the object whose signal handlers you wish to stop.
236 	 * name = the name of the signal you wish to stop.
237 	 */
238 	public static void emitStopByName(ObjectGtk object, string name)
239 	{
240 		// void gtk_signal_emit_stop_by_name (GtkObject *object,  const gchar *name);
241 		gtk_signal_emit_stop_by_name((object is null) ? null : object.getObjectGtkStruct(), Str.toStringz(name));
242 	}
243 	
244 	/**
245 	 * Warning
246 	 * gtk_signal_connect_full is deprecated and should not be used in newly-written code. Use g_signal_connect_data() instead.
247 	 * Attaches a function pointer and user data to a signal with
248 	 * more control.
249 	 * Params:
250 	 * object = the object which emits the signal. For example, a button
251 	 * in the button press signal.
252 	 * name = the name of the signal.
253 	 * func = function pointer to attach to the signal.
254 	 * data = the user data associated with the function.
255 	 * destroyFunc = function to call when this particular hook is
256 	 * disconnected.
257 	 * objectSignal = whether this is an object signal-- basically an "object
258 	 * signal" is one that wants its user_data and object fields switched,
259 	 * which is useful for calling functions which operate on another
260 	 * object primarily.
261 	 * after = whether to invoke the user-defined handler after the signal, or to let
262 	 * the signal's default behavior preside (i.e. depending on GTK_RUN_FIRST
263 	 * and GTK_RUN_LAST).
264 	 * Returns: the connection id.
265 	 */
266 	public static gulong connectFull(ObjectGtk object, string name, GCallback func, GtkCallbackMarshal unsupported, void* data, GDestroyNotify destroyFunc, int objectSignal, int after)
267 	{
268 		// gulong gtk_signal_connect_full (GtkObject *object,  const gchar *name,  GCallback func,  GtkCallbackMarshal unsupported,  gpointer data,  GDestroyNotify destroy_func,  gint object_signal,  gint after);
269 		return gtk_signal_connect_full((object is null) ? null : object.getObjectGtkStruct(), Str.toStringz(name), func, unsupported, data, destroyFunc, objectSignal, after);
270 	}
271 	
272 	/**
273 	 * Warning
274 	 * gtk_signal_connect_while_alive is deprecated and should not be used in newly-written code. Use g_signal_connect_object() instead.
275 	 * Attaches a function pointer and another GtkObject to a signal.
276 	 * This function takes an object whose "destroy" signal
277 	 * should be trapped.
278 	 * That way, you don't have to clean up the
279 	 * signal handler when you destroy the object.
280 	 * It is a little less efficient though.
281 	 * (Instead you may call gtk_signal_disconnect_by_data(), if you want
282 	 * to explicitly delete all attachments to this object. This
283 	 * is perhaps not recommended since it could be confused
284 	 * with an integer masquerading as a pointer (through GINT_TO_POINTER()).)
285 	 * Params:
286 	 * object = the object that emits the signal.
287 	 * name = name of the signal.
288 	 * func = function pointer to attach to the signal.
289 	 * funcData = pointer to pass to func.
290 	 * aliveObject = object whose death should cause the handler connection
291 	 * to be destroyed.
292 	 */
293 	public static void connectWhileAlive(ObjectGtk object, string name, GCallback func, void* funcData, ObjectGtk aliveObject)
294 	{
295 		// void gtk_signal_connect_while_alive (GtkObject *object,  const gchar *name,  GCallback func,  gpointer func_data,  GtkObject *alive_object);
296 		gtk_signal_connect_while_alive((object is null) ? null : object.getObjectGtkStruct(), Str.toStringz(name), func, funcData, (aliveObject is null) ? null : aliveObject.getObjectGtkStruct());
297 	}
298 	
299 	/**
300 	 * Warning
301 	 * gtk_signal_connect_object_while_alive is deprecated and should not be used in newly-written code. Use g_signal_connect_object() instead, passing
302 	 * G_CONNECT_SWAPPED as connect_flags.
303 	 * These signal connectors are for signals which refer to objects,
304 	 * so they must not be called after the object is deleted.
305 	 * Unlike gtk_signal_connect_while_alive(),
306 	 * this swaps the object and user data, making it suitable for
307 	 * use with functions which primarily operate on the user data.
308 	 * This function acts just like gtk_signal_connect_object() except
309 	 * it traps the "destroy" signal to prevent you from having to
310 	 * clean up the handler.
311 	 * Params:
312 	 * object = the object associated with the signal.
313 	 * name = name of the signal.
314 	 * func = function pointer to attach to the signal.
315 	 * aliveObject = the user data, which must be an object, whose destruction
316 	 * should signal the removal of this signal.
317 	 */
318 	public static void connectObjectWhileAlive(ObjectGtk object, string name, GCallback func, ObjectGtk aliveObject)
319 	{
320 		// void gtk_signal_connect_object_while_alive  (GtkObject *object,  const gchar *name,  GCallback func,  GtkObject *alive_object);
321 		gtk_signal_connect_object_while_alive((object is null) ? null : object.getObjectGtkStruct(), Str.toStringz(name), func, (aliveObject is null) ? null : aliveObject.getObjectGtkStruct());
322 	}
323 }