luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-12 23:46:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Document signal handler types and arguments

Browse Source 
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 <pwithnall@gnome.org>
This commit is contained in:
Philip Withnall 2024-03-06 13:22:41 +00:00
parent a6dbfcd601
commit 8a640f50ca
1 changed files with 15 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/reference/gobject/signals.md
View File

@ -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: