MicroBitEvent¶
Overview¶
Computer programs execute sequentially - one line after another, following the logic of the program you have written.
Sometimes though, we want to be able to determine when something has happened, and write some code to decide what should
happen in that case. For example, maybe you want to know when a button has been pressed, when your micro:bit has been shaken,
or when some data has been sent to you over the micro:bit radio. For these sorts of cases, we create a MicroBitEvent.
Creating Events¶
Many components will raise events when interesting things occur. For example, 'MicroBitAccelerometer' will raise events to indicate that the
micro:bit has be been shaken, or is in freefall and 'MicroBitButton' will send events on a range of button up, down, click and hold events.
Programmers are also free to send their own events whenever they feel it would be useful. MicroBitEvents are very simple, and consist of
only two numbers:
source- A number identifying the component that created the event.value- A number unique to the source that identifies the event.
The documentation for each component defines its event source, and all the events it may generate, and also gives a name to these event values. For example, take a look at the button documentation to see that the source MICROBIT_ID_BUTTON_A has the value '1', and an event MICROBIT_BUTTON_EVT_CLICK with the value '3' is generated when a button is clicked.
Creating an event is easy - just create a MicroBitEvent with the source and value you need, and the runtime takes care of the rest:
MicroBitEvent(MICROBIT_ID_BUTTON_A, MICROBIT_BUTTON_EVT_CLICK);
Feel free to create your own events lke this too. Just try to avoid using any source ID that is already used by the runtime! :-) See the messageBus page for a complete table of the reserved source IDs.
Detecting Events¶
The micro:bit runtime has a component called the MicroBitMessageBus, and its job is remember which events your program is interested in, and
to deliver MicroBitEvents to your program as they occur.
To find out when an event happens, you need to create a function in your program, then tell the message bus which event you want to attach this function to. This is known as writing an event handler.
You write an event handler through the MicroBitMessageBus listen function.
API¶
Constructor¶
MicroBitEvent( uint16_t source, uint16_t value)¶
Description¶
Constructor.
Parameters¶
uint16_tsourceuint16_tvalue - A component specific code indicating the cause of the event.
Example¶
// Create and launch an event using the default configuration
MicrobitEvent evt(id,MICROBIT_BUTTON_EVT_CLICK);
// Create an event only, do not fire onto an EventModel.
MicrobitEvent evt(id,MICROBIT_BUTTON_EVT_CLICK,CREATE_AND_FIRE);
MicroBitEvent( uint16_t source, uint16_t value, MicroBitEventLaunchMode mode)¶
Description¶
Constructor.
Parameters¶
uint16_tsourceuint16_tvalue - A component specific code indicating the cause of the event.MicroBitEventLaunchModemode - 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_FIRE: MicroBitEvent is initialised, and its event handlers are immediately fired (not suitable for use in interrupts!).
Example¶
// Create and launch an event using the default configuration
MicrobitEvent evt(id,MICROBIT_BUTTON_EVT_CLICK);
// Create an event only, do not fire onto an EventModel.
MicrobitEvent evt(id,MICROBIT_BUTTON_EVT_CLICK,CREATE_AND_FIRE);
MicroBitEvent()¶
Description¶
Default constructor - initialises all values, and sets timestamp to the current time.
fire¶
void fire()¶
Description¶
Fires this MicroBitEvent onto the Default EventModel , or a custom one!