GSignal: The GSignal API

Description

The basic concept of the signal system is that of the emission of a signal. Signals are introduced per-type and are identified through strings. Signals introduced for a parent type are available in derived types as well, so basically they are a per-type facility that is inherited.

Usage

gSignalConnect(obj, signal, f, data = NULL, after = FALSE, user.data.first = FALSE)
gSignalHandlerDisconnect(obj, id)
gSignalHandlerBlock(obj, id)
gSignalHandlerUnblock(obj, id)
gSignalEmit(obj, signal, ..., detail = NULL)
gSignalStopEmission(obj, signal, detail = NULL)
gSignalGetInfo(sig)

Arguments

obj

The object that owns the signal

signal

The detailed name of the signal

The R function to connect as a callback

data

Arbitrary "user data" that will be passed to the callback f

after

Whether f will be called before or after the default handler

user.data.first

Whether the data is the first or last argument to the callback

The signal handler id obtained upon connection to the signal

...

Arguments to pass to the signal handlers

detail

Optional separate argument for the detail portion of the signal

sig

A signal id provided by gObjectGetSignals.

Value

gSignalConnect returns a numeric id for the signal handler. It is used for blocking and disconnecting the handler.
gSignalGetInfo returns detailed information about a signal. The returned list contains the following elements:
returnTypeThe return GType id of the signal
signalThe signal id
parametersA list of GType ids for the parameters
objectTypeThe GType id owning the signal
runFlagsThe flags determining behavior of the signal, see reference

Details

A signal emission mainly involves invocation of a certain set of callbacks in precisely defined manner. There are two main categories of such callbacks, per-object ones and user provided ones. The per-object callbacks are most often referred to as "object method handler" or "default (signal) handler", while user provided callbacks are usually just called "signal handler". The object method handler is provided at signal creation time (this most frequently happens at the end of an object class' creation), while user provided handlers are frequently connected and disconnected to/from a certain signal on certain object instances.

A signal emission consists of five stages, unless prematurely stopped:

Invocation of the object method handler forG_SIGNAL_RUN_FIRSTsignals
Invocation of normal user-provided signal handlers (afterflagFALSE)
Invocation of the object method handler forG_SIGNAL_RUN_LASTsignals
Invocation of user provided signal handlers, connected with anafterflag ofTRUE
Invocation of the object method handler forG_SIGNAL_RUN_CLEANUPsignals

The user-provided signal handlers are called in the order they were connected in. All handlers may prematurely stop a signal emission, and any number of handlers may be connected, disconnected, blocked or unblocked during a signal emission. There are certain criteria for skipping user handlers in stages 2 and 4 of a signal emission. First, user handlers may be blocked, blocked handlers are omitted during callback invocation, to return from the "blocked" state, a handler has to get unblocked exactly the same amount of times it has been blocked before. Second, upon emission of a G_SIGNAL_DETAILED signal, an additional "detail" argument passed in to gSignalEmit has to match the detail argument of the signal handler currently subject to invocation. Specification of no detail argument for signal handlers (omission of the detail part of the signal specification upon connection) serves as a wildcard and matches any detail argument passed in to emission.

Most of the time, the RGtk2 user will be connecting to signals using gSignalConnect. This attaches an R function (and, optionally, some arbitrary "user data") to a specific GObject as a listener to the named signal.

gSignalHandlerBlock and gSignalHandlerUnblock provide facilities for (temporarily) blocking and unblocking the calling of an R function in response to some signal. To permanately disconnect the handler from the object and signal, use gSignalHandlerDisconnect.

A signal may be manually emitted with gSignalEmit. The emission of a signal may be killed prematurely with gSignalStopEmission.

Detailed information about a signal may be introspected with gSignalGetInfo using ids obtained with gObjectGetSignals.

References