Event¶
Overview¶
Event contains information about a raised event from the message bus.
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 an Event.
Creating Events¶
Many components will raise events when interesting things occur. For example, uBit.accelerometer can raise events to indicate that the
micro:bit has be been shaken, or is in freefall, and uBit.button[A,B,AB] can 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. An Event object is very simple, and consists 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 DEVICE_ID_BUTTON_A has the value '1', and an event DEVICE_BUTTON_EVT_CLICK with the value '3' is generated when a button is clicked.
Creating an event is easy - just create an Event with the source and value you need, and the runtime takes care of the rest:
Event(DEVICE_ID_BUTTON_A, DEVICE_BUTTON_EVT_CLICK);
Custom events
You can create your own event sources (and therefore events). Avoid using any source ID that is already used by the runtime. See the message bus for a complete table of the reserved source IDs.
Detecting Events¶
The micro:bit runtime has a component called uBit.messageBus, and its job is remember which events your program is interested in, and
to deliver any Event 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.
Tip
See "Using the message bus" for how to write handlers.
API¶
fire¶
void fire()
Description
Fires this Event onto the Default EventModel , or a custom one!
Component Constructor¶
Advanced users only
Do not use this unless you really know what you're doing. It's usually best to use uBit.
Event( 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
Event evt(id,DEVICE_BUTTON_EVT_CLICK);
// Create an event only, do not fire onto an EventModel.
Event evt(id,DEVICE_BUTTON_EVT_CLICK,CREATE_AND_FIRE);
Event( uint16_t source, uint16_t value, EventLaunchMode mode)
Description
Constructor.
Parameters
uint16_tsourceuint16_tvalue - A component specific code indicating the cause of the event.EventLaunchModemode - Optional definition of how the event should be processed after construction (if at all): CREATE_ONLY: Event is initialised, and no further processing takes place. CREATE_AND_FIRE: Event 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
Event evt(id,DEVICE_BUTTON_EVT_CLICK);
// Create an event only, do not fire onto an EventModel.
Event evt(id,DEVICE_BUTTON_EVT_CLICK,CREATE_AND_FIRE);