diff --git a/inc/MicroBitEvent.h b/inc/MicroBitEvent.h index d9c05c9..425848b 100644 --- a/inc/MicroBitEvent.h +++ b/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); }; /** diff --git a/inc/MicroBitMessageBus.h b/inc/MicroBitMessageBus.h index 85990f6..fdace6a 100644 --- a/inc/MicroBitMessageBus.h +++ b/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); diff --git a/source/MicroBitEvent.cpp b/source/MicroBitEvent.cpp index c12d33b..330048a 100644 --- a/source/MicroBitEvent.cpp +++ b/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. diff --git a/source/MicroBitMessageBus.cpp b/source/MicroBitMessageBus.cpp index 1223c32..3d7b999 100644 --- a/source/MicroBitMessageBus.cpp +++ b/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