GNU Info
(gtk.info)Signals
Signals Overview
****************
Signals are GTK's method for objects to perform callbacks. A signal
is an event which occurs upon an object. The programmer can connect to a
signal of an object which involves specifying a function to be called
when that signal is emitted in the specified object.
When a signal is emitted, both the class function associated with the
signal (when it was defined) and all signal handlers installed for that
signal on the particular object emitting the signal are called. The
widget programmer can specify whether the class function is to be called
before after or both before and after the signal handlers installed by
the widget user. The widget user can, however, specify that their signal
handler is to be run after the class function (using the "_after"
signal connection routines). Any signal handling function can emit the
same signal on the same object while it is running causing that signal
emission to either restart or to run recursively. Additionally, signal
emission can be terminated prematurely. While both such abilities are
rarely used, they do allow for greater flexibility in regards to
signals. For instance, a programmer can attach to the key press event
signal and intercept all tab key presses from a widget. This particular
example is used in the file selection dialog to implement tab completion
of filenames and prevent the entry widget from inserting the tab into
its buffer.
Signals are selected using either an integer identifier or a
character string name. It is convention to name the signal the same as
the class function which is associated with it. There are two versions
of most of the signal functions, one which takes an integer identifier
and one which takes a character string name for the signal.
- Function: gint gtk_signal_new (gchar *NAME, GtkSignalRunType
RUN_TYPE, gint OBJECT_TYPE, gint FUNCTION_OFFSET,
GtkSignalMarshaller MARSHALLER, GtkParamType RETURN_VAL, gint
NPARAMS, ...)
Create a new signal and give it the character string identifier
NAME. NAME needs to be unique in the context of OBJECT_TYPE's
branch of the class hierarchy. That is, OBJECT_TYPE cannot create
a signal type with the same name as a signal type created by one
of its parent types.
RUN_TYPE specifies whether the class function should be run before
(`GTK_RUN_FIRST'), after (`GTK_RUN_LAST') or both before and after
normal signal handlers (`GTK_RUN_BOTH'). Additionally, the
`GTK_RUN_NO_RECURSE' value can be or'ed with any of those values to
specify that the signal should not be recursive. By default,
emitting the same signal on the same widget will cause the signal
to be emitted twice. However, if the `GTK_RUN_NO_RECURSE' flag is
specified, emitting the same signal on the same widget will cause
the current signal emission to be restarted. This allows the
widget programmer to specify the semantics of signal emission on a
per signal basis. (The `GTK_RUN_NO_RECURSE' flag is used by the
GtkAdjustment widget).
The FUNCTION_OFFSET is the byte offset from the start of the class
structure to the class function field within the class structure.
The easiest means to compute this offset is by using the
`GTK_SIGNAL_OFFSET' macro which takes the class structure type as
the first argument and the field as the second argument. For
example, `GTK_SIGNAL_OFFSET (GtkObjectClass, destroy)' will give
the offset of the `destroy' class function within the
`GtkObjectClass'. Note: An offset is specified instead of an
absolute location since there will be multiple instances of a class
structure being referenced. (The `GtkWidgetClass' structure "is a"
`GtkObjectClass' structure, etc.)
The MARSHALLER function is used to invoke a signal handler. Since
signal handlers may take different parameters and return values
and a general mechanism for invoking them is not apparent, the
approach of making the signal creator responsible for invoking the
signal handler was taken. (FIXME: unfinished).
The RETURN_VAL and NPARAMS and the remaining arguments specify the
return value and the arguments to the signal handler respectively.
Note: There is an implicit first argument to every signal handler
which is the widget the signal has been emitted from. The variable
argument list (...) specifies the types of the arguments. These
can be one of `GTK_PARAM_CHAR', `GTK_PARAM_SHORT',
`GTK_PARAM_INT', `GTK_PARAM_LONG', `GTK_PARAM_POINTER' or
`GTK_PARAM_FUNCTION'. It is undefined to specify `GTK_PARAM_NONE'
as an argument type, however it is OK to use `GTK_PARAM_NONE' for
RETURN_VAL. (This corresponds to returning a `void').
`gtk_signal_new' returns the integer identifier of the newly
created signal. Signal identifiers start numbering at 1 and
increase upwards. A value of -1 will be returned if an error
occurs.
*Note:* `gtk_signal_new' is only needed by widget writers. A
normal user of GTK will never needed to invoke this function.
- Function: gint gtk_signal_lookup (gchar *NAME, gint OBJECT_TYPE)
Returns the integer identifier for the signal referenced by NAME
and OBJECT_TYPE. If OBJECT_TYPE does not define the signal NAME,
then the signal is looked for in OBJECT_TYPE's parent type
recursively.
- Function: gchar* gtk_signal_name (gint SIGNAL_NUM)
- Function: gint gtk_signal_emit (GtkObject *OBJECT, gint SIGNAL_TYPE,
...)
Emit the signal specified by the integer identifier SIGNAL_TYPE
from OBJECT. If an error occurs, `gtk_signal_emit' will return
`FALSE' and will return `TRUE' on success. The signal definition
determines the parameters passed in the variable argument list
(`...'). For example, if the signal is defined as:
gint (* event) (GtkWidget *widget, GdkEvent *event);
Then a call to emit the "event" signal would look like:
GdkEvent event;
gint return_val;
...
gtk_signal_emit (some_object,
gtk_signal_lookup ("event",
GTK_OBJECT_TYPE (some_object)),
&event, &return_val);
Notice that the `widget' argument is implicit in that the first
argument to every signal is a type derived from `GtkObject'. The
RETURN_VAL argument is actually a pointer to the return value type
since the signal mechanism needs to be able to place the return
value in an actual location. And lastly, the `gtk_signal_lookup'
call is normally avoided by using the `gtk_signal_emit_by_name'
function instead. `gtk_signal_emit' is normally used internally by
widgets which know the signal identifier (since they defined the
signal) and can therefore side-step the cost of calling
`gtk_signal_lookup'.
- Function: gint gtk_signal_emit_by_name (GtkObject *OBJECT, gchar
*NAME, ...)
Similar to `gtk_signal_emit' except that the signal is referenced
by NAME instead of by its integer identifier.
- Function: void gtk_signal_emit_stop (GtkObject *OBJECT, gint
SIGNAL_TYPE)
Stop the emission of the signal SIGNAL_TYPE on OBJECT. SIGNAL_TYPE
is the integer identifier for the signal and can be determined
using the function `gtk_signal_lookup'. Alternatively, the function
`gtk_signal_emit_stop_by_name' can be used to refer to the signal
by name. Attempting to stop the emission of a signal that isn't
being emitted does nothing.
- Function: void gtk_signal_emit_stop_by_name (GtkObject *OBJECT,
gchar *NAME)
Similar to `gtk_signal_emit_stop' except that the signal is
referenced by NAME instead of by its integer identifier.
- Function: gint gtk_signal_connect (GtkObject *OBJECT, gchar *NAME,
GtkSignalFunc FUNC, gpointer FUNC_DATA)
Connects a signal handling function to a signal emitting object.
FUNC is connected to the signal NAME emitted by OBJECT. The
arguments and returns type of FUNC should match the arguments and
return type of the signal NAME. However, FUNC may take the extra
argument of FUNC_DATA. Due to the C calling convention it is OK to
ignore the extra argument. (It is OK to ignore all the arguments
in fact).
`gtk_signal_connect' returns an integer identifier for the
connection which can be used to refer to it in the future.
Specifically it is useful for removing the connection and/or
blocking it from being used.
- Function: gint gtk_signal_connect_after (GtkObject *OBJECT, gchar
*NAME, GtkSignalFunc FUNC, gpointer FUNC_DATA)
Similar to `gtk_signal_connect' except the signal handler is
connected in the "after" slot. This allows a signal handler to be
guaranteed to run after other signal handlers connected to the same
signal on the same object and after the class function associated
with the signal.
Like `gtk_signal_connect', `gtk_signal_connect_after' returns an
integer identifier which can be used to refer to the connection.
- Function: gint gtk_signal_connect_object (GtkObject *OBJECT, gchar
*NAME, GtkSignalFunc FUNC, GtkObject *SLOT_OBJECT)
Connects FUNC to the signal NAME emitted by OBJECT. Similar to
`gtk_signal_connect' with the difference that SLOT_OBJECT is
passed as the first parameter to FUNC instead of the signal
emitting object. This can be useful for connecting a signal
emitted by one object to a signal in another object. A common
usage is to connect the "destroy" signal of dialog to the "clicked"
signal emitted by a "close" button in the dialog. That is, the
"clicked" signal emitted by the button will caused the "destroy"
signal to be emitted for the dialog. This is also the "right" way
to handle closing of a dialog since the "destroy" signal will be
sent if the dialog is deleted using a window manager function and
this enables the two methods of closing the window to be handled
by the same mechanism. Returns an integer identifier which can be
used to refer to the connection.
- Function: gint gtk_signal_connect_object_after (GtkObject *OBJECT,
gchar *NAME, GtkSignalFunc FUNC, GtkObject *SLOT_OBJECT)
Similar to `gtk_signal_connect_object' except the signal handler is
connected in the "after" slot. This allows a signal handler to be
guaranteed to run after other signal handlers connected to the same
signal on the same object and after the class function associated
with the signal. Returns an integer identifier which can be used
to refer to the connection.
- Function: gint gtk_signal_connect_interp (GtkObject *OBJECT, gchar
*NAME, GtkCallbackMarshal FUNC, gpointer DATA,
GtkDestroyNotify DESTROY_FUNC, gint AFTER)
- Function: void gtk_signal_disconnect (GtkObject *OBJECT, gint ID)
Disconnects a signal handler from an object. The signal handler is
identified by the integer ID which is returned by the
`gtk_signal_connect*' family of functions.
- Function: void gtk_signal_disconnect_by_data (GtkObject *OBJECT,
gpointer DATA)
Disconnects a signal handler from an object. The signal handler is
identified by the DATA argument specified as the FUNC_DATA
argument to the `gtk_signal_connect*' family of functions. For the
`gtk_signal_connect_object*' functions, DATA refers to the
SLOT_OBJECT.
*Note:* This will remove all signal handlers connected to OBJECT
which were connected using DATA as their FUNC_DATA argument.
Multiple signal handlers may be disconnected with this call.
- Function: void gtk_signal_handler_block (GtkObject *OBJECT, gint ID)
Blocks calling of a signal handler during signal emission. The
signal handler is identified by the integer ID which is returned
by the `gtk_signal_connect*' family of functions. If the signal is
already blocked no change is made.
- Function: void gtk_signal_handler_block_by_data (GtkObject *OBJECT,
gint DATA)
Blocks calling of a signal handler during signal emission. The
signal handler is identified by the DATA argument specified as the
FUNC_DATA argument to the `gtk_signal_connect*' family of
functions. For the `gtk_signal_connect_object*' functions, DATA
refers to the SLOT_OBJECT. If the signal is already blocked no
change is made.
*Note:* This will block all signal handlers connected to OBJECT
which were connected using DATA as their FUNC_DATA argument.
Multiple signal handlers may be blocked with this call.
- Function: void gtk_signal_handler_unblock (GtkObject *OBJECT, gint
ID)
Unblocks calling of a signal handler during signal emission. The
signal handler is identified by the integer ID which is returned
by the `gtk_signal_connect*' family of functions. If the signal is
already unblocked no change is made.
- Function: void gtk_signal_handler_unblock_by_data (GtkObject
*OBJECT, gint DATA)
Unblocks calling of a signal handler during signal emission. The
signal handler is identified by the DATA argument specified as the
FUNC_DATA argument to the `gtk_signal_connect*' family of
functions. For the `gtk_signal_connect_object*' functions, DATA
refers to the SLOT_OBJECT. If the signal is already unblocked no
change is made.
*Note:* This will unblock all signal handlers connected to OBJECT
which were connected using DATA as their FUNC_DATA argument.
Multiple signal handlers may be unblocked with this call.
- Function: void gtk_signal_handlers_destroy (GtkObject *OBJECT)
Destroy all of the signal handlers connected to OBJECT. There
should normally never be reason to call this function as it is
called automatically when OBJECT is destroyed.
- Function: void gtk_signal_default_marshaller (GtkObject *OBJECT,
GtkSignalFunc FUNC, gpointer FUNC_DATA, GtkSignalParam
*PARAMS)
`gtk_signal_new' requires a callback in order to actually call a
signal handler for a particular signal. The vast majority of
signals are of the particular form:
(* std_signal) (gpointer std_arg);
`gtk_signal_default_marshaller' is a signal marshaller which
marshals arguments for a signal of that form.
- Function: void gtk_signal_set_funcs (GtkSignalMarshal MARSHAL_FUNC,
GtkSignalDestroy DESTROY_FUN)
automatically generated by info2www version 1.2.2.9