GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# Signals

## Name

Signals -- Object methods and callbacks.

## Synopsis

    #include <gtk/gtk.h>

    #define     GTK_SIGNAL_OFFSET               (struct, field)
    void        (*GtkSignalMarshal)             (GtkObject *object,
                                                 gpointer data,
                                                 guint nparams,
                                                 GtkArg *args,
                                                 GtkType *arg_types,
                                                 GtkType return_type);
    void        (*GtkSignalDestroy)             (gpointer data);
    gboolean    (*GtkEmissionHook)              (GtkObject *object,
                                                 guint signal_id,
                                                 guint n_params,
                                                 GtkArg *params,
                                                 gpointer data);
    struct      GtkSignalQuery;
    enum        GtkSignalRunType;
    void        gtk_signal_init                 (void);
    guint       gtk_signal_new                  (const gchar *name,
                                                 GtkSignalRunType signal_flags,
                                                 GtkType object_type,
                                                 guint function_offset,
                                                 GtkSignalMarshaller marshaller,
                                                 GtkType return_val,
                                                 guint nparams,
                                                 ...);
    guint       gtk_signal_newv                 (const gchar *name,
                                                 GtkSignalRunType signal_flags,
                                                 GtkType object_type,
                                                 guint function_offset,
                                                 GtkSignalMarshaller marshaller,
                                                 GtkType return_val,
                                                 guint nparams,
                                                 GtkType *params);
    guint       gtk_signal_lookup               (const gchar *name,
                                                 GtkType object_type);
    gchar*      gtk_signal_name                 (guint signal_id);
    void        gtk_signal_emit                 (GtkObject *object,
                                                 guint signal_id,
                                                 ...);
    void        gtk_signal_emit_by_name         (GtkObject *object,
                                                 const gchar *name,
                                                 ...);
    void        gtk_signal_emitv                (GtkObject *object,
                                                 guint signal_id,
                                                 GtkArg *params);
    void        gtk_signal_emitv_by_name        (GtkObject *object,
                                                 const gchar *name,
                                                 GtkArg *params);
    guint       gtk_signal_n_emissions          (GtkObject *object,
                                                 guint signal_id);
    guint       gtk_signal_n_emissions_by_name  (GtkObject *object,
                                                 const gchar *name);
    void        gtk_signal_emit_stop            (GtkObject *object,
                                                 guint signal_id);
    void        gtk_signal_emit_stop_by_name    (GtkObject *object,
                                                 const gchar *name);
    guint       gtk_signal_connect              (GtkObject *object,
                                                 const gchar *name,
                                                 GtkSignalFunc func,
                                                 gpointer func_data);
    guint       gtk_signal_connect_after        (GtkObject *object,
                                                 const gchar *name,
                                                 GtkSignalFunc func,
                                                 gpointer func_data);
    guint       gtk_signal_connect_object       (GtkObject *object,
                                                 const gchar *name,
                                                 GtkSignalFunc func,
                                                 GtkObject *slot_object);
    guint       gtk_signal_connect_object_after (GtkObject *object,
                                                 const gchar *name,
                                                 GtkSignalFunc func,
                                                 GtkObject *slot_object);
    guint       gtk_signal_connect_full         (GtkObject *object,
                                                 const gchar *name,
                                                 GtkSignalFunc func,
                                                 GtkCallbackMarshal marshal,
                                                 gpointer data,
                                                 GtkDestroyNotify destroy_func,
                                                 gint object_signal,
                                                 gint after);
    void        gtk_signal_connect_while_alive  (GtkObject *object,
                                                 const gchar *signal,
                                                 GtkSignalFunc func,
                                                 gpointer func_data,
                                                 GtkObject *alive_object);
    void        gtk_signal_connect_object_while_alive
                                                (GtkObject *object,
                                                 const gchar *signal,
                                                 GtkSignalFunc func,
                                                 GtkObject *alive_object);
    void        gtk_signal_disconnect           (GtkObject *object,
                                                 guint handler_id);
    void        gtk_signal_disconnect_by_func   (GtkObject *object,
                                                 GtkSignalFunc func,
                                                 gpointer data);
    void        gtk_signal_disconnect_by_data   (GtkObject *object,
                                                 gpointer data);
    void        gtk_signal_handler_block        (GtkObject *object,
                                                 guint handler_id);
    void        gtk_signal_handler_block_by_func
                                                (GtkObject *object,
                                                 GtkSignalFunc func,
                                                 gpointer data);
    void        gtk_signal_handler_block_by_data
                                                (GtkObject *object,
                                                 gpointer data);
    void        gtk_signal_handler_unblock      (GtkObject *object,
                                                 guint handler_id);
    void        gtk_signal_handler_unblock_by_func
                                                (GtkObject *object,
                                                 GtkSignalFunc func,
                                                 gpointer data);
    void        gtk_signal_handler_unblock_by_data
                                                (GtkObject *object,
                                                 gpointer data);
    guint       gtk_signal_handler_pending      (GtkObject *object,
                                                 guint signal_id,
                                                 gboolean may_be_blocked);
    guint       gtk_signal_handler_pending_by_func
                                                (GtkObject *object,
                                                 guint signal_id,
                                                 gboolean may_be_blocked,
                                                 GtkSignalFunc func,
                                                 gpointer data);
    gint        gtk_signal_handler_pending_by_id
                                                (GtkObject *object,
                                                 guint handler_id,
                                                 gboolean may_be_blocked);
    void        gtk_signal_handlers_destroy     (GtkObject *object);
    void        gtk_signal_set_funcs            (GtkSignalMarshal marshal_func,
                                                 GtkSignalDestroy destroy_func);
    GtkSignalQuery* gtk_signal_query            (guint signal_id);
    guint       gtk_signal_add_emission_hook    (guint signal_id,
                                                 GtkEmissionHook hook_func,
                                                 gpointer data);
    guint       gtk_signal_add_emission_hook_full
                                                (guint signal_id,
                                                 GtkEmissionHook hook_func,
                                                 gpointer data,
                                                 GDestroyNotify destroy);
    void        gtk_signal_remove_emission_hook (guint signal_id,
                                                 guint hook_id);

## Description

### What are signals?

Signals are a way to get notification when something happens and to customize object behavior according to the user's needs. Every signal is uniquely identified by a name, "class_name::signal_name", where signal_name might be something like "clicked" and class_name might be "GtkButton". Note that some other class may also define a "clicked" callback, so long as it doesn't derive from GtkButton.

When they are created, they are also assigned a unique positive integer, the signal id (1 is the first signal id- 0 is used to flag an error). Each is also tied to an array of types that describes the prototype of the function pointer(s) (handlers) you may connect to the signal. Finally, every signal has a default handler that is given by a function pointer in its class structure: it is run by default whenever the signal is emitted. (It is possible that a signal will be emitted and a user-defined handler will prevent the default handler from being run.)

Signals are used by everyone, but they are only created on a per class basis-- so you should call call gtk_signal_new() unless you are writing a new GtkObject type. However, if you want to make a new signal for an existing type, you may use gtk_object_class_user_signal_new() to create a signal that doesn't correspond to a class's builtin methods.

### How are signals used?

There are two basic actions in the signal handling game. If you want notification of an event, you must connect a function pointer and a data pointer to that signal; the data pointer will be passed as the last argument to the function (so long as you are using the default marshalling functions). You will receive a connection id, a unique positive integer corresponding to that attachment.

Functions that want to notify the user of certain actions, emit signals.

### Basic Terminology

signal

  A class method, e.g. GtkButton::clicked. More precisely it is a unique class-branch/signal-name pair. This means you may not define a signal handler for a class which derives from GtkButton that is called clicked, but it is okay to share signals names if they are separate in the class tree.

default handler

  The object's internal method which is invoked when the signal is emitted.

user-defined handler

  A function pointer and data connected to a signal (for a particular object).

  There are really two types: those which are connected normally, and those which are connected by one of the connect_after functions. The connect_after handlers are always run after the default handler.

  Many toolkits refer to these as callbacks.

emission

  the whole process of emitting a signal, including the invocation of all the different handler types mentioned above.

signal id

  The unique positive (nonzero) integer used to identify a signal. It can be used instead of a name to many functions for a slight performance improvement.

connection id

  The unique positive (nonzero) integer used to identify the connection of a user-defined handler to a signal. Notice that it is allowed to connect the same function-pointer/user-data pair twice, so there is no guarantee that a function-pointer/user-data maps to a unique connection id.

### A brief note on how they work.

The functions responsible for translating an array of GtkArgs to your C compiler's normal semantics are called Marshallers. They are identified by gtk_marshal_return_value__parameter_list() for example a C function returning a gboolean and taking a gint can be invoked by using gtk_marshal_BOOL__INT(). Not all possibly combinations of return/params are available, of course, so if you are writing a GtkObject with parameters you might have to write a marshaller.

## Details

### GTK_SIGNAL_OFFSET()

    #define GTK_SIGNAL_OFFSET(struct, field)	(GTK_STRUCT_OFFSET (struct, field))

`struct` : |
`field` : |

### GtkSignalMarshal ()

    void        (*GtkSignalMarshal)             (GtkObject *object,
                                                 gpointer data,
                                                 guint nparams,
                                                 GtkArg *args,
                                                 GtkType *arg_types,
                                                 GtkType return_type);

This is currently a hack left in for a scheme wrapper library. It may be removed.

Don't use it.

`object` : | The object which emits the signal.
`data` : | The user data associated with the hook.
`nparams` : | The number of parameters to the function.
`args` : | The actual values of the arguments.
`arg_types` : | The types of the arguments.
`return_type` : | The type of the return value from the function or GTK_TYPE_NONE for no return value.

### GtkSignalDestroy ()

    void        (*GtkSignalDestroy)             (gpointer data);

A function which you can use to clean up when the signal handler is destroyed.

For example, if your handler requires a few variables that you made into a struct and allocated (using g_new() or something), then you will probably want to free it as soon as the hook is destroyed. This will allow you to do that. (For this in particular it is convenient to pass g_free() as a GtkSignalDestroy function).

`data` : | The user data associated with the hook that is being destroyed.

### GtkEmissionHook ()

    gboolean    (*GtkEmissionHook)              (GtkObject *object,
                                                 guint signal_id,
                                                 guint n_params,
                                                 GtkArg *params,
                                                 gpointer data);

A simple function pointer to get invoked when the signal is emitted. This allows you tie a hook to the signal type, so that it will trap all emissions of that signal, from any object.

You may not attach these to signals created with the GTK_RUN_NO_HOOKS flag.

`object` : | the object which emits the signal.
`signal_id` : | the unique integer identify the signal type.
`n_params` : | the number of parameters to the function, not including return value.
`params` : | the parameters to the function. A pointer to the return value is passed as a last element.
`data` : | the user data associated with the hook.
Returns : | whether it wished to be removed. If it returns TRUE, the signal hook is disconnected (and destroyed).

### struct GtkSignalQuery

    struct GtkSignalQuery
    {
      GtkType	   object_type;
      guint		   signal_id;
      const gchar	  *signal_name;
      guint		   is_user_signal : 1;
      GtkSignalRunType signal_flags;
      GtkType	   return_val;
      guint		   nparams;
      const GtkType	  *params;
    };

This structure contains all the information about a particular signal: its name, the type it affects, the signature of the handlers, and its unique identifying integer.

### enum GtkSignalRunType

    typedef enum			/*< flags >*/
    {
      GTK_RUN_FIRST      = 1 << 0,
      GTK_RUN_LAST       = 1 << 1,
      GTK_RUN_BOTH       = (GTK_RUN_FIRST | GTK_RUN_LAST),
      GTK_RUN_NO_RECURSE = 1 << 2,
      GTK_RUN_ACTION     = 1 << 3,
      GTK_RUN_NO_HOOKS   = 1 << 4
    } GtkSignalRunType;

These configure the signal's emission. They control whether the signal can be emitted recursively on an object and whether to run the default method before or after the user-defined handlers.

GTK_RUN_FIRST

  Run the default handler before the connected user-defined handlers.

GTK_RUN_LAST

  Run the default handler after the connected user-defined handlers. (Handlers registered as "after" always run after the default handler though)

GTK_RUN_BOTH

  Run the default handler twice, once before the user-defined handlers, and once after.

GTK_RUN_NO_RECURSE

  Whether to prevent a handler or hook from reemitting the signal from within itself. Attempts to emit the signal while it is running will result in the signal emission being restarted once it is done with the current processing.

  You must be careful to avoid having two handlers endlessly reemitting signals, gtk_signal_n_emissions() can be helpful.

GTK_RUN_ACTION

  The signal is an action you can invoke without any particular setup or cleanup. The signal is treated no differently, but some other code can determine if the signal is appropriate to delegate to user control. For example, key binding sets only allow bindings of ACTION signals to keystrokes.

GTK_RUN_NO_HOOKS

  This prevents the connection of emission hooks to the signal.

### gtk_signal_init ()

    void        gtk_signal_init                 (void);

### gtk_signal_new ()

    guint       gtk_signal_new                  (const gchar *name,
                                                 GtkSignalRunType signal_flags,
                                                 GtkType object_type,
                                                 guint function_offset,
                                                 GtkSignalMarshaller marshaller,
                                                 GtkType return_val,
                                                 guint nparams,
                                                 ...);

Create a new signal type. (This is usually done in the class initializer.)

`name` : | the event name for the signal, e.g. "clicked".
`signal_flags` : | a combination of GTK_RUN flags specifying detail of when the default handler is to be invoked. You should at least specify GTK_RUN_FIRST or GTK_RUN_LAST.
`object_type` : | the type of object this signal pertains to. It will also pertain to derivers of this type automatically.
`function_offset` : | How many bytes the function pointer is in the class structure for this type. Used to invoke a class method generically.
`marshaller` : | the function to translate between an array of GtkArgs and the native calling convention. Usually they are identified just by the type of arguments they take: for example, gtk_marshal_BOOL__STRING() describes a marshaller which takes a string and returns a boolean value.
`return_val` : | the type of return value, or GTK_TYPE_NONE for a signal without a return value.
`nparams` : | the number of parameter the handlers may take.
`...` : | a list of GTK_TYPE_*, one for each parameter.
Returns : | the signal id.

### gtk_signal_newv ()

    guint       gtk_signal_newv                 (const gchar *name,
                                                 GtkSignalRunType signal_flags,
                                                 GtkType object_type,
                                                 guint function_offset,
                                                 GtkSignalMarshaller marshaller,
                                                 GtkType return_val,
                                                 guint nparams,
                                                 GtkType *params);

Create a new signal type. (This is usually done in a class initializer.)

This function take the types as an array, instead of a list following the arguments. Otherwise the same as gtk_signal_new().

`name` : | the name of the signal to create.
`signal_flags` : | see gtk_signal_new().
`object_type` : | the type of GtkObject to associate the signal with.
`function_offset` : | how many bytes the function pointer is in the class structure for this type.
`marshaller` : |
`return_val` : | the type of the return value, or GTK_TYPE_NONE if you don't want a return value.
`nparams` : | the number of parameters to the user-defined handlers.
`params` : | an array of GtkTypes, describing the prototype to the callbacks.
Returns : | the signal id.

### gtk_signal_lookup ()

    guint       gtk_signal_lookup               (const gchar *name,
                                                 GtkType object_type);

Given the name of the signal and the type of object it connects to, get the signal's identifying integer. Emitting the signal by number is somewhat faster than using the name each time.

It also tries the ancestors of the given type.

`name` : | the signal's name, e.g. clicked.
`object_type` : | the type that the signal operates on, e.g. GTK_TYPE_BUTTON.
Returns : | the signal's identifying number, or 0 if no signal was found.

### gtk_signal_name ()

    gchar*      gtk_signal_name                 (guint signal_id);

Given the signal's identifier, find its name.

Two different signals may have the same name, if they have differing types.

`signal_id` : | the signal's identifying number.
Returns : | the signal name, or NULL if the signal number was invalid.

### gtk_signal_emit ()

    void        gtk_signal_emit                 (GtkObject *object,
                                                 guint signal_id,
                                                 ...);

Emit a signal. This causes the default handler and user-defined handlers to be run.

Here is what gtk_signal_emit() does:

1. Calls the default handler and the user-connected handlers. The default handler will be called first if GTK_RUN_FIRST is set, and last if GTK_RUN_LAST is set.

2. Calls all handlers connected with the "after" flag set.

`object` : | the object that emits the signal.
`signal_id` : | the signal identifier.
`...` : | the parameters to the function, followed by a pointer to the return type, if any.

### gtk_signal_emit_by_name ()

    void        gtk_signal_emit_by_name         (GtkObject *object,
                                                 const gchar *name,
                                                 ...);

Emit a signal. This causes the default handler and user-connected handlers to be run.

`object` : | the object that emits the signal.
`name` : | the name of the signal.
`...` : | the parameters to the function, followed by a pointer to the return type, if any.

### gtk_signal_emitv ()

    void        gtk_signal_emitv                (GtkObject *object,
                                                 guint signal_id,
                                                 GtkArg *params);

Emit a signal. This causes the default handler and user-connected handlers to be run. This differs from gtk_signal_emit() by taking an array of GtkArgs instead of using C's varargs mechanism.

`object` : | the object to emit the signal to.
`signal_id` : | the signal identifier.
`params` : | an array of GtkArgs, one for each parameter, followed by one which is a pointer to the return type.

### gtk_signal_emitv_by_name ()

    void        gtk_signal_emitv_by_name        (GtkObject *object,
                                                 const gchar *name,
                                                 GtkArg *params);

Emit a signal by name. This causes the default handler and user-connected handlers to be run. This differs from gtk_signal_emit() by taking an array of GtkArgs instead of using C's varargs mechanism.

`object` : | the object to emit the signal to.
`name` : | the name of the signal.
`params` : | an array of GtkArgs, one for each parameter, followed by one which is a pointer to the return type.

### gtk_signal_n_emissions ()

    guint       gtk_signal_n_emissions          (GtkObject *object,
                                                 guint signal_id);

Find out the recursion depth of emissions for a particular type of signal and object. (So it will always return 0 or 1 if GTK_RUN_NO_RECURSE is specified) This is a way to avoid recursion: you can see if you are currently running in that signal handler and emit it only if you are.

Another way to look at it is that this number increases by one when #gtk_signal_emit(), et al, are called, and decreases by one when #gtk_signal_emit() returns.

`object` : | the object with the signal handler.
`signal_id` : | the signal id.
Returns : | the recursion depth of emissions of this signal for this object.

### gtk_signal_n_emissions_by_name ()

    guint       gtk_signal_n_emissions_by_name  (GtkObject *object,
                                                 const gchar *name);

Find out the recursion depth of emissions for a particular type of signal and object. Just like gtk_signal_n_emissions() except it will lookup the signal id for you.

`object` : | the object with the signal handler.
`name` : | the signal name.
Returns : | the recursion depth of emissions of this signal for this object.

### gtk_signal_emit_stop ()

    void        gtk_signal_emit_stop            (GtkObject *object,
                                                 guint signal_id);

This function aborts a signal's current emission.

It will prevent the default method from running, if the signal was GTK_RUN_LAST and you connected normally (i.e. without the "after" flag).

It will print a warning if used on a signal which isn't being emitted.

`object` : | the object whose signal handlers you wish to stop.
`signal_id` : | the signal identifier, as returned by gtk_signal_lookup().

### gtk_signal_emit_stop_by_name ()

    void        gtk_signal_emit_stop_by_name    (GtkObject *object,
                                                 const gchar *name);

This function aborts a signal's current emission.

It is just like gtk_signal_emit_stop() except it will lookup the signal id for you.

`object` : | the object whose signal handlers you wish to stop.
`name` : | the name of the signal you wish to stop.

### gtk_signal_connect ()

    guint       gtk_signal_connect              (GtkObject *object,
                                                 const gchar *name,
                                                 GtkSignalFunc func,
                                                 gpointer func_data);

Attach a function pointer and user data to a signal for a particular object.

The GtkSignalFunction takes a GtkObject as its first parameter. It will be the same object as the one you're connecting the hook to. The func_data will be passed as the last parameter to the hook.

All else being equal, signal handlers are invoked in the order connected (see gtk_signal_emit() for the other details of which order things are called in).

Here is how one passes an integer as user data, for when you just want to specify a constant int as parameter to your function:

    static void button_clicked_int(GtkButton* button, gpointer func_data)
    {
    	g_print("button pressed: d\n", GPOINTER_TO_INT(func_data));
    }

    /* By calling this function, you will make the g_print above
     * execute, printing the number passed as `to_print'. */
    static void attach_print_signal(GtkButton* button, gint to_print)
    {
    	gtk_signal_connect(GTK_OBJECT(button), "clicked",
    		GTK_SIGNAL_FUNC(button_clicked_int),
    		GINT_TO_POINTER(to_print));
    }

`object` : | the object associated with the signal, e.g. if a button is getting pressed, this is that button.
`name` : | name of the signal.
`func` : | function pointer to attach to the signal.
`func_data` : | value to pass as to your function (through the marshaller).
Returns : | the connection id.

### gtk_signal_connect_after ()

    guint       gtk_signal_connect_after        (GtkObject *object,
                                                 const gchar *name,
                                                 GtkSignalFunc func,
                                                 gpointer func_data);

Attach a function pointer and user data to a signal so that this handler will be called after the other handlers.

`object` : | the object associated with the signal.
`name` : | name of the signal.
`func` : | function pointer to attach to the signal.
`func_data` : | value to pass as to your function (through the marshaller).
Returns : | the unique identifier for this attachment: the connection id.

### gtk_signal_connect_object ()

    guint       gtk_signal_connect_object       (GtkObject *object,
                                                 const gchar *name,
                                                 GtkSignalFunc func,
                                                 GtkObject *slot_object);

This function is for registering a callback that will call another object's callback. That is, instead of passing the object which is responsible for the event as the first parameter of the callback, it is switched with the user data (so the object which emits the signal will be the last parameter, which is where the user data usually is).

This is useful for passing a standard function in as a callback. For example, if you wanted a button's press to gtk_widget_show() some widget, you could write:

    gtk_signal_connect_object(button, "clicked", gtk_widget_show, window);

`object` : | the object which emits the signal.
`name` : | the name of the signal.
`func` : | the function to callback.
`slot_object` : | the object to pass as the first parameter to func. (Though it pretends to take an object, you can really pass any gpointer as the slot_object .)
Returns : | the connection id.

### gtk_signal_connect_object_after ()

    guint       gtk_signal_connect_object_after (GtkObject *object,
                                                 const gchar *name,
                                                 GtkSignalFunc func,
                                                 GtkObject *slot_object);

Attach a signal hook to a signal, passing in an alternate object as the first parameter, and guaranteeing that the default handler and all normal handlers are called first.

`object` : | the object associated with the signal.
`name` : | name of the signal.
`func` : | function pointer to attach to the signal.
`slot_object` : | the object to pass as the first parameter to func.
Returns : | the connection id.

### gtk_signal_connect_full ()

    guint       gtk_signal_connect_full         (GtkObject *object,
                                                 const gchar *name,
                                                 GtkSignalFunc func,
                                                 GtkCallbackMarshal marshal,
                                                 gpointer data,
                                                 GtkDestroyNotify destroy_func,
                                                 gint object_signal,
                                                 gint after);

Attach a function pointer and user data to a signal with more control.

`object` : | the object which emits the signal. For example, a button in the button press signal.
`name` : | the name of the signal.
`func` : | function pointer to attach to the signal.
`marshal` : | the function marshal, see the gtkmarshall documentation for more details, but briefly: the marshaller is a function which takes the GtkObject which emits the signal, the user data, the number of the arguments, and the array of arguments. It is responsible for calling the function in the appropriate calling convention. gtk_signal_default_marshaller is usually fine. (This shows up, for example, when worrying about matching c++ or other languages' calling conventions.)
`data` : | the user data associated with the function.
`destroy_func` : | function to call when this particular hook is disconnected.
`object_signal` : | whether this is an object signal-- basically an "object signal" is one that wants its user_data and object fields switched, which is useful for calling functions which operate on another object primarily.
`after` : | whether to invoke the user-defined handler after the signal, or to let the signal's default behavior preside (i.e. depending on GTK_RUN_FIRST and GTK_RUN_LAST).
Returns : | the connection id.

### gtk_signal_connect_while_alive ()

    void        gtk_signal_connect_while_alive  (GtkObject *object,
                                                 const gchar *signal,
                                                 GtkSignalFunc func,
                                                 gpointer func_data,
                                                 GtkObject *alive_object);

Attach a function pointer and another GtkObject to a signal.

This function takes an object whose "destroy" signal should be trapped. That way, you don't have to clean up the signal handler when you destroy the object. It is a little less efficient though.

(Instead you may call gtk_signal_disconnect_by_data(), if you want to explicitly delete all attachments to this object. This is perhaps not recommended since it could be confused with an integer masquerading as a pointer (through GINT_AS_POINTER).)

`object` : | the object that emits the signal.
`signal` : |
`func` : | function pointer to attach to the signal.
`func_data` : | pointer to pass to func.
`alive_object` : | object whose death should cause the handler connection to be destroyed.

### gtk_signal_connect_object_while_alive ()

    void        gtk_signal_connect_object_while_alive
                                                (GtkObject *object,
                                                 const gchar *signal,
                                                 GtkSignalFunc func,
                                                 GtkObject *alive_object);

These signal connectors are for signals which refer to objects, so they must not be called after the object is deleted.

Unlike gtk_signal_connect_while_alive(), this swaps the object and user data, making it suitable for use with functions which primarily operate on the user data.

This function acts just like gtk_signal_connect_object() except it traps the "destroy" signal to prevent you from having to clean up the handler.

`object` : | the object associated with the signal.
`signal` : |
`func` : | function pointer to attach to the signal.
`alive_object` : | the user data, which must be an object, whose destruction should signal the removal of this signal.

### gtk_signal_disconnect ()

    void        gtk_signal_disconnect           (GtkObject *object,
                                                 guint handler_id);

Destroy a user-defined handler connection.

`object` : | the object which the handler pertains to.
`handler_id` : | the connection id.

### gtk_signal_disconnect_by_func ()

    void        gtk_signal_disconnect_by_func   (GtkObject *object,
                                                 GtkSignalFunc func,
                                                 gpointer data);

Destroy all connections for a particular object, with the given function-pointer and user-data.

`object` : | the object which emits the signal.
`func` : | the function pointer to search for.
`data` : | the user data to search for.

### gtk_signal_disconnect_by_data ()

    void        gtk_signal_disconnect_by_data   (GtkObject *object,
                                                 gpointer data);

Destroy all connections for a particular object, with the given user-data.

`object` : | the object which emits the signal.
`data` : | the user data to search for.

### gtk_signal_handler_block ()

    void        gtk_signal_handler_block        (GtkObject *object,
                                                 guint handler_id);

Prevent an user-defined handler from being invoked. All other signal processing will go on as normal, but this particular handler will ignore it.

`object` : | the object which emits the signal to block.
`handler_id` : | the connection id.

### gtk_signal_handler_block_by_func ()

    void        gtk_signal_handler_block_by_func
                                                (GtkObject *object,
                                                 GtkSignalFunc func,
                                                 gpointer data);

Prevent a user-defined handler from being invoked, by reference to the user-defined handler's function pointer and user data. (It may result in multiple hooks being blocked, if you've called connect multiple times.)

`object` : | the object which emits the signal to block.
`func` : | the function pointer of the handler to block.
`data` : | the user data of the handler to block.

### gtk_signal_handler_block_by_data ()

    void        gtk_signal_handler_block_by_data
                                                (GtkObject *object,
                                                 gpointer data);

Prevent all user-defined handlers with a certain user data from being invoked.

`object` : | the object which emits the signal we want to block.
`data` : | the user data of the handlers to block.

### gtk_signal_handler_unblock ()

    void        gtk_signal_handler_unblock      (GtkObject *object,
                                                 guint handler_id);

Undo a block, by connection id. Note that undoing a block doesn't necessarily make the hook callable, because if you block a hook twice, you must unblock it twice.

`object` : | the object which emits the signal we want to unblock.
`handler_id` : | the emission handler identifier, as returned by gtk_signal_connect(), etc.

### gtk_signal_handler_unblock_by_func ()

    void        gtk_signal_handler_unblock_by_func
                                                (GtkObject *object,
                                                 GtkSignalFunc func,
                                                 gpointer data);

Undo a block, by function pointer and data. Note that undoing a block doesn't necessarily make the hook callable, because if you block a hook twice, you must unblock it twice.

`object` : | the object which emits the signal we want to unblock.
`func` : | the function pointer to search for.
`data` : | the user data to search for.

### gtk_signal_handler_unblock_by_data ()

    void        gtk_signal_handler_unblock_by_data
                                                (GtkObject *object,
                                                 gpointer data);

Undo block(s), to all signals for a particular object with a particular user-data pointer

`object` : | the object which emits the signal we want to unblock.
`data` : | the user data to search for.

### gtk_signal_handler_pending ()

    guint       gtk_signal_handler_pending      (GtkObject *object,
                                                 guint signal_id,
                                                 gboolean may_be_blocked);

Returns a connection id corresponding to a given signal id and object.

One example of when you might use this is when the arguments to the signal are difficult to compute. A class implementor may opt to not emit the signal if no one is attached anyway, thus saving the cost of building the arguments.

`object` : | the object to search for the desired user-defined handler.
`signal_id` : | the number of the signal to search for.
`may_be_blocked` : | whether it is acceptable to return a blocked handler.
Returns : | the connection id, if a connection was found. 0 otherwise.

### gtk_signal_handler_pending_by_func ()

    guint       gtk_signal_handler_pending_by_func
                                                (GtkObject *object,
                                                 guint signal_id,
                                                 gboolean may_be_blocked,
                                                 GtkSignalFunc func,
                                                 gpointer data);

Returns a connection id corresponding to a given signal id, object, function pointer and user data.

`object` : | the object to search for the desired handler.
`signal_id` : | the number of the signal to search for.
`may_be_blocked` : | whether it is acceptable to return a blocked handler.
`func` : | the function pointer to search for.
`data` : | the user data to search for.
Returns : | the connection id, if a handler was found. 0 otherwise.

### gtk_signal_handler_pending_by_id ()

    gint        gtk_signal_handler_pending_by_id
                                                (GtkObject *object,
                                                 guint handler_id,
                                                 gboolean may_be_blocked);

Returns whether a connection id is valid (and optionally not blocked).

`object` : | the object to search for the desired handler.
`handler_id` : | the connection id.
`may_be_blocked` : | whether it is acceptable to return a blocked handler.
Returns : | TRUE if the signal exists and wasn't blocked, unless may_be_blocked was specified. FALSE otherwise.

### gtk_signal_handlers_destroy ()

    void        gtk_signal_handlers_destroy     (GtkObject *object);

Destroy all the signal handlers connected to an object. This is done automatically when the object is destroyed.

This function is labeled private.

`object` : | the object whose signal handlers should be destroyed.

### gtk_signal_set_funcs ()

    void        gtk_signal_set_funcs            (GtkSignalMarshal marshal_func,
                                                 GtkSignalDestroy destroy_func);

These set default functions to call when the user didn't supply a function when connecting. (These are rarely used, and probably only for language bindings)

By default, there are no such functions.

`marshal_func` : | the function to invoke on every handlers for which there isn't a function pointer. May be NULL.
`destroy_func` : | the function to invoke when each hook is destroyed. May be NULL.

### gtk_signal_query ()

    GtkSignalQuery* gtk_signal_query            (guint signal_id);

Obtain information about a signal.

`signal_id` : | the signal type identifier.
Returns : | a pointer to a GtkSignalQuery structure which contains all the information, or NULL. The pointer is allocated just for you: you must g_free() it.

### gtk_signal_add_emission_hook ()

    guint       gtk_signal_add_emission_hook    (guint signal_id,
                                                 GtkEmissionHook hook_func,
                                                 gpointer data);

Add an emission hook for a type of signal, for any object.

`signal_id` : | the type of signal to hook for.
`hook_func` : | the function to invoke to handle the emission hook.
`data` : | the user data passed in to hook_func.
Returns : | the id (that you may pass as a parameter to gtk_signal_remove_emission_hook()).

### gtk_signal_add_emission_hook_full ()

    guint       gtk_signal_add_emission_hook_full
                                                (guint signal_id,
                                                 GtkEmissionHook hook_func,
                                                 gpointer data,
                                                 GDestroyNotify destroy);

Add an emission hook for a type of signal, for any object. (with control of what happens when the hook is destroyed).

`signal_id` : | the type of signal add the hook for.
`hook_func` : | the function to invoke to handle the hook.
`data` : | the user data passed in to hook_func.
`destroy` : | a function to invoke when the hook is destroyed, to clean up any allocation done just for this signal handler.
Returns : | the id (that you may pass as a parameter to gtk_signal_remove_emission_hook()).

### gtk_signal_remove_emission_hook ()

    void        gtk_signal_remove_emission_hook (guint signal_id,
                                                 guint hook_id);

Delete an emission hook. (see gtk_signal_add_emission_hook())

`signal_id` : | the id of the signal type.
`hook_id` : | the id of the emission handler, returned by add_emission_hook().

## See Also

GtkObject

  The base class for things which emit signals.

<<< Previous Page | Home | Up | Next Page >>>
Drag and Drop | Signal Marshallers