[clutter-gtk] Add explicit subclassing notes for GtkClutterEmbed

[Emmanuele Bassi <ebassi src gnome org>]

commit c29ecc8a0eec016b05b15d609f566965763e185e
Author: Emmanuele Bassi <ebassi linux intel com>
Date:   Tue May 1 11:33:57 2012 +0100

    Add explicit subclassing notes for GtkClutterEmbed
    
    The reason why GtkClutterEmbed is a GtkContainer is that we need to
    provide an uninterrupted parents chain from the top-level to widgets
    embedded using GtkClutterActor.
    
    If you override GtkContainer's implementation when subclassing
    GtkClutterEmbed you can only chain up - and end up triggering an
    assertion failure, because GtkClutterEmbed only accepts children of
    GtkClutterOffscreen type; GtkClutterOffscreen is an internal type,
    though, so you can't use that knowlegde as a filter in your own code.
    
    It's better to cut our losses, and just explicitly note in the
    documentation that overriding GtkContainer is just A Bad Ideaâ when
    subclassing GtkClutterEmbed.

 clutter-gtk/gtk-clutter-embed.c |   17 ++++++++++++++++-
 1 files changed, 16 insertions(+), 1 deletions(-)
---
diff --git a/clutter-gtk/gtk-clutter-embed.c b/clutter-gtk/gtk-clutter-embed.c
index 4c887f4..b67a2bd 100644
--- a/clutter-gtk/gtk-clutter-embed.c
+++ b/clutter-gtk/gtk-clutter-embed.c
@@ -31,6 +31,14 @@
  *
  * 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>
  */
 
 #ifdef HAVE_CONFIG_H
@@ -613,7 +621,14 @@ gtk_clutter_embed_add (GtkContainer *container,
 {
   GtkClutterEmbedPrivate *priv = GTK_CLUTTER_EMBED (container)->priv;
 
-  g_assert (GTK_CLUTTER_IS_OFFSCREEN (widget));
+#ifndef G_DISABLE_ASSERT
+  if (G_UNLIKELY (!GTK_CLUTTER_IS_OFFSCREEN (widget)))
+    {
+      g_critical ("Widgets of type '%s' do not support children.",
+                  G_OBJECT_TYPE_NAME (container));
+      return;
+    }
+#endif
 
   priv->children = g_list_prepend (priv->children, widget);
   gtk_widget_set_parent (widget, GTK_WIDGET (container));