From 464b0001e3464374e2b361caa6ef45e8584bf30e Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Wed, 17 Jun 2015 12:54:56 +0100 Subject: docs: Note the event handling gotchas We should note that calling GTK API that deals with events from a ClutterActor event handler will cause re-entrancy issues. In other words: If you call GTK event API from Clutter event handlers [ South Park ski instructor ] You're going to have a bad time https://bugzilla.gnome.org/show_bug.cgi?id=745248 --- clutter-gtk/gtk-clutter-embed.c | 42 ++++++++++++++++++++++++++++++++++------- 1 file changed, 35 insertions(+), 7 deletions(-) diff --git a/clutter-gtk/gtk-clutter-embed.c b/clutter-gtk/gtk-clutter-embed.c index 80b5839..638772d 100644 --- a/clutter-gtk/gtk-clutter-embed.c +++ b/clutter-gtk/gtk-clutter-embed.c @@ -32,13 +32,41 @@ * By using a #GtkClutterEmbed widget is possible to build, show and * interact with a scene built using Clutter inside a GTK+ application. * - * Though #GtkClutterEmbed is a #GtkContainer subclass, - * it is not a real GTK+ container; #GtkClutterEmbed is required to - * implement #GtkContainer in order to embed a #GtkWidget through the - * #GtkClutterActor class. Calling gtk_container_add() on a #GtkClutterEmbed - * will trigger an assertion. It is strongly advised not to override the - * #GtkContainer implementation when subclassing - * #GtkClutterEmbed. + * ## Event handling with GtkClutterEmbed + * + * Due to re-entrancy concerns, you should not use GTK event-related + * API from within event handling signals emitted by Clutter actors + * inside a #GtkClutterEmbed. + * + * Event-related API, like the GTK drag and drop functions, or the + * GTK grab ones, cause events to be processed inside the GDK event + * loop; #GtkClutterEmbed and the Clutter event loop may use those + * events to generate Clutter events, and thus emit signals on + * #ClutterActors. If you use the event-related signals of a + * #ClutterActor to call the GTK API, one of the two event loops + * will try to re-enter into each other, and either cause a crash + * or simply block your application. + * + * To avoid this behavior, you can either: + * + * - only use GTK+ event handling signals to call event-related + * GTK functions + * - let the main loop re-enter, by calling event-related GTK + * functions from within an idle or a timeout callback + * + * You should also make sure you're not using GTK widgets that call + * event-related GTK API, like the grab functions in a #GtkMenu, in + * response to Clutter actor events. + * + * ## Using GtkClutterEmbed as a container + * + * Though #GtkClutterEmbed is a #GtkContainer subclass, it is not a + * real GTK+ container; #GtkClutterEmbed is required to implement the + * #GtkContainer virtual functions in order to embed a #GtkWidget + * through the #GtkClutterActor class. Calling gtk_container_add() + * on a #GtkClutterEmbed will trigger an assertion. It is strongly + * advised not to override the #GtkContainer implementation when + * subclassing #GtkClutterEmbed, to avoid breaking internal state. */ #ifdef HAVE_CONFIG_H -- cgit v1.2.1