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 }