microbit: Added configurable event processing options into MicroBitEvent

Events in the micro:bit runtime are normally launched through making an instance
of the MicroBitEvent class. This update added configuration support to all the
code creating the MicroBitEvent decide if the newly created event should then be
automatically queued on the MessageBus or processed immediately by event handlers.

inc/MicroBitEvent.h

@@ -3,6 +3,15 @@
 
 #include "mbed.h"
 
+enum MicroBitEventLaunchMode
+{
+    CREATE_ONLY,                        
+    CREATE_AND_QUEUE,
+    CREATE_AND_FIRE
+};
+
+#define MICROBIT_EVENT_DEFAULT_LAUNCH_MODE     CREATE_AND_QUEUE
+
 /**
   * Class definition for a MicrobitEvent
   * It represents a common event that is generated by the various components on the MB.
@@ -22,15 +31,24 @@ class MicroBitEvent
       * Constructor. 
       * @param src ID of the MicroBit Component that generated the event e.g. MICROBIT_ID_BUTTON_A.
       * @param value Component specific code indicating the cause of the event.
-      * @param fire whether the event should be fire immediately upon construction
+      * @param mode optional definition of how the event should be processed after construction (if at all):
+      *
+      * CREATE_ONLY: MicroBitEvent is initialised, and no further processing takes place.
+      * CREATE_AND_QUEUE: MicroBitEvent is initialised, and queued on the MicroBitMessageBus.
+      * CREATE_AND_FIRE: MicroBitEvent is initialised, and its event handlers are immediately fired (not suitable for use in interrupts!).
       * 
-      * Example:
+      * Example: Create and launch an event using the default configuration
       * @code 
-      * MicrobitEvent evt(id,MICROBIT_BUTTON_EVT_CLICK,true); // auto fire
+      * MicrobitEvent evt(id,MICROBIT_BUTTON_EVT_CLICK); 
+      * @endcode
+      *
+      * Example: Create and launch an event and process all registered event handlers immediately.
+      * @code 
+      * MicrobitEvent evt(id,MICROBIT_BUTTON_EVT_CLICK,CREATE_AND_FIRE); 
       * @endcode
       */
-    
-    MicroBitEvent(uint16_t source, uint16_t value, bool fire = true);  
+   
+    MicroBitEvent(uint16_t source, uint16_t value, MicroBitEventLaunchMode mode = MICROBIT_EVENT_DEFAULT_LAUNCH_MODE);  
     
     /**
       * Default constructor - initialises all values, and sets timestamp to the current time.
@@ -38,9 +56,15 @@ class MicroBitEvent
     MicroBitEvent(); 
 
     /**
-      * Fires the represented event onto the message bus.
+      * Fires the represented event onto the message bus using the default configuration.
       */
     void fire();
+
+    /**
+      * Fires the represented event onto the message bus.
+      * @param mode Configuration of how the event is processed.
+      */
+    void fire(MicroBitEventLaunchMode mode);
 };
 
 /**

inc/MicroBitMessageBus.h

@@ -60,10 +60,10 @@ class MicroBitMessageBus : public MicroBitComponent
       * Internal function, used to deliver the given event to all relevant recipients.
       * Normally, this is called once an event has been removed from the event queue.
       *
-      * IT IS RECOMMENDED THAT ALL EXTERNAL CODE USE THE send() FUNCTIONS INSTEAD OF THIS FUNCTION.
+      * IT IS RECOMMENDED THAT ALL EXTERNAL CODE USE THE send() FUNCTIONS INSTEAD OF THIS FUNCTION,
+      * or the constructors provided by MicroBitEvent.
 	  *
 	  * @param evt The event to send. 
-	  * @param c The cache entry to reduce lookups for commonly used channels.
 	  */
 	void process(MicroBitEvent evt);
 

source/MicroBitEvent.cpp

@@ -17,14 +17,14 @@
   * MicrobitEvent evt(id,MICROBIT_BUTTON_EVT_CLICK,true); // auto fire
   * @endcode
   */
-MicroBitEvent::MicroBitEvent(uint16_t source, uint16_t value, bool fire)
+MicroBitEvent::MicroBitEvent(uint16_t source, uint16_t value, MicroBitEventLaunchMode mode)
 {
     this->source = source;
     this->value = value;
     this->timestamp = ticks;
     
-    if(fire)
-        this->fire();
+    if(mode != CREATE_ONLY)
+        this->fire(mode);
 }    
 
 /**
@@ -37,14 +37,27 @@ MicroBitEvent::MicroBitEvent()
     this->timestamp = ticks;
 }
 
+/**
+  * Fires the represented event onto the message bus.
+  */
+void MicroBitEvent::fire(MicroBitEventLaunchMode mode)
+{
+    if (mode == CREATE_AND_QUEUE)
+        uBit.MessageBus.send(*this);
+
+    else if (mode == CREATE_AND_FIRE)
+        uBit.MessageBus.process(*this);
+}
+
 /**
   * Fires the represented event onto the message bus.
   */
 void MicroBitEvent::fire()
 {
-    uBit.MessageBus.send(*this);
+    fire(MICROBIT_EVENT_DEFAULT_LAUNCH_MODE);
 }
 
+
 /**
   * Constructor. 
   * Create a new MicroBitEventQueueItem.

source/MicroBitMessageBus.cpp

@@ -189,8 +189,9 @@ int MicroBitMessageBus::isIdleCallbackNeeded()
   *
   * Example:
   * @code 
-  * MicroBitEvent evt(id,MICROBIT_BUTTON_EVT_DOWN,ticks,false);
+  * MicroBitEvent evt(id,MICROBIT_BUTTON_EVT_DOWN,ticks,CREATE_ONLY);
   * evt.fire();
+  *
   * //OR YOU CAN DO THIS...  
   * MicroBitEvent evt(id,MICROBIT_BUTTON_EVT_DOWN);
   * @endcode