From 8a640f50cad10cd3c3d87b9b8c90835cd42255fc Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 6 Mar 2024 13:22:41 +0000 Subject: [PATCH] docs: Document signal handler types and arguments It seems this was missing from the documentation (or, at least, not in an obvious place). As spotted on https://discourse.gnome.org/t/calling-g-main-loop-quit-from-a-signal-handler/19785. Signed-off-by: Philip Withnall --- docs/reference/gobject/signals.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/reference/gobject/signals.md b/docs/reference/gobject/signals.md index c5eefbe8a..6b17ee54c 100644 --- a/docs/reference/gobject/signals.md +++ b/docs/reference/gobject/signals.md @@ -31,6 +31,21 @@ 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 handler must match the type defined by the signal in both its arguments and +return value (which is often `void`). All handlers take a pointer to the type +instance as their first argument, and a `gpointer user_data` as their final +argument, with signal-defined arguments in-between. The `user_data` is always +filled with the user data provided when the handler was connected to the signal. +Handlers are documented as having type [type@GObject.Callback], but this is +simply a generic placeholder type — an artifact of the GSignal APIs being +polymorphic. + +When a signal handler is connected, its first (‘instance’) and final (‘user +data’) arguments may be swapped if [func@GObject.signal_connect_swapped] is used +rather than [func@GObject.signal_connect]. This can sometimes be convenient for +avoiding defining wrapper functions as signal handlers, instead just directly +passing a function which takes the user data as its first argument. + ## Emissions A signal emission consists of five stages, unless prematurely stopped: