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:

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_t
source

uint16_t
value - 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_t
source

uint16_t
value - A component specific code indicating the cause of the event.

MicroBitEventLaunchMode
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_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!