Signals

Name

Signals -- Object methods and callbacks.

Synopsis


#include <gtk/gtk.h>


#define     GTK_SIGNAL_OFFSET
enum        GtkSignalRunType;
guint       gtk_signal_new                  (const gchar *name,
                                             GtkSignalRunType signal_flags,
                                             GtkType object_type,
                                             guint function_offset,
                                             GtkSignalMarshaller marshaller,
                                             GtkType return_val,
                                             guint n_args,
                                             ...);
guint       gtk_signal_newv                 (const gchar *name,
                                             GtkSignalRunType signal_flags,
                                             GtkType object_type,
                                             guint function_offset,
                                             GtkSignalMarshaller marshaller,
                                             GtkType return_val,
                                             guint n_args,
                                             GtkType *args);
#define     gtk_signal_lookup               (name,object_type)
#define     gtk_signal_name                 (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 *args);
void        gtk_signal_emitv_by_name        (GtkObject *object,
                                             const gchar *name,
                                             GtkArg *args);
#define     gtk_signal_emit_stop            (object,signal_id)
void        gtk_signal_emit_stop_by_name    (GtkObject *object,
                                             const gchar *name);
#define     gtk_signal_connect              (object,name,func,func_data)
#define     gtk_signal_connect_after        (object,name,func,func_data)
#define     gtk_signal_connect_object       (object,name,func,slot_object)
#define     gtk_signal_connect_object_after (object,name,func,slot_object)
gulong      gtk_signal_connect_full         (GtkObject *object,
                                             const gchar *name,
                                             GtkSignalFunc func,
                                             GtkCallbackMarshal unsupported,
                                             gpointer data,
                                             GtkDestroyNotify destroy_func,
                                             gint object_signal,
                                             gint after);
void        gtk_signal_connect_while_alive  (GtkObject *object,
                                             const gchar *name,
                                             GtkSignalFunc func,
                                             gpointer func_data,
                                             GtkObject *alive_object);
void        gtk_signal_connect_object_while_alive
                                            (GtkObject *object,
                                             const gchar *name,
                                             GtkSignalFunc func,
                                             GtkObject *alive_object);
#define     gtk_signal_disconnect           (object,handler_id)
#define     gtk_signal_disconnect_by_func   (object,func,data)
#define     gtk_signal_disconnect_by_data   (object,data)
#define     gtk_signal_handler_block        (object,handler_id)
#define     gtk_signal_handler_block_by_func(object,func,data)
#define     gtk_signal_handler_block_by_data(object,data)
#define     gtk_signal_handler_unblock      (object,handler_id)
#define     gtk_signal_handler_unblock_by_func(object,func,data)
#define     gtk_signal_handler_unblock_by_data(object,data)
#define     gtk_signal_handler_pending      (object,signal_id,may_be_blocked)
#define     gtk_signal_handler_pending_by_func(object,signal_id,may_be_blocked,func,data)
#define     gtk_signal_default_marshaller

Description

The GTK+ signal system merely proxies the GLib signal system now. For future usage, direct use of the GSignal API is recommended, this avoids significant performance hits where GtkArg structures have to be converted into GValues.

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 not 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	                      GTK_STRUCT_OFFSET

Warning

GTK_SIGNAL_OFFSET is deprecated and should not be used in newly-written code.

Use in place of offsetof(), which is used if it exists.


enum GtkSignalRunType

typedef enum			/*< flags >*/
{
  GTK_RUN_FIRST      = G_SIGNAL_RUN_FIRST,
  GTK_RUN_LAST       = G_SIGNAL_RUN_LAST,
  GTK_RUN_BOTH       = (GTK_RUN_FIRST | GTK_RUN_LAST),
  GTK_RUN_NO_RECURSE = G_SIGNAL_NO_RECURSE,
  GTK_RUN_ACTION     = G_SIGNAL_ACTION,
  GTK_RUN_NO_HOOKS   = G_SIGNAL_NO_HOOKS
} GtkSignalRunType;

Warning

GtkSignalRunType is deprecated and should not be used in newly-written code.

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_new ()

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

Warning

gtk_signal_new is deprecated and should not be used in newly-written code.

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


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 n_args,
                                             GtkType *args);

Warning

gtk_signal_newv is deprecated and should not be used in newly-written code.

Creates 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().


gtk_signal_lookup()

#define     gtk_signal_lookup(name,object_type)

Warning

gtk_signal_lookup is deprecated and should not be used in newly-written code.

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.


gtk_signal_name()

#define     gtk_signal_name(signal_id)

Warning

gtk_signal_name is deprecated and should not be used in newly-written code.

Given the signal's identifier, finds its name.

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


gtk_signal_emit ()

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

Warning

gtk_signal_emit is deprecated and should not be used in newly-written code.

Emits 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.


gtk_signal_emit_by_name ()

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

Warning

gtk_signal_emit_by_name is deprecated and should not be used in newly-written code.

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


gtk_signal_emitv ()

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

Warning

gtk_signal_emitv is deprecated and should not be used in newly-written code.

Emits 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.


gtk_signal_emitv_by_name ()

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

Warning

gtk_signal_emitv_by_name is deprecated and should not be used in newly-written code.

Emits 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.


gtk_signal_emit_stop()

#define     gtk_signal_emit_stop(object,signal_id)

Warning

gtk_signal_emit_stop is deprecated and should not be used in newly-written code.

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.


gtk_signal_emit_stop_by_name ()

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

Warning

gtk_signal_emit_stop_by_name is deprecated and should not be used in newly-written code.

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.


gtk_signal_connect()

#define     gtk_signal_connect(object,name,func,func_data)

Warning

gtk_signal_connect is deprecated and should not be used in newly-written code.

Attaches 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:


gtk_signal_connect_after()

#define     gtk_signal_connect_after(object,name,func,func_data)

Warning

gtk_signal_connect_after is deprecated and should not be used in newly-written code.

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


gtk_signal_connect_object()

#define     gtk_signal_connect_object(object,name,func,slot_object)

Warning

gtk_signal_connect_object is deprecated and should not be used in newly-written code.

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_after()

#define     gtk_signal_connect_object_after(object,name,func,slot_object)

Warning

gtk_signal_connect_object_after is deprecated and should not be used in newly-written code.

Attaches 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.


gtk_signal_connect_full ()

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

Warning

gtk_signal_connect_full is deprecated and should not be used in newly-written code.

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


gtk_signal_connect_while_alive ()

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

Warning

gtk_signal_connect_while_alive is deprecated and should not be used in newly-written code.

Attaches 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_TO_POINTER()).)


gtk_signal_connect_object_while_alive ()

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

Warning

gtk_signal_connect_object_while_alive is deprecated and should not be used in newly-written code.

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.


gtk_signal_disconnect()

#define     gtk_signal_disconnect(object,handler_id)

Warning

gtk_signal_disconnect is deprecated and should not be used in newly-written code.

Destroys a user-defined handler connection.


gtk_signal_disconnect_by_func()

#define     gtk_signal_disconnect_by_func(object,func,data)

Warning

gtk_signal_disconnect_by_func is deprecated and should not be used in newly-written code.

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


gtk_signal_disconnect_by_data()

#define     gtk_signal_disconnect_by_data(object,data)

Warning

gtk_signal_disconnect_by_data is deprecated and should not be used in newly-written code.

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


gtk_signal_handler_block()

#define     gtk_signal_handler_block(object,handler_id)

Warning

gtk_signal_handler_block is deprecated and should not be used in newly-written code.

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


gtk_signal_handler_block_by_func()

#define     gtk_signal_handler_block_by_func(object,func,data)

Warning

gtk_signal_handler_block_by_func is deprecated and should not be used in newly-written code.

Prevents 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.)


gtk_signal_handler_block_by_data()

#define     gtk_signal_handler_block_by_data(object,data)

Warning

gtk_signal_handler_block_by_data is deprecated and should not be used in newly-written code.

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


gtk_signal_handler_unblock()

#define     gtk_signal_handler_unblock(object,handler_id)

Warning

gtk_signal_handler_unblock is deprecated and should not be used in newly-written code.

Undoes 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.


gtk_signal_handler_unblock_by_func()

#define     gtk_signal_handler_unblock_by_func(object,func,data)

Warning

gtk_signal_handler_unblock_by_func is deprecated and should not be used in newly-written code.

Undoes 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.


gtk_signal_handler_unblock_by_data()

#define     gtk_signal_handler_unblock_by_data(object,data)

Warning

gtk_signal_handler_unblock_by_data is deprecated and should not be used in newly-written code.

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


gtk_signal_handler_pending()

#define     gtk_signal_handler_pending(object,signal_id,may_be_blocked)

Warning

gtk_signal_handler_pending is deprecated and should not be used in newly-written code.

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.


gtk_signal_handler_pending_by_func()

#define     gtk_signal_handler_pending_by_func(object,signal_id,may_be_blocked,func,data)

Warning

gtk_signal_handler_pending_by_func is deprecated and should not be used in newly-written code.

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


gtk_signal_default_marshaller

#define	gtk_signal_default_marshaller	g_cclosure_marshal_VOID__VOID

Warning

gtk_signal_default_marshaller is deprecated and should not be used in newly-written code.

A marshaller that returns void and takes no extra parameters.

See Also

GtkObject

The base class for things which emit signals.

GSignal

The GLib signal system.