2.5.3 GObject Signals

GObjects have a functionality for defining and calling callback procedures that it calls signals. Note that these signals have nothing to do with Unix signals like SIGTERM.

To hook a callback procedure to an object’s signal, use the connect procedure. Consider the following example.

(define (activate app)
   ...
   )

(define activate-signal (make <signal> #:name "activate"))

(connect app              ; A GObject
         activate-signal  ; A <signal> object
         activate)        ; A procedure to call when emitted

In that example, the caller is attaching a procedure named activate to the object app’s “activate” signal. When the gobject object calls all the callback procedures attached to its “activate” signal it will call this activate procedure.

When a callback procedure is called it may receive some arguments from the caller and some from user data. In the example, activate is supposed to take a single argument. This argument – app – is supplied by the caller, as are all arguments to signals.

Procedure: connect obj (signal <signal>) (handler <procedure>) #:key after? detail ¶

Procedure: connect obj (signal <signal>) (detail <symbol>) (handler <procedure>) ... ¶

Procedure: connect-after obj (signal <signal>) (handler <procedure>) ... ¶

Procedure: connect-after obj (signal <signal>) (detail <symbol>) (handler <procedure>) ... ¶

Hooks handler to emissions of signal. If detail is supplied, only emissions in which the detail matches it are considered.

connect-after works like connect, except that the handler is run after the main handling code. The same can be achieved by setting after? to #t.

Note, that signal may expect handler to have multiple output arguments. Each bit set in its output-mask corresponds to one additional value in the output. If the return-type is G_TYPE_NONE, the number of expected outputs is the number of bits set in output-mask. Otherwise, an additional (first) value is required for the return value of the signal itself.

Signal objects can also be used to emit signals. Note that you shouldn’t normally do this when using objects of types that you did not define. When using objects of types that you did define, you should only emit the signals that you defined for that object (and perhaps the “notify” signal when using explicit notification).

Special Form: (signal <signal>) obj [detail] [args...] ¶

Emits the signal signal of obj with detail and args. Note, that the interpretation of detail depends on whether or not signal is detailed. If it is, detail needs to be a symbol, that will be translated to the detail of the emission. If it is not, it is considered the first argument and will be consed with args to form an argument list.

Signals have several slots, that can be bound on creation time (and reassigned freely, since they are proper GOOPS objects). When connecting signals, only name needs to be supplied. When using them as proper signals, at least return-type needs to be given as well.

Slot: name ¶

The name of the signal. A string.

Slot: return-type ¶

The return type of the signal. A <GType> or integer, such as G_TYPE_INT.

Slot: param-types ¶

The parameter types of the signal. A list of <GType>s or integers.

Slot: accumulator ¶

An optional signal accumulator procedure. See Signal Accumulators.

Slot: flags ¶

Signal flags, a logical or of one or more of SIGNAL_RUN_FIRST, SIGNAL_RUN_LAST, SIGNAL_RUN_CLEANUP, SIGNAL_NO_RECURSE, etc.

Slot: output-mask ¶

A bitmask, describing which argument should be returned to the user when calling the signal as a procedure.

• Signal Accumulators