The documentation previously implied that they could. That’s not really
true though: they can only fail if preconditions fail, i.e. they’re
passed invalid input. That’s a programmer error, which is not something
we want to encourage people to check for at runtime (e.g. by dynamically
checking for a 0 return value).
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
This is nowhere near a complete check-through and gi-docgenification of
the signals docs, just a few bits I was looking at anyway.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3250
This reverts commit da7a31a052. The renaming of parameters implicitly introduced "closure" annotations in the documentation which are wrong on callbacks.
This makes calls to g_signal_connect_data() and g_signal_connect_object()
with default flags more self-documenting.
Signed-off-by: Simon McVittie <smcv@collabora.com>
These have all been added manually, as I’ve finished all the files which
I can automatically detect.
All the license headers in this commit are for LGPL-2.1-or-later, and
all have been double-checked against the license paragraph in the file
header.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Helps: #1415
The user data parameters in callbacks need to be named user_data to
generate correct closure attributes in the introspection data. This
updates parameters missed in GNOME/glib!2633.
When rendering the contents of the GLib documentation stored inside the
introspection data, a common behaviour is to take the first paragraph as
a summary of the symbol being documented.
The documentation is assumed to be in Markdown format, which means:
- paragraphs must be separated by newlines
- lines that have an indentation of four or more spaces are considered
code blocks
- lines that start with a `#` are considered titles
This means we need to slightly tweak the documentation in our sources to
ensure that it can be rendered appropriately by tools that are not
gtk-doc.
See issue: #2365
Preferably macros behave function-like to minimize surprises. That
means for example that they evaluate all arguments exactly once.
Rework g_clear_signal_handler() to assign the macro parameters
to auto variables so they are accessed exactly once.
Also, drop the static assert for the size of (*handler_id_ptr).
As we now assign to a "gulong *" pointer, the compiler already
checks the types. In fact, the check is now stricter than before.
Previously it would have allowed a pointer to a "signed long".
This is a change in behavior of the macro and the stricter compile
check could cause a build failure with broken code.
Also, clear the handler id first, before calling
g_signal_handler_disconnect(). Disconnecting a signal invokes the
destroy notify, which can have side effects. It just feels cleaner
to first reset the *_handler_id_ptr, before those side effects
can happen. Of course, in practice it makes little difference.
Making this validation code public allows projects to validate a
GParamSpec name before creating it. While hard-coded GParamSpec don't
need this, we can't afford crashing the main program for dynamically
generated GParamSpec from user-created data.
In such case, we will need to validate the param names and return errors
instead of trying to create a GParamSpec with invalid names.
Includes modifications from Philip Withnall and Emmanuele Bassi to
rearrange the new function addition and split it into one function for
GParamSpecs and one for GSignals.
These macros wrap functions which were only introduced in certain
versions of GLib. The functions are correctly marked as introduced in
those versions, but the macros aren’t, which can result in not getting
appropriate deprecation warnings if you’re using those APIs when you
have said you’re targeting older GLib versions using
`GLIB_VERSION_MAX_ALLOWED`.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
Closes: #1860
It allows to disconnect a signal handler from GObject instance and at the same
time to nullify the signal handler.
Provided also a macro for handler type conversion.
gtk-doc doesn’t make the return type clear, because these are macros
rather than inline functions, so people often have to guess at the
return type (or look it up from g_signal_connect_closure(), but that’s
hard work).
Make it clear that the return type for handler IDs is gulong. While
there, fix the capitalisation of ‘id’ to ‘ID’ in a few places.
Some compilers have trouble with such sequences. Visual C++ may or may
not generate a warning in this particular case depending on if the
local code page supports an ellipsis.
https://bugzilla.gnome.org/show_bug.cgi?id=767218
It’s quite common to see naked g_signal_connect() calls without a paired
g_signal_handler_disconnect(). This is commonly a bug which could lead
to uses of the callback user data after it’s been freed.
Document the best practices for avoiding this kind of bug by properly
disconnecting all signal handlers.
https://bugzilla.gnome.org/show_bug.cgi?id=741779
Add the GLIB_AVAILABLE_IN_ALL annotation to all old functions (that
haven't already been annotated with the GLIB_AVAILABLE_IN_* macros or a
deprecation macro).
If we discover in the future that we cannot use only one macro on
Windows, it will be an easy sed patch to fix that.
https://bugzilla.gnome.org/show_bug.cgi?id=688681
This lets you set a va_marshaller on your signal which will be
propagated to all closures for the signal. Also, automatically
uses the generica va_marshaller if you specify a NULL c_marshaller.
https://bugzilla.gnome.org/show_bug.cgi?id=661140
Similar to G_PARAM_DEPRECATED. It will warn only for users of the
signals, so a signal can still be emited without warning, for
compatibility reasons.
Apparently, there is no way user flags could have been used before,
so that shouldn't break anyone.
https://bugzilla.gnome.org/show_bug.cgi?id=663581
Some links were broken due to typos, because functionality was removed
in GLib 2.0 or for various other reasons. Fix up as many of them as is
reasonable.
In some cases, signal arguments have to be collected, even if there are i
no signal handlers connected (e.g. for GVariant parameters, where collection
consumes a floating variant).
Based on a patch by Christian Persch.
Bug #643624.
2008-07-04 Michael Natterer <mitch@imendio.com>
Bug 541208 – Functions to easily install and use signals without
class struct slot
* gobject.symbols
* gsignal.[ch] (g_signal_new_class_handler): the same as
_gtk_binding_signal_new(), to install signals with a callback
instead of a class struct slot as class closure.
The next two functions are C convenience and much easier to use
than the generic overriding and chaining APIs which are intended
primarily for language bindings:
(g_signal_override_class_handler): to override a signal with a
callback instead of a class struct slot.
(g_signal_chain_from_overridden_handler): to chain up from a
signal without class struct slot. The API is similar to
g_signal_emit().
svn path=/trunk/; revision=7157
Thu Sep 22 12:42:12 2005 Tim Janik <timj@gtk.org>
* gparam.c (g_param_spec_internal): fix pspec->name assignment which
needs to be strdup()ed for non G_PARAM_STATIC_NAME pspecs. this fixes
recently introduced crashes during plugin unloading.
also, ensure that static pspec names are canonicalized.
* gsignal.h: reverted last change from matthias, we don't guarantee
that type ids aren't mangled with G_SIGNAL_TYPE_STATIC_SCOPE anywhere.
2005-09-20 Matthias Clasen <mclasen@redhat.com>
* gsignal.h (struct _GSignalQuery): Remove the misleading comment
about G_SIGNAL_TYPE_STATIC_SCOPE, since we don't allow that
on return types.
Fri Sep 12 16:31:40 2003 Owen Taylor <otaylor@redhat.com>
* gsignal.[ch]: Add g_signal_accumulator_true_handled(), to
do TRUE-stops-emit signals.
* Makefile.am: Move testoverride.c and testifaceinit.c to
tests/gobject.
Tue Mar 26 15:21:47 2002 Owen Taylor <otaylor@redhat.com>
* gsignal.h (g_signal_handlers_*_by_func): Add explicit
cast of G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA to
GSignalMatchType so that these macros work for C++.
(#76454, Damien Sandras)
