Move examples from tests/interactive to a new top-level

The example code that is meant to be XIncluded into the API reference
should not be part of the interactive test suite: it's code that it is
meant to be used as a reference implementation - whereas the interactive
test suite should be allowed to be lean and test behaviour even in nasty
ways. In short: the test suite should not be the place where we show off
idiomatic code for educational purposes.

Makefile.am

@@ -2,7 +2,7 @@ include $(top_srcdir)/build/autotools/Makefile.am.silent
 
 NULL =
 
-SUBDIRS = clutter tests doc po build
+SUBDIRS = clutter tests examples doc po build
 
 # XXX - this is a massive hack to make autoreconf honour the ACLOCAL_FLAGS
 # that jhbuild sets while still retaining build/autotools as the authoritative

clutter/clutter-actor.c

@@ -105,7 +105,7 @@
  *   of children from a ClutterActor, use the #ClutterContainer::actor-removed
  *   signal.</para>
  *   <informalexample><programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../tests/interactive/test-actor.c">
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/basic-actor.c">
  *   <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
  * </xi:include>
  *   </programlisting></informalexample>

clutter/clutter-bin-layout.c

@@ -52,7 +52,7 @@
  * <example id="example-clutter-bin-layout">
  *  <title>How to pack actors inside a BinLayout</title>
  *  <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../tests/interactive/test-bin-layout.c">
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/bin-layout.c">
  *   <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
  * </xi:include>
  *  </programlisting>

clutter/clutter-bind-constraint.c

@@ -80,7 +80,7 @@
  * <example id="bind-constraint-example">
  *   <title>Animating the offset property of ClutterBindConstraint</title>
  *   <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../tests/interactive/test-constraints.c">
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/bind-constraint.c">
  *   <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
  * </xi:include>
  *   </programlisting>

clutter/clutter-canvas.c

@@ -38,7 +38,7 @@
  *
  * <informalexample id="canvas-example">
  *   <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../tests/interactive/test-canvas.c">
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/canvas.c">
  *   <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
  * </xi:include>
  *   </programlisting>

clutter/clutter-constraint.c

@@ -91,7 +91,9 @@
  *       <graphic fileref="constraints-example.png" format="PNG"/>
  *     </figure>
  *     <programlisting>
- *<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../tests/interactive/test-snap-constraint.c" parse="text"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>
+ *<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../examples/constraints.c" parse="text">
+ *  <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+ *</xi:include>
  *     </programlisting>
  *     <para>You can try resizing interactively the #ClutterStage and verify
  *     that the three #ClutterActor<!-- -->s maintain the same position and

clutter/clutter-drag-action.c

@@ -57,7 +57,7 @@
  * <example id="drag-action-example">
  *   <title>A simple draggable actor</title>
  *   <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../tests/interactive/test-drag.c">
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/drag-action.c">
  *   <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
  * </xi:include>
  *   </programlisting>

clutter/clutter-drop-action.c

@@ -52,7 +52,7 @@
  * <example id="drop-action-example">
  *   <title>Drop targets</title>
  *   <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../tests/interactive/test-drop.c">
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/drop-action.c">
  *   <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
  * </xi:include>
  *   </programlisting>

clutter/clutter-image.c

@@ -31,7 +31,7 @@
  * image data.
  *
  * <informalexample><programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../tests/interactive/test-image-box.c">
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/image-content.c">
  *   <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
  * </xi:include>
  * </programlisting></informalexample>

clutter/clutter-main.c

@@ -81,7 +81,7 @@
  *   <example id="worker-thread-example">
  *     <title>A worker thread example</title>
  *     <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../tests/interactive/test-thread.c">
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/threads.c">
  *   <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
  * </xi:include>
  *     </programlisting>

configure.ac

@@ -1121,6 +1121,8 @@ AC_CONFIG_FILES([
 	tests/micro-bench/Makefile
 	tests/performance/Makefile
 
+        examples/Makefile
+
 	doc/Makefile
 	doc/reference/Makefile
 	doc/reference/clutter/Makefile

examples/Makefile.am

@@ -0,0 +1,39 @@
+include $(top_srcdir)/build/autotools/Makefile.am.silent
+
+all_examples = \
+	basic-actor \
+	bind-constraint \
+	canvas \
+	constraints \
+	drag-action \
+	drop-action \
+	threads
+
+if PIXBUF_TESTS
+all_examples += \
+	bin-layout \
+	image-content
+endif
+
+INCLUDES = \
+	-I$(top_srcdir)			\
+	-I$(top_srcdir)/clutter 	\
+	-I$(top_builddir)/clutter
+
+LDADD = \
+	$(top_builddir)/clutter/libclutter-@CLUTTER_API_VERSION@.la \
+	$(CLUTTER_LIBS) \
+	$(GDK_PIXBUF_LIBS) \
+	-lm
+
+AM_CFLAGS = $(CLUTTER_CFLAGS) $(GDK_PIXBUF_CFLAGS)
+
+AM_CPPFLAGS = \
+	-DTESTS_DATADIR=\""$(abs_top_srcdir)/tests/data"\" \
+	-DG_DISABLE_SINGLE_INCLUDES \
+	-DGLIB_DISABLE_DEPRECATION_WARNINGS \
+	-DCLUTTER_DISABLE_DEPRECATION_WARNINGS
+
+noinst_PROGRAMS = $(all_examples)
+
+-include $(top_srcdir)/build/autotools/Makefile.am.gitignore

examples/README

@@ -0,0 +1,10 @@
+The code in this directory is meant to be XIncluded into the Clutter API
+reference, and thus is to be considered part of the Clutter documentation.
+
+As such, the code MUST be:
+
+  - correct;
+  - idiomatic, i.e. show how a task is meant to be achieved using the
+    best possible practices given the current API;
+  - well documented;
+  - ready for copy and paste.

examples/basic-actor.c

@@ -1,5 +1,4 @@
 #include <stdlib.h>
-#include <gmodule.h>
 #include <clutter/clutter.h>
 
 #define SIZE    128
@@ -84,8 +83,8 @@ animate_rotation (ClutterActor *actor,
   return CLUTTER_EVENT_STOP;
 }
 
-G_MODULE_EXPORT int
-test_actor_main (int argc, char *argv[])
+int
+main (int argc, char *argv[])
 {
   ClutterActor *stage, *vase;
   ClutterActor *flowers[3];
@@ -152,9 +151,3 @@ test_actor_main (int argc, char *argv[])
 
   return EXIT_SUCCESS;
 }
-
-G_MODULE_EXPORT const char *
-test_actor_describe (void)
-{
-  return "Basic example of actor usage.";
-}

examples/bin-layout.c

@@ -1,5 +1,4 @@
 #include <stdlib.h>
-#include <gmodule.h>
 #include <cairo.h>
 #include <gdk-pixbuf/gdk-pixbuf.h>
 #include <clutter/clutter.h>
@@ -160,8 +159,8 @@ redraw_canvas (ClutterActor  *actor,
                            clutter_actor_get_height (actor));
 }
 
-G_MODULE_EXPORT int
-test_bin_layout_main (int argc, char *argv[])
+int
+main (int argc, char *argv[])
 {
   ClutterActor *stage, *box, *bg, *icon, *emblem, *label;
   ClutterLayoutManager *layout;
@@ -306,9 +305,3 @@ test_bin_layout_main (int argc, char *argv[])
 
   return EXIT_SUCCESS;
 }
-
-G_MODULE_EXPORT const char *
-test_bin_layout_describe (void)
-{
-  return "BinLayout layout manager example";
-}

examples/bind-constraint.c

@@ -1,5 +1,4 @@
 #include <stdlib.h>
-#include <gmodule.h>
 #include <clutter/clutter.h>
 
 #define RECT_SIZE       128
@@ -155,8 +154,8 @@ on_button_release (ClutterActor *actor,
   return TRUE;
 }
 
-G_MODULE_EXPORT int
-test_constraints_main (int argc, char *argv[])
+int
+main (int argc, char *argv[])
 {
   ClutterActor *stage, *rect;
   ClutterConstraint *constraint;
@@ -245,9 +244,3 @@ test_constraints_main (int argc, char *argv[])
 
   return EXIT_SUCCESS;
 }
-
-G_MODULE_EXPORT const char *
-test_constraints_describe (void)
-{
-  return "Visualize usage of Bind and Align constraints";
-}

examples/canvas.c

@@ -80,8 +80,8 @@ invalidate_clock (gpointer data_)
   return TRUE;
 }
 
-G_MODULE_EXPORT int
-test_canvas_main (int argc, char *argv[])
+int
+main (int argc, char *argv[])
 {
   ClutterActor *stage, *actor;
   ClutterContent *canvas;
@@ -131,9 +131,3 @@ test_canvas_main (int argc, char *argv[])
 
   return EXIT_SUCCESS;
 }
-
-G_MODULE_EXPORT const char *
-test_canvas_describe (void)
-{
-  return "Simple 2D clock using the Canvas content";
-}

examples/constraints.c

@@ -1,11 +1,8 @@
 #include <stdlib.h>
-#include <gmodule.h>
-
 #include <clutter/clutter.h>
 
-G_MODULE_EXPORT int
-test_snap_constraint_main (int   argc,
-                           char *argv[])
+int
+main (int argc, char *argv[])
 {
   ClutterActor *stage, *layer_a, *layer_b, *layer_c;
 

examples/drag-action.c

@@ -1,5 +1,4 @@
 #include <stdlib.h>
-#include <gmodule.h>
 #include <clutter/clutter.h>
 
 static gboolean
@@ -148,8 +147,8 @@ static GOptionEntry entries[] = {
   { NULL }
 };
 
-G_MODULE_EXPORT int
-test_drag_main (int argc, char *argv[])
+int
+main (int argc, char *argv[])
 {
   ClutterActor *stage, *handle;
   ClutterAction *action;

examples/drop-action.c

@@ -169,8 +169,8 @@ on_target_drop (ClutterDropAction *action,
   add_drag_object (actor);
 }
 
-G_MODULE_EXPORT int
-test_drop_main (int argc, char *argv[])
+int
+main (int argc, char *argv[])
 {
   ClutterActor *dummy;
 
@@ -243,9 +243,3 @@ test_drop_main (int argc, char *argv[])
 
   return EXIT_SUCCESS;
 }
-
-G_MODULE_EXPORT const char *
-test_drop_describe (void)
-{
-  return "Drop action support";
-}

examples/image-content.c

@@ -1,5 +1,4 @@
 #include <stdlib.h>
-#include <gmodule.h>
 #include <gdk-pixbuf/gdk-pixbuf.h>
 #include <clutter/clutter.h>
 
@@ -47,14 +46,8 @@ on_clicked (ClutterClickAction *action,
     cur_gravity = 0;
 }
 
-G_MODULE_EXPORT const char *
-test_image_box_describe (void)
-{
-  return "A test with image content.";
-}
-
-G_MODULE_EXPORT int
-test_image_box_main (int argc, char *argv[])
+int
+main (int argc, char *argv[])
 {
   ClutterActor *stage, *box, *text;
   ClutterContent *image;

examples/threads.c

@@ -1,6 +1,5 @@
 #include <stdio.h>
 #include <stdlib.h>
-#include <gmodule.h>
 #include <clutter/clutter.h>
 
 /* our thread-specific data */
@@ -195,8 +194,8 @@ on_key_press_event (ClutterStage *stage,
   return FALSE;
 }
 
-G_MODULE_EXPORT int
-test_threads_main (int argc, char *argv[])
+int
+main (int argc, char *argv[])
 {
   ClutterActor *stage;
   ClutterActor *rect;
@@ -273,9 +272,3 @@ test_threads_main (int argc, char *argv[])
 
   return EXIT_SUCCESS;
 }
-
-const char *
-test_threads_describe (void)
-{
-  return "Multi-threading programming with Clutter";
-}

tests/interactive/Makefile.am

@@ -8,8 +8,6 @@ UNIT_TESTS = \
 	test-scale.c \
         test-actors.c \
 	test-shader-effects.c \
-	test-depth.c \
-	test-threads.c \
 	test-script.c \
 	test-grab.c \
 	test-cogl-shader-arbfp.c \
@@ -43,21 +41,15 @@ UNIT_TESTS = \
 	test-flow-layout.c \
 	test-box-layout.c \
 	test-stage-sizing.c \
-	test-drag.c \
-	test-constraints.c \
 	test-scrolling.c \
 	test-swipe-action.c \
 	test-cogl-point-sprites.c \
 	test-table-layout.c \
 	test-path-constraint.c \
-	test-snap-constraint.c \
 	test-state-script.c \
-	test-drop.c \
 	test-devices.c \
-	test-actor.c \
 	test-transitions.c \
 	test-content.c \
-	test-canvas.c \
 	test-keyframe-transition.c \
 	test-scroll-actor.c
 
@@ -67,9 +59,7 @@ endif
 
 if PIXBUF_TESTS
 UNIT_TESTS += \
-	test-bin-layout.c \
-	test-image.c \
-	test-image-box.c
+	test-image.c
 endif
 
 if OS_WIN32