Commit Graph

71 Commits

Author SHA1 Message Date
Emmanuele Bassi
f62622fc7b docs: Start stanzas with a single paragraph
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
2021-08-02 13:22:23 +01:00
John McCambridge
e010624309 Update signal accumulator docs.
Reflect that a FALSE returned from the accumulator will still emit signals in the RUN_CLEANUP state.
Fixes #2352
2021-04-29 09:41:44 +01:00
Thomas Haller
7777f3bdbe gsignal: let g_clear_signal_handler() evaluate argument only once
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.
2021-02-01 09:45:16 +01:00
Sebastian Dröge
9d1455444c gsignal: Add a new GSignalFlag to mark the first run of an accumulator function
Also add a test for signal accumulators. There was none before, and this
one now also covers the new flag.

Fixes https://gitlab.gnome.org/GNOME/glib/issues/514
2020-12-21 17:10:19 +00:00
Jehan
13d1697b67 gobject: Add g_{param_spec,signal}_is_valid_name() functions
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.
2020-03-04 14:46:28 +00:00
Philip Withnall
ccbe9690d3 gsignal: Fix typos in GSignalMatchType documentation
Signed-off-by: Philip Withnall <withnall@endlessm.com>
2019-11-15 11:06:14 +00:00
Philip Withnall
d196bfa4a4 glib: Mark various macros as available in certain versions of GLib
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
2019-08-26 18:50:16 +03:00
Marco Trevisan (Treviño)
409c1522bc gisgnal: Add g_clear_signal_handler
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.
2019-05-20 13:33:41 -05:00
Sébastien Wilmet
6b948d9613 gobject/: LGPLv2+ -> LGPLv2.1+
All gobject/*.{c,h} files have been processed.

gmarshal.c and gmarshal.h don't have a license header.

https://bugzilla.gnome.org/show_bug.cgi?id=776504
2017-05-24 11:58:19 +02:00
Philip Withnall
9f4d5e8b91 gsignal: Mention handler ID type in signal connection macro docs
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.
2016-11-10 16:12:41 +00:00
Gerald Combs
05d429af9d gsignal: Remove a UTF-8 ellipsis from docs
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
2016-06-03 16:09:43 -04:00
Philip Withnall
ef1ba452b3 gsignal: Document memory management best practices for signal handlers
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
2015-08-19 12:56:38 +01:00
Philip Withnall
248ca72782 gsignal: Add an example to the g_signal_connect_swapped() documentation
The precise behaviour of and motivation behind swapping parameters was
not entirely clear before.

https://bugzilla.gnome.org/show_bug.cgi?id=732068
2014-06-23 12:30:51 +01:00
Matthias Clasen
4dba2eb486 Remove some markup from docs 2014-05-13 08:08:37 -04:00
Matthias Clasen
49cc207e35 docs: Ditch more markup
Some markup was hiding in docs in headers. Drop it there, too.
2014-03-02 18:23:43 -05:00
Daniel Mustieles
078dbda148 Updated FSF's address 2014-01-31 14:31:55 +01:00
Colin Walters
8f4dc7012e gsignal: Signal connection ids are always > 0 if successful
Note this explicitly so that people can rely on doing:

if (mystruct->sigid > 0)
  g_signal_disconnect (mystruct->object, mystruct->sigid);

https://bugzilla.gnome.org/show_bug.cgi?id=719809
2013-12-03 19:23:49 -05:00
Ryan Lortie
0156092a42 various: add GLIB_AVAILABLE_IN_ALL everywhere else
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
2013-01-13 13:11:57 -05:00
Matthias Clasen
e1b99b2ddc Move single-include guards inside include guards
gcc has optimizations for include guards that only work
if they are outermost in the the header.
https://bugzilla.gnome.org/show_bug.cgi?id=689810
2012-12-27 23:43:14 -05:00
Simon Feltman
8e92798612 Add array length annotation to GSignalQuery param_types field
https://bugzilla.gnome.org/show_bug.cgi?id=687541
2012-11-04 13:51:15 +01:00
Alexander Larsson
7964cda8e6 Add g_signal_set_va_marshaller
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
2012-03-02 17:13:03 +01:00
Ryan Lortie
cf48434867 gsignal: add g_signal_handlers_disconnect_by_data
Similar to g_signal_handlers_disconnect_by_func() but disconnects all
functions that use the given user_data.

https://bugzilla.gnome.org/show_bug.cgi?id=668269
2012-01-19 10:49:31 -05:00
Murray Cumming
951827379f gsignal.h: Remove trailing comma 2011-11-18 10:46:35 +01:00
Marc-André Lureau
fb95c20c96 Add G_SIGNAL_DEPRECATED
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
2011-11-07 23:12:45 +01:00
Ryan Lortie
9829d04be8 GObject docs: resolve broken links
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.
2011-09-05 18:46:59 -04:00
Pavel Holejsovsky
fd1a12ca4d [gi] Add signal annotations 2011-08-21 17:17:07 +02:00
Ryan Lortie
8073759f8c Remove all uses of G_CONST_RETURN
Just use 'const'.

https://bugzilla.gnome.org/show_bug.cgi?id=644611
2011-06-09 11:15:40 -04:00
Emmanuele Bassi
08f0a31289 Revert "Remove all uses of G_CONST_RETURN"
This reverts commit 36741245cc.

The removal has not been discussed, except on Bugzilla:

https://bugzilla.gnome.org/show_bug.cgi?id=644611
2011-03-15 09:03:28 +00:00
Ryan Lortie
36741245cc Remove all uses of G_CONST_RETURN
Just use 'const'.
2011-03-15 01:32:22 -04:00
Christian Persch
61b0e1c8d4 Add G_SIGNAL_MUST_COLLECT
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.
2011-03-15 01:32:22 -04:00
Ryan Lortie
15d87c2cc4 GObject: add g_signal_accumulator_first_wins
Deals with the case where we want exactly one signal handler to run.
2010-10-12 21:34:17 -04:00
Michael Natterer
20d4f6da73 Bug 541208 – Functions to easily install and use signals without class
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
2008-07-04 11:10:17 +00:00
Stefan Kost
356fe46531 Migrating docs.
* docs/reference/gobject/tmpl/signals.sgml:
	* gobject/gclosure.c:
	* gobject/gobject.c:
	* gobject/gsignal.c:
	* gobject/gsignal.h:
	  Migrating docs.


svn path=/trunk/; revision=7083
2008-06-22 09:29:52 +00:00
Tim Janik
b94a2fe66c fix pspec->name assignment which needs to be strdup()ed for non
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-22 10:48:04 +00:00
Matthias Clasen
a07b4b8c02 Remove the misleading comment about G_SIGNAL_TYPE_STATIC_SCOPE, since we
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.
2005-09-20 14:28:32 +00:00
Owen Taylor
32bc3c4197 Add g_signal_accumulator_true_handled(), to do TRUE-stops-emit signals.
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.
2003-09-12 20:33:31 +00:00
Matthias Clasen
6df677db74 Sync parameter names with docs and implementation.
* gsignal.h (g_signal_add_emission_hook):
	* gtype.h (g_type_interface_get_plugin): Sync parameter names with
	docs and implementation.

	* gtype.c (g_type_add_interface_dynamic):
	(g_type_interface_get_plugin):
	(g_type_interface_peek_parent):
	(g_type_query): Add docs.

	* gobject/tmpl/gtype.sgml: Add docs.

	* gobject/tmpl/signals.sgml: Regenerated.
2002-12-03 23:54:55 +00:00
Owen Taylor
564cbf8516 Add explicit cast of G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA to
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)
2002-03-26 20:32:30 +00:00
Tim Janik
5bbfa527f7 fix extraneous include.
Thu Mar 21 01:28:14 2002  Tim Janik  <timj@gtk.org>

        * gsignal.h: fix extraneous include.
2002-03-21 00:24:41 +00:00
Tim Janik
69c000f069 added some assertions to test g_signal_get_invocation_hint().
Tue Dec 18 21:39:57 2001  Tim Janik  <timj@gtk.org>

        * testoverride.c: added some assertions to test
        g_signal_get_invocation_hint().

        * gsignal.[hc]: remove signal_id argument from
        g_signal_chain_from_overridden(), the parameters are assumed to match
        the innermost signal currently in emission for this instance.
        added g_signal_get_invocation_hint() to figure the invocation hint
        of the innermost signal emission of an instance.

        * gsignal.c (g_signal_list_ids): fix G_BSEARCH_ARRAY_NODES() to
        access a bsearch array and not a pointer to it (discovered by
        Sven Neumann).
2001-12-18 20:38:58 +00:00
Tim Janik
a05a4b7660 implemented closure chaining.
Thu Dec 13 08:03:17 2001  Tim Janik  <timj@gtk.org>

        * gsignal.c: implemented closure chaining.
2001-12-13 07:04:41 +00:00
Christopher Blizzard
5217cbcd9d Explicitly add a cast to the last argument so that the macro will work
2001-12-08  Christopher Blizzard  <blizzard@redhat.com>

        * gsignal.h (g_signal_connect): Explicitly add a cast to the last
        argument so that the macro will work from C++.
2001-12-08 23:52:50 +00:00
Owen Taylor
e767aa0a4f Improve the detection of invalid includes by moving the test outside the
Mon Nov 19 14:35:56 2001  Owen Taylor  <otaylor@redhat.com>

        * *.h: Improve the detection of invalid includes by moving
        the test outside the duplicate include guards.

        * gsourceclosure.c (g_source_set_closure): Doc fix.
2001-11-22 18:55:06 +00:00
Owen Taylor
5852eace66 Include gtypes.h not gobject/gtype.h
Sat Nov 17 14:10:35 2001  Owen Taylor  <otaylor@redhat.com>

	* glib/gbsearcharray.h: Include gtypes.h not gobject/gtype.h

	* glib/glib-object.h gobject/*.h: Prevent headers from
	being included directly except when compiling GObject.

	* gobject/gvaluecollector.h: Include glib-object.h so that
	this file can be included directly, since we don't
	include it _from_ glib-object.h.

	* gobject/gtype.c: Remove struct _GValue hack since we
	now include glib/gvaluecollector.h which simply pulls in
        glib-object.h.
2001-11-18 00:38:48 +00:00
Tim Janik
35bf561f5f add API for chaining: g_signal_chain_from_overridden() and
Tue Nov 13 23:18:10 2001  Tim Janik  <timj@gtk.org>

        * gsignal.[hc]: add API for chaining:
        g_signal_chain_from_overridden() and g_signal_override_class_closure(),
        implementation yet to come.

        * gtype.[hc], Makefile.am: provide G_LOG_DOMAIN as compile flag.

        * gparam.[hc]: s/g_param_get/g_param_spec_get/ for get_nick,
        get_name and get_blurb, to be consistent with the rest of the
        g_param_spec_*() functions.

        * gparamspecs.[hc]: got rid of bogus GClosure paramspec.
        G_TYPE_CLOSURE is a boxed type already.
2001-11-14 03:02:22 +00:00
Tim Janik
ca8f047a45 we need signal.h for G_BREAKPOINT().
Mon Nov  5 18:59:08 2001  Tim Janik  <timj@gtk.org>

        * gobject.h:
        * gsignal.h: we need signal.h for G_BREAKPOINT().
2001-11-05 17:58:43 +00:00
Sven Neumann
57c5a11d7b added convenience macro g_signal_connect_after().
2001-08-01  Sven Neumann  <sven@gimp.org>

        * gsignal.h: added convenience macro g_signal_connect_after().
2001-08-01 12:14:12 +00:00
Tim Janik
11b0d06eee fix negative exponent handling (numbers<0).
Fri Jul  6 00:02:41 2001  Tim Janik  <timj@gtk.org>

        * glib/gmessages.c (printf_string_upper_bound): fix negative exponent
        handling (numbers<0).

        * glib/gutils.h (g_bit_storage): take a gulong as argument.
        same for g_bit_nth_lsf() and g_bit_nth_msf() as mask.

Tue Jul 10 18:50:16 2001  Tim Janik  <timj@gtk.org>

        * gsignal.h (struct _GSignalQuery): fix misplaced comment.
2001-07-10 22:37:08 +00:00
Tim Janik
69f32ba7c9 added g_list_insert_before().
Sat Jun 30 23:14:32 2001  Tim Janik  <timj@gtk.org>

        * glib/glist.[hc]: added g_list_insert_before().

        * glib/gslist.c (g_slist_insert_before): provide an implementation,
        prototype was already present...

Sat Jun 30 11:07:00 2001  Tim Janik  <timj@gtk.org>

        * gobject.[hc]: provide weak_ref/weak_unref functions,
        invoked from ->dispose. renamed ->shutdown() to ->dispose(),
        provide "public" API entry here: g_object_run_dispose(), this
        fucntion should _only_ be called from object system implementations
        (e.g. gtkobject.c) if at all.

        * gtypemodule.c (g_type_module_dispose): s/shutdown/dispose/

        * gsignal.h: removed compat aliases.

        * gobject.c (g_object_connect): support data objects.
2001-07-02 05:02:13 +00:00
Tim Janik
fd860cb987 up version number to 1.3.7, interface age 0, binary age 0.
Thu Jun 28 16:57:44 2001  Tim Janik  <timj@gtk.org>

        * configure.in (GLIB_MICRO_VERSION): up version number to 1.3.7,
        interface age 0, binary age 0.

Thu Jun 28 16:42:49 2001  Tim Janik  <timj@gtk.org>

        * gsignal.c (g_signal_lookup):
        (g_signal_list_ids): give elaborate warnings about invalid types,
        non-instantiatable types and unloaded types that we can't operate on.

        * gparam.[hc]: g_param_spec_pool_belongings() ->
        g_param_spec_pool_list_owned().

        * gsignal.[hc]: renamed:
        g_signal_newc -> g_signal_new
        g_signal_disconnect_by_func -> g_signal_handlers_disconnect_by_func
        g_signal_block_by_func -> g_signal_handlers_block_by_func
        g_signal_unblock_by_func -> g_signal_handlers_unblock_by_func
        added GConnectType to simplify (..gboolean swapped, gboolean after)
        args.

        * gobject.[hc]: changed prototypes accordingly.
2001-06-28 17:05:12 +00:00