2007-10-15 Matthew Allum <mallum@openedhand.com>

* clutter/clutter-actor.c:
        More events documentation.

        * clutter/clutter-event.c:
        * clutter/clutter-event.h:
        Add synthetic flag and make put_event use it
        (via modded patch from pippin)

        * clutter/clutter-main.c: (clutter_do_event):
        dont use put event anymore when pushing enter/leave events.

ChangeLog

@@ -1,3 +1,16 @@
+2007-10-15  Matthew Allum  <mallum@openedhand.com>
+
+	* clutter/clutter-actor.c:
+	More events documentation.
+
+	* clutter/clutter-event.c:
+	* clutter/clutter-event.h:
+	Add synthetic flag and make put_event use it 
+	(via modded patch from pippin)
+
+	* clutter/clutter-main.c: (clutter_do_event):
+	dont use put event anymore when pushing enter/leave events.
+
 2007-10-15  Emmanuele Bassi  <ebassi@openedhand.com>
 
 	* clutter/pango/Makefile.am: Compile with the debug flags, if

clutter/clutter-actor.c

@@ -38,6 +38,8 @@
  * <orderedlist>
  *   <listitem><para>Actors emit pointer events if set reactive, see
  *   clutter_actor_set_reactive()</para></listitem>
+ *   <listitem><para>Events are handled by connecting signal handlers to
+ *   the numerous event signal types.</para></listitem>
  *   <listitem><para>Event handlers must return %TRUE if they handled
  *   the event and wish to block the event emission chain; and %FALSE
  *   if the emission chain must continue</para></listitem>
@@ -46,10 +48,15 @@
  *   <listitem><para>Motion events (motion, enter, leave) are only emitted
  *   per actor if clutter_enable_motion_events() was called with %TRUE. If
  *   set to %FALSE (the default) then only the stage emits motion
- *   events</para></listitem>
+ *   events (no enter or leave events).</para></listitem>
- *   <listitem><para>Once emitted, an event has two phases: capture
+ *   <listitem><para>Once emitted, an event emmision chain has two
- *   and bubble</para></listitem>
+ *   phases: capture and bubble. A emitted event starts in the capture
- * </orderedlist>
+ *   phase beginning at the stage and transversing child actors until
+ *   the event source actor is reached. The emmision then enters the bubble
+ *   phase transversing back up via parents to the stage. An event
+ *   handler can abort this chain at point by returning
+ *   %TRUE.</para></listitem> 
+ *   </orderedlist>
  */
 
 #ifdef HAVE_CONFIG_H

clutter/clutter-event.c

@@ -439,19 +439,24 @@ clutter_event_peek (void)
  * clutter_event_put:
  * @event: a #ClutterEvent
  *
- * Puts a copy of the event on the back on the event queue. 
+ * Puts a copy of the event on the back of the event queue.
+ * The event will have the #CLUTTER_EVENT_FLAG_SYNTHETIC flag set. 
  *
- * Since: 0.4
+ * Since: 0.6
  */
 void
 clutter_event_put (ClutterEvent *event)
 {
   ClutterMainContext *context = clutter_context_get_default ();
+  ClutterEvent       *event_copy;
 
   /* FIXME: check queue is valid */
   g_return_if_fail (context != NULL);
 
-  g_queue_push_head (context->events_queue, clutter_event_copy (event));
+  event_copy = clutter_event_copy (event);
+  event_copy->any.flags |= CLUTTER_EVENT_FLAG_SYNTHETIC;
+
+  g_queue_push_head (context->events_queue, event_copy);
 }
 
 /**

clutter/clutter-event.h

@@ -52,7 +52,7 @@ typedef enum {
 } ClutterModifierType;
 
 typedef enum {
-  CLUTTER_EVENT_FLAG_COOKED = 1 << 0,
+  CLUTTER_EVENT_FLAG_SYNTHETIC = 1 << 0,
 } ClutterEventFlags;
 
 typedef enum 

clutter/clutter-main.c

@@ -1310,7 +1310,8 @@ clutter_do_event (ClutterEvent *event)
 		    /* unref in free  */
 		    cev.crossing.related = g_object_ref (actor);
 
-		    clutter_event_put (&cev); /* copys */
+		    g_queue_push_head (context->events_queue, 
+				       clutter_event_copy (&cev));
 
 		    cev.crossing.type    = CLUTTER_ENTER;
 		    cev.crossing.time    = event->any.time;
@@ -1320,7 +1321,8 @@ clutter_do_event (ClutterEvent *event)
 		    cev.crossing.source  = actor;
 		    cev.crossing.related = g_object_ref (motion_last_actor);
 
-		    clutter_event_put (&cev);
+		    g_queue_push_head (context->events_queue, 
+				       clutter_event_copy (&cev));
 		  }
 	      }
 	    motion_last_actor = actor;