[clutter-gtk] docs: Note the event handling gotchas

[Emmanuele Bassi <ebassi src gnome org>]

commit 464b0001e3464374e2b361caa6ef45e8584bf30e
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Wed Jun 17 12:54:56 2015 +0100

    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 files 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.
  *
- * <warning><para>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.</para></warning>
+ * ## 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