---

Signals ¶

G-Golf GObject Signals low level API.
Signals — A means for customization of object behaviour and a general purpose notification mechanism

Procedures ¶

g-signal-newv

g-signal-query

g-signal-lookup

g-signal-list-ids

g-signal-emitv

g-signal-connect-closure-by-id

g-signal-handler-disconnect

g-signal-parse-name

Types and Values ¶

%g-signal-flags

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.

Please read the Signals section from the GObject reference manual for a complete description.

Procedures ¶

Procedure: g-signal-newv name iface-type flags class-closure accumulator accu-data c-marshaller return-type n-param param-types ¶

Returns the signal id.

Creates a new signal. The arguments are:

name

The name for the signal.

iface-type

The type this signal pertains to. It will also pertain to types which are derived from this type.

flags

A list of %g-signal-flags, specifying detail of when the default handler is to be invoked. It should at least specify run-first or run-last.

class-closure

The closure to invoke on signal emission, may be #f.

accumulator

The accumulator for this signal; may be #f.

accu-data

User data for the accumulator.

c-marshaller

The function to translate arrays of parameter values to signal emissions into C language callback invocations or #f.

return-type

The GType of the signal returned value. The caller may obtain the GType, given a scheme object (or 'none for a signal without a return value), by calling scm->g-type.

n-param

The length of param-types.

param-types

An list of types, one for each parameter (may be '() if n-param is zero).

Procedure: g-signal-query id ¶

Returns a list.

Obtains and returns a list composed of the signal id, name, interface-type³⁰, flags, return-type, number of arguments and their types. For example³¹:

,use (g-golf)
(gi-import "Clutter")

(make <clutter-actor>)
⇒ $2 = #<<clutter-actor> 565218c88a80>

(!g-type (class-of $2))
⇒ $3 = 94910597864000

(g-signal-list-ids $3)
⇒ $4 = (5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30)

(g-signal-query 20)
⇒ $5 = (20 "enter-event" 94910597864000 (run-last) boolean 1 (boxed))

As you may have noticed, the signal query argument(s) list does not include the instance (and its type) upon which the signal is called, but both at C level and within the context of GClosure, callbacks must assume that the instance upon which a signal is called is always the first argument of the callback.

Procedure: g-signal-lookup name g-type ¶

Returns an integer.

Obtains and returns the signal’s identifying integer, given the name of the signal and the object g-type it connects to. If a signal identifier can’t be find for the given name and g-type, an exception is raised.

Procedure: g-signal-list-ids g-type ¶

Returns a list of integers.

Obtains and returns the list of signal’s identifying integers for g-type (Note that at least one g-type instance must have been created prior to attempt to list or query signal’s identifying integers for a given g-type).

Procedure: g-signal-emitv params id detail return-value ¶

Returns nothing.

Emits a signal. Signal emission is done synchronously. The method will only return control after all handlers are called or signal emission was stopped.

Note that g-signal-emitv doesn’t change return-value if no handlers are connected.

The params points to the argument list for the signal emission. The first element in the array is a GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. The id is the signal id, detail the detail (a g-quark and return-value the location to store the return value of the signal emission (it must be provided if the specified signal returns a value, but may be ignored otherwise).

Procedure: g-signal-connect-closure-by-id instance id detail closure after ¶

Returns the handler ID (always greater than 0 for successful connections).

Connects a closure to a signal for a particular object.

If closure is a floating reference (see g-closure-sink), this function takes ownership of closure.

The instance is the instance to connect to, the id the id of the signal, detail the detail (a g-quark). closure the closure to connect, after (a boolean) whether the handler should be called before or after the default handler of the signal.

Procedure: g-signal-handler-disconnect instance handler-id ¶

Returns nothing.

Disconnects a handler from an instance so it will not be called during any future or currently ongoing emissions of the signal it has been connected to. The handler-id becomes invalid and may be reused.

The handler-id has to be a valid signal handler id, connected to a signal of instance .

Procedure: g-signal-parse-name detailed-signal g-type [force-detail-quark #t] ¶

Returns two integer values.

Obtains and returns the signal-id and a detail corresponding to detailed-signal for g-type. The detailed-signal can be passed as a symbol or a string. When force-detail-quark is #t it forces the creation of a GQuark for the detail.

If the signal name could not successfully be parsed, it raises an exception.

Types and Values ¶

Instance Variable of <gi-enum>: %g-signal-flags ¶

The signal flags are used to specify a signal’s behaviour, the overall signal description outlines how especially the RUN flags control the stages of a signal emission.

An instance of <gi-enum>, who’s members are the scheme representation of the GSignalFlags:

g-name: GSignalFlags
name: g-signal-flags
enum-set:

run-first

Invoke the object method handler in the first emission stage.

run-last

Invoke the object method handler in the third emission stage.

run-cleanup

Invoke the object method handler in the last emission stage.

no-recurse

Signals being emitted for an object while currently being in emission for this very object will not be emitted recursively, but instead cause the first emission to be restarted.

detailed

This signal supports "::detail" appendices to the signal name upon handler connections and emissions.

action

Action signals are signals that may freely be emitted on alive objects from user code via g-signal-emit and friends, without the need of being embedded into extra code that performs pre or post emission adjustments on the object. They can also be thought of as object methods which can be called generically by third-party code.

no-hooks

No emissions hooks are supported for this signal.

must-collect

Varargs signal emission will always collect the arguments, even if there are no signal handlers connected. Since 2.30.

deprecated

The signal is deprecated and will be removed in a future version. A warning will be generated if it is connected while running with G_ENABLE_DIAGNOSTIC=1. Since 2.32.