Cefn Hoile / microbit-dal

Attempting to publish a tree

Dependencies:   BLE_API mbed-dev-bin nRF51822

Fork of microbit-dal by Lancaster University

Embed: (wiki syntax)

« Back to documentation index

EventModel Class Reference
Public Member Functions | Static Public Member Functions | Static Public Attributes

EventModel Class Reference

Class definition for the micro:bit EventModel. More...

#include <EventModel.h>

Inherited by MicroBitMessageBus.

Public Member Functions

virtual int send (MicroBitEvent evt)
 Queues the given event to be sent to all registered recipients.
virtual int add (MicroBitListener *listener)
 Add the given MicroBitListener to the list of event handlers, unconditionally.
virtual int remove (MicroBitListener *listener)
 Remove the given MicroBitListener from the list of event handlers.
MicroBitListener * elementAt (int n)
 Returns the MicroBitListener at the given position in the list.
int listen (int id, int value, void(*handler)(MicroBitEvent), uint16_t flags=EVENT_LISTENER_DEFAULT_FLAGS)
 Register a listener function.
int listen (int id, int value, void(*handler)(MicroBitEvent, void *), void *arg, uint16_t flags=EVENT_LISTENER_DEFAULT_FLAGS)
 Register a listener function.
template<typename T >
int listen (uint16_t id, uint16_t value, T *object, void(T::*handler)(MicroBitEvent), uint16_t flags=EVENT_LISTENER_DEFAULT_FLAGS)
 Register a listener function.
int ignore (int id, int value, void(*handler)(MicroBitEvent))
 Unregister a listener function.
int ignore (int id, int value, void(*handler)(MicroBitEvent, void *))
 Unregister a listener function.
template<typename T >
int ignore (uint16_t id, uint16_t value, T *object, void(T::*handler)(MicroBitEvent))
 Unregister a listener function.

Static Public Member Functions

static int setDefaultEventModel (EventModel &model)
 Define the default EventModel to use for events raised and consumed by the microbit-dal runtime.

Static Public Attributes

static EventModel * defaultEventBus = NULL
 Class definition for a MicroBitEvent.

Detailed Description

Class definition for the micro:bit EventModel.

It is common to need to send events from one part of a program (or system) to another. The way that these events are stored and delivered is known as an Event Model...

The micro:bit can be programmed in a number of languages, and it not be good to constrain those languages to any particular event model (e.g. they may have their own already).

This class defines the functionality an event model needs to have to be able to interact with events generated and/or used by the micro:bit runtime. Programmer may choose to implement such funcitonality to integrate their own event models.

This is an example of a key principle in computing - ABSTRACTION. This is now part of the UK's Computing curriculum in schools... so ask your teacher about it. :-)

An EventModel implementation is provided in the MicroBitMessageBus class.

Definition at line 54 of file EventModel.h.

Member Function Documentation

virtual int add ( MicroBitListener *  listener ) [virtual]

Add the given MicroBitListener to the list of event handlers, unconditionally.

Parameters:
listenerThe MicroBitListener to validate.
Returns:
This default implementation simply returns MICROBIT_NOT_SUPPORTED.

Reimplemented in MicroBitMessageBus.

Definition at line 81 of file EventModel.h.

MicroBitListener* elementAt ( int  n )

Returns the MicroBitListener at the given position in the list.

Parameters:
nThe index of the desired MicroBitListener.
Returns:
This default implementation simply returns NULL.

Reimplemented in MicroBitMessageBus.

Definition at line 107 of file EventModel.h.

int ignore ( uint16_t  id,
uint16_t  value,
T *  object,
void(T::*)(MicroBitEvent)  handler 
)

Unregister a listener function.

Listners are identified by the Event ID, Event value and handler registered using listen().

Parameters:
idThe Event ID used to register the listener.
valueThe Event value used to register the listener.
handlerThe function used to register the listener.
Returns:
MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object pointers are NULL.

Example: 

 void SomeClass::onButtonBClick()
 {
    //do something
 }

 SomeClass s = new SomeClass();
 uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick);

 // the previously created listener is now ignored.
 uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick);

Definition at line 419 of file EventModel.h.

int ignore ( int  id,
int  value,
void(*)(MicroBitEvent)  handler 
)

Unregister a listener function.

Listeners are identified by the Event ID, Event value and handler registered using listen().

Parameters:
idThe Event ID used to register the listener.
valueThe Event value used to register the listener.
handlerThe function used to register the listener.
Returns:
MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler given is NULL.

Example: 

 void onButtonBClick(MicroBitEvent)
 {
    //do something
 }

 uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);

 // the previously created listener is now ignored.
 uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);

Definition at line 283 of file EventModel.h.

int ignore ( int  id,
int  value,
void(*)(MicroBitEvent, void *)  handler 
)

Unregister a listener function.

Listeners are identified by the Event ID, Event value and handler registered using listen().

Parameters:
idThe Event ID used to register the listener.
valueThe Event value used to register the listener.
handlerThe function used to register the listener.
Returns:
MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler given is NULL.

Example: 

 void onButtonBClick(MicroBitEvent, void* data)
 {
    //do something
 }

 uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);

 // the previously created listener is now ignored.
 uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);

Definition at line 318 of file EventModel.h.

int listen ( int  id,
int  value,
void(*)(MicroBitEvent, void *)  handler,
void *  arg,
uint16_t  flags = EVENT_LISTENER_DEFAULT_FLAGS 
)

Register a listener function.

An EventModel implementing this interface may optionally choose to override this method, if that EventModel supports asynchronous callbacks to user code, but there is no requirement to do so.

Parameters:
idThe source of messages to listen for. Events sent from any other IDs will be filtered. Use MICROBIT_ID_ANY to receive events from all components.
valueThe value of messages to listen for. Events with any other values will be filtered. Use MICROBIT_EVT_ANY to receive events of any value.
handlerThe function to call when an event is received.
argProvide the callback with in an additional argument.
flagsUser specified, implementation specific flags, that allow behaviour of this events listener to be tuned.
Returns:
MICROBIT_OK on success, or any valid error code defined in "ErrNo.h". The default implementation simply returns MICROBIT_NOT_SUPPORTED.
 void onButtonBClicked(MicroBitEvent, void* data)
 {
    //do something
 }

 // call onButtonBClicked when ever a click event from buttonB is detected.
 uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);

Definition at line 212 of file EventModel.h.

int listen ( uint16_t  id,
uint16_t  value,
T *  object,
void(T::*)(MicroBitEvent)  handler,
uint16_t  flags = EVENT_LISTENER_DEFAULT_FLAGS 
)

Register a listener function.

A registration function to allow C++ member functions (methods) to be registered as an event listener.

Parameters:
idThe source of messages to listen for. Events sent from any other IDs will be filtered. Use MICROBIT_ID_ANY to receive events from all components.
valueThe value of messages to listen for. Events with any other values will be filtered. Use MICROBIT_EVT_ANY to receive events of any value.
handerThe function to call when an event is received.
flagsUser specified, implementation specific flags, that allow behaviour of this events listener to be tuned.
Returns:
MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object pointers are NULL.
 void SomeClass::onButtonBClicked(MicroBitEvent)
 {
    //do something
 }

 SomeClass s = new SomeClass();

 uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick);
Parameters:
idThe source of messages to listen for. Events sent from any other IDs will be filtered. Use MICROBIT_ID_ANY to receive events from all components.
valueThe value of messages to listen for. Events with any other values will be filtered. Use MICROBIT_EVT_ANY to receive events of any value.
objectThe object on which the method should be invoked.
handlerThe method to call when an event is received.
Returns:
MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object pointers are NULL.

Definition at line 378 of file EventModel.h.

int listen ( int  id,
int  value,
void(*)(MicroBitEvent)  handler,
uint16_t  flags = EVENT_LISTENER_DEFAULT_FLAGS 
)

Register a listener function.

An EventModel implementing this interface may optionally choose to override this method, if that EventModel supports asynchronous callbacks to user code, but there is no requirement to do so.

Parameters:
idThe source of messages to listen for. Events sent from any other IDs will be filtered. Use MICROBIT_ID_ANY to receive events from all components.
valueThe value of messages to listen for. Events with any other values will be filtered. Use MICROBIT_EVT_ANY to receive events of any value.
handlerThe function to call when an event is received.
flagsUser specified, implementation specific flags, that allow behaviour of this events listener to be tuned.
Returns:
MICROBIT_OK on success, or any valid error code defined in "ErrNo.h". The default implementation simply returns MICROBIT_NOT_SUPPORTED.
 void onButtonBClicked(MicroBitEvent)
 {
    //do something
 }

 // call onButtonBClicked when ever a click event from buttonB is detected.
 uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);

Definition at line 164 of file EventModel.h.

virtual int remove ( MicroBitListener *  listener ) [virtual]

Remove the given MicroBitListener from the list of event handlers.

Parameters:
listenerThe MicroBitListener to remove.
Returns:
This default implementation simply returns MICROBIT_NOT_SUPPORTED.

Reimplemented in MicroBitMessageBus.

Definition at line 94 of file EventModel.h.

virtual int send ( MicroBitEvent  evt ) [virtual]

Queues the given event to be sent to all registered recipients.

The method of delivery will vary depending on the underlying implementation.

Parameters:
Theevent to send.
Returns:
This default implementation simply returns MICROBIT_NOT_SUPPORTED.

Reimplemented in MicroBitMessageBus.

Definition at line 68 of file EventModel.h.

static int setDefaultEventModel ( EventModel &  model ) [static]

Define the default EventModel to use for events raised and consumed by the microbit-dal runtime.

The default EventModel may be changed at any time.

Parameters:
modelA new instance of an EventModel to use as the default.
Returns:
MICROBIT_OK on success.

Example: 

 MicroBitMessageBus b();
 EventModel:setDefaultEventModel(b);

Definition at line 127 of file EventModel.h.

Field Documentation

EventModel * defaultEventBus = NULL [static]

Class definition for a MicroBitEvent.

It represents a common event that is generated by the various components on the micro:bit.

Definition at line 58 of file EventModel.h.

Generated on Tue Jul 12 2022 19:58:09 by  doxygen 1.7.2