Cefn Hoile / microbit-dal

Attempting to publish a tree

Dependencies:   BLE_API mbed-dev-bin nRF51822

Fork of microbit-dal by Lancaster University

inc/core/EventModel.h@1:8aa5cdb4ab67, 2016-04-07 (annotated)

Committer:
Jonathan Austin
Date:
Thu Apr 07 01:33:22 2016 +0100
Revision:
1:8aa5cdb4ab67
Synchronized with git rev 55cb9199

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Jonathan Austin 1:8aa5cdb4ab67 1 /*
Jonathan Austin 1:8aa5cdb4ab67 2 The MIT License (MIT)
Jonathan Austin 1:8aa5cdb4ab67 3
Jonathan Austin 1:8aa5cdb4ab67 4 Copyright (c) 2016 British Broadcasting Corporation.
Jonathan Austin 1:8aa5cdb4ab67 5 This software is provided by Lancaster University by arrangement with the BBC.
Jonathan Austin 1:8aa5cdb4ab67 6
Jonathan Austin 1:8aa5cdb4ab67 7 Permission is hereby granted, free of charge, to any person obtaining a
Jonathan Austin 1:8aa5cdb4ab67 8 copy of this software and associated documentation files (the "Software"),
Jonathan Austin 1:8aa5cdb4ab67 9 to deal in the Software without restriction, including without limitation
Jonathan Austin 1:8aa5cdb4ab67 10 the rights to use, copy, modify, merge, publish, distribute, sublicense,
Jonathan Austin 1:8aa5cdb4ab67 11 and/or sell copies of the Software, and to permit persons to whom the
Jonathan Austin 1:8aa5cdb4ab67 12 Software is furnished to do so, subject to the following conditions:
Jonathan Austin 1:8aa5cdb4ab67 13
Jonathan Austin 1:8aa5cdb4ab67 14 The above copyright notice and this permission notice shall be included in
Jonathan Austin 1:8aa5cdb4ab67 15 all copies or substantial portions of the Software.
Jonathan Austin 1:8aa5cdb4ab67 16
Jonathan Austin 1:8aa5cdb4ab67 17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
Jonathan Austin 1:8aa5cdb4ab67 18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
Jonathan Austin 1:8aa5cdb4ab67 19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
Jonathan Austin 1:8aa5cdb4ab67 20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
Jonathan Austin 1:8aa5cdb4ab67 21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
Jonathan Austin 1:8aa5cdb4ab67 22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
Jonathan Austin 1:8aa5cdb4ab67 23 DEALINGS IN THE SOFTWARE.
Jonathan Austin 1:8aa5cdb4ab67 24 */
Jonathan Austin 1:8aa5cdb4ab67 25
Jonathan Austin 1:8aa5cdb4ab67 26 #ifndef EVENT_MODEL_H
Jonathan Austin 1:8aa5cdb4ab67 27 #define EVENT_MODEL_H
Jonathan Austin 1:8aa5cdb4ab67 28
Jonathan Austin 1:8aa5cdb4ab67 29 #include "mbed.h"
Jonathan Austin 1:8aa5cdb4ab67 30 #include "MicroBitConfig.h"
Jonathan Austin 1:8aa5cdb4ab67 31 #include "MicroBitComponent.h"
Jonathan Austin 1:8aa5cdb4ab67 32 #include "MicroBitEvent.h"
Jonathan Austin 1:8aa5cdb4ab67 33 #include "MicroBitListener.h"
Jonathan Austin 1:8aa5cdb4ab67 34 #include "ErrorNo.h"
Jonathan Austin 1:8aa5cdb4ab67 35
Jonathan Austin 1:8aa5cdb4ab67 36 /**
Jonathan Austin 1:8aa5cdb4ab67 37 * Class definition for the micro:bit EventModel.
Jonathan Austin 1:8aa5cdb4ab67 38 *
Jonathan Austin 1:8aa5cdb4ab67 39 * It is common to need to send events from one part of a program (or system) to another.
Jonathan Austin 1:8aa5cdb4ab67 40 * The way that these events are stored and delivered is known as an Event Model...
Jonathan Austin 1:8aa5cdb4ab67 41 *
Jonathan Austin 1:8aa5cdb4ab67 42 * The micro:bit can be programmed in a number of languages, and it not be good to
Jonathan Austin 1:8aa5cdb4ab67 43 * constrain those languages to any particular event model (e.g. they may have their own already).
Jonathan Austin 1:8aa5cdb4ab67 44 *
Jonathan Austin 1:8aa5cdb4ab67 45 * This class defines the functionality an event model needs to have to be able to interact
Jonathan Austin 1:8aa5cdb4ab67 46 * with events generated and/or used by the micro:bit runtime. Programmer may choose to implement
Jonathan Austin 1:8aa5cdb4ab67 47 * such funcitonality to integrate their own event models.
Jonathan Austin 1:8aa5cdb4ab67 48 *
Jonathan Austin 1:8aa5cdb4ab67 49 * This is an example of a key principle in computing - ABSTRACTION. This is now part of the
Jonathan Austin 1:8aa5cdb4ab67 50 * UK's Computing curriculum in schools... so ask your teacher about it. :-)
Jonathan Austin 1:8aa5cdb4ab67 51 *
Jonathan Austin 1:8aa5cdb4ab67 52 * An EventModel implementation is provided in the MicroBitMessageBus class.
Jonathan Austin 1:8aa5cdb4ab67 53 */
Jonathan Austin 1:8aa5cdb4ab67 54 class EventModel
Jonathan Austin 1:8aa5cdb4ab67 55 {
Jonathan Austin 1:8aa5cdb4ab67 56 public:
Jonathan Austin 1:8aa5cdb4ab67 57
Jonathan Austin 1:8aa5cdb4ab67 58 static EventModel *defaultEventBus;
Jonathan Austin 1:8aa5cdb4ab67 59
Jonathan Austin 1:8aa5cdb4ab67 60 /**
Jonathan Austin 1:8aa5cdb4ab67 61 * Queues the given event to be sent to all registered recipients.
Jonathan Austin 1:8aa5cdb4ab67 62 * The method of delivery will vary depending on the underlying implementation.
Jonathan Austin 1:8aa5cdb4ab67 63 *
Jonathan Austin 1:8aa5cdb4ab67 64 * @param The event to send.
Jonathan Austin 1:8aa5cdb4ab67 65 *
Jonathan Austin 1:8aa5cdb4ab67 66 * @return This default implementation simply returns MICROBIT_NOT_SUPPORTED.
Jonathan Austin 1:8aa5cdb4ab67 67 */
Jonathan Austin 1:8aa5cdb4ab67 68 virtual int send(MicroBitEvent evt)
Jonathan Austin 1:8aa5cdb4ab67 69 {
Jonathan Austin 1:8aa5cdb4ab67 70 (void) evt;
Jonathan Austin 1:8aa5cdb4ab67 71 return MICROBIT_NOT_SUPPORTED;
Jonathan Austin 1:8aa5cdb4ab67 72 }
Jonathan Austin 1:8aa5cdb4ab67 73
Jonathan Austin 1:8aa5cdb4ab67 74 /**
Jonathan Austin 1:8aa5cdb4ab67 75 * Add the given MicroBitListener to the list of event handlers, unconditionally.
Jonathan Austin 1:8aa5cdb4ab67 76 *
Jonathan Austin 1:8aa5cdb4ab67 77 * @param listener The MicroBitListener to validate.
Jonathan Austin 1:8aa5cdb4ab67 78 *
Jonathan Austin 1:8aa5cdb4ab67 79 * @return This default implementation simply returns MICROBIT_NOT_SUPPORTED.
Jonathan Austin 1:8aa5cdb4ab67 80 */
Jonathan Austin 1:8aa5cdb4ab67 81 virtual int add(MicroBitListener *listener)
Jonathan Austin 1:8aa5cdb4ab67 82 {
Jonathan Austin 1:8aa5cdb4ab67 83 (void) listener;
Jonathan Austin 1:8aa5cdb4ab67 84 return MICROBIT_NOT_SUPPORTED;
Jonathan Austin 1:8aa5cdb4ab67 85 }
Jonathan Austin 1:8aa5cdb4ab67 86
Jonathan Austin 1:8aa5cdb4ab67 87 /**
Jonathan Austin 1:8aa5cdb4ab67 88 * Remove the given MicroBitListener from the list of event handlers.
Jonathan Austin 1:8aa5cdb4ab67 89 *
Jonathan Austin 1:8aa5cdb4ab67 90 * @param listener The MicroBitListener to remove.
Jonathan Austin 1:8aa5cdb4ab67 91 *
Jonathan Austin 1:8aa5cdb4ab67 92 * @return This default implementation simply returns MICROBIT_NOT_SUPPORTED.
Jonathan Austin 1:8aa5cdb4ab67 93 */
Jonathan Austin 1:8aa5cdb4ab67 94 virtual int remove(MicroBitListener *listener)
Jonathan Austin 1:8aa5cdb4ab67 95 {
Jonathan Austin 1:8aa5cdb4ab67 96 (void) listener;
Jonathan Austin 1:8aa5cdb4ab67 97 return MICROBIT_NOT_SUPPORTED;
Jonathan Austin 1:8aa5cdb4ab67 98 }
Jonathan Austin 1:8aa5cdb4ab67 99
Jonathan Austin 1:8aa5cdb4ab67 100 /**
Jonathan Austin 1:8aa5cdb4ab67 101 * Returns the MicroBitListener at the given position in the list.
Jonathan Austin 1:8aa5cdb4ab67 102 *
Jonathan Austin 1:8aa5cdb4ab67 103 * @param n The index of the desired MicroBitListener.
Jonathan Austin 1:8aa5cdb4ab67 104 *
Jonathan Austin 1:8aa5cdb4ab67 105 * @return This default implementation simply returns NULL.
Jonathan Austin 1:8aa5cdb4ab67 106 */
Jonathan Austin 1:8aa5cdb4ab67 107 MicroBitListener *elementAt(int n)
Jonathan Austin 1:8aa5cdb4ab67 108 {
Jonathan Austin 1:8aa5cdb4ab67 109 (void) n;
Jonathan Austin 1:8aa5cdb4ab67 110 return NULL;
Jonathan Austin 1:8aa5cdb4ab67 111 }
Jonathan Austin 1:8aa5cdb4ab67 112
Jonathan Austin 1:8aa5cdb4ab67 113 /**
Jonathan Austin 1:8aa5cdb4ab67 114 * Define the default EventModel to use for events raised and consumed by the microbit-dal runtime.
Jonathan Austin 1:8aa5cdb4ab67 115 * The default EventModel may be changed at any time.
Jonathan Austin 1:8aa5cdb4ab67 116 *
Jonathan Austin 1:8aa5cdb4ab67 117 * @param model A new instance of an EventModel to use as the default.
Jonathan Austin 1:8aa5cdb4ab67 118 *
Jonathan Austin 1:8aa5cdb4ab67 119 * @return MICROBIT_OK on success.
Jonathan Austin 1:8aa5cdb4ab67 120 *
Jonathan Austin 1:8aa5cdb4ab67 121 * Example:
Jonathan Austin 1:8aa5cdb4ab67 122 * @code
Jonathan Austin 1:8aa5cdb4ab67 123 * MicroBitMessageBus b();
Jonathan Austin 1:8aa5cdb4ab67 124 * EventModel:setDefaultEventModel(b);
Jonathan Austin 1:8aa5cdb4ab67 125 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 126 */
Jonathan Austin 1:8aa5cdb4ab67 127 static int setDefaultEventModel(EventModel &model)
Jonathan Austin 1:8aa5cdb4ab67 128 {
Jonathan Austin 1:8aa5cdb4ab67 129 EventModel::defaultEventBus = &model;
Jonathan Austin 1:8aa5cdb4ab67 130 return MICROBIT_OK;
Jonathan Austin 1:8aa5cdb4ab67 131 }
Jonathan Austin 1:8aa5cdb4ab67 132
Jonathan Austin 1:8aa5cdb4ab67 133 /**
Jonathan Austin 1:8aa5cdb4ab67 134 * Register a listener function.
Jonathan Austin 1:8aa5cdb4ab67 135 *
Jonathan Austin 1:8aa5cdb4ab67 136 * An EventModel implementing this interface may optionally choose to override this method,
Jonathan Austin 1:8aa5cdb4ab67 137 * if that EventModel supports asynchronous callbacks to user code, but there is no
Jonathan Austin 1:8aa5cdb4ab67 138 * requirement to do so.
Jonathan Austin 1:8aa5cdb4ab67 139 *
Jonathan Austin 1:8aa5cdb4ab67 140 * @param id The source of messages to listen for. Events sent from any other IDs will be filtered.
Jonathan Austin 1:8aa5cdb4ab67 141 * Use MICROBIT_ID_ANY to receive events from all components.
Jonathan Austin 1:8aa5cdb4ab67 142 *
Jonathan Austin 1:8aa5cdb4ab67 143 * @param value The value of messages to listen for. Events with any other values will be filtered.
Jonathan Austin 1:8aa5cdb4ab67 144 * Use MICROBIT_EVT_ANY to receive events of any value.
Jonathan Austin 1:8aa5cdb4ab67 145 *
Jonathan Austin 1:8aa5cdb4ab67 146 * @param handler The function to call when an event is received.
Jonathan Austin 1:8aa5cdb4ab67 147 *
Jonathan Austin 1:8aa5cdb4ab67 148 * @param flags User specified, implementation specific flags, that allow behaviour of this events listener
Jonathan Austin 1:8aa5cdb4ab67 149 * to be tuned.
Jonathan Austin 1:8aa5cdb4ab67 150 *
Jonathan Austin 1:8aa5cdb4ab67 151 * @return MICROBIT_OK on success, or any valid error code defined in "ErrNo.h". The default implementation
Jonathan Austin 1:8aa5cdb4ab67 152 * simply returns MICROBIT_NOT_SUPPORTED.
Jonathan Austin 1:8aa5cdb4ab67 153 *
Jonathan Austin 1:8aa5cdb4ab67 154 * @code
Jonathan Austin 1:8aa5cdb4ab67 155 * void onButtonBClicked(MicroBitEvent)
Jonathan Austin 1:8aa5cdb4ab67 156 * {
Jonathan Austin 1:8aa5cdb4ab67 157 * //do something
Jonathan Austin 1:8aa5cdb4ab67 158 * }
Jonathan Austin 1:8aa5cdb4ab67 159 *
Jonathan Austin 1:8aa5cdb4ab67 160 * // call onButtonBClicked when ever a click event from buttonB is detected.
Jonathan Austin 1:8aa5cdb4ab67 161 * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);
Jonathan Austin 1:8aa5cdb4ab67 162 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 163 */
Jonathan Austin 1:8aa5cdb4ab67 164 int listen(int id, int value, void (*handler)(MicroBitEvent), uint16_t flags = EVENT_LISTENER_DEFAULT_FLAGS)
Jonathan Austin 1:8aa5cdb4ab67 165 {
Jonathan Austin 1:8aa5cdb4ab67 166 if (handler == NULL)
Jonathan Austin 1:8aa5cdb4ab67 167 return MICROBIT_INVALID_PARAMETER;
Jonathan Austin 1:8aa5cdb4ab67 168
Jonathan Austin 1:8aa5cdb4ab67 169 MicroBitListener *newListener = new MicroBitListener(id, value, handler, flags);
Jonathan Austin 1:8aa5cdb4ab67 170
Jonathan Austin 1:8aa5cdb4ab67 171 if(add(newListener) == MICROBIT_OK)
Jonathan Austin 1:8aa5cdb4ab67 172 return MICROBIT_OK;
Jonathan Austin 1:8aa5cdb4ab67 173
Jonathan Austin 1:8aa5cdb4ab67 174 delete newListener;
Jonathan Austin 1:8aa5cdb4ab67 175
Jonathan Austin 1:8aa5cdb4ab67 176 return MICROBIT_NOT_SUPPORTED;
Jonathan Austin 1:8aa5cdb4ab67 177 }
Jonathan Austin 1:8aa5cdb4ab67 178
Jonathan Austin 1:8aa5cdb4ab67 179 /**
Jonathan Austin 1:8aa5cdb4ab67 180 * Register a listener function.
Jonathan Austin 1:8aa5cdb4ab67 181 *
Jonathan Austin 1:8aa5cdb4ab67 182 * An EventModel implementing this interface may optionally choose to override this method,
Jonathan Austin 1:8aa5cdb4ab67 183 * if that EventModel supports asynchronous callbacks to user code, but there is no
Jonathan Austin 1:8aa5cdb4ab67 184 * requirement to do so.
Jonathan Austin 1:8aa5cdb4ab67 185 *
Jonathan Austin 1:8aa5cdb4ab67 186 * @param id The source of messages to listen for. Events sent from any other IDs will be filtered.
Jonathan Austin 1:8aa5cdb4ab67 187 * Use MICROBIT_ID_ANY to receive events from all components.
Jonathan Austin 1:8aa5cdb4ab67 188 *
Jonathan Austin 1:8aa5cdb4ab67 189 * @param value The value of messages to listen for. Events with any other values will be filtered.
Jonathan Austin 1:8aa5cdb4ab67 190 * Use MICROBIT_EVT_ANY to receive events of any value.
Jonathan Austin 1:8aa5cdb4ab67 191 *
Jonathan Austin 1:8aa5cdb4ab67 192 * @param handler The function to call when an event is received.
Jonathan Austin 1:8aa5cdb4ab67 193 *
Jonathan Austin 1:8aa5cdb4ab67 194 * @param arg Provide the callback with in an additional argument.
Jonathan Austin 1:8aa5cdb4ab67 195 *
Jonathan Austin 1:8aa5cdb4ab67 196 * @param flags User specified, implementation specific flags, that allow behaviour of this events listener
Jonathan Austin 1:8aa5cdb4ab67 197 * to be tuned.
Jonathan Austin 1:8aa5cdb4ab67 198 *
Jonathan Austin 1:8aa5cdb4ab67 199 * @return MICROBIT_OK on success, or any valid error code defined in "ErrNo.h". The default implementation
Jonathan Austin 1:8aa5cdb4ab67 200 * simply returns MICROBIT_NOT_SUPPORTED.
Jonathan Austin 1:8aa5cdb4ab67 201 *
Jonathan Austin 1:8aa5cdb4ab67 202 * @code
Jonathan Austin 1:8aa5cdb4ab67 203 * void onButtonBClicked(MicroBitEvent, void* data)
Jonathan Austin 1:8aa5cdb4ab67 204 * {
Jonathan Austin 1:8aa5cdb4ab67 205 * //do something
Jonathan Austin 1:8aa5cdb4ab67 206 * }
Jonathan Austin 1:8aa5cdb4ab67 207 *
Jonathan Austin 1:8aa5cdb4ab67 208 * // call onButtonBClicked when ever a click event from buttonB is detected.
Jonathan Austin 1:8aa5cdb4ab67 209 * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);
Jonathan Austin 1:8aa5cdb4ab67 210 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 211 */
Jonathan Austin 1:8aa5cdb4ab67 212 int listen(int id, int value, void (*handler)(MicroBitEvent, void*), void* arg, uint16_t flags = EVENT_LISTENER_DEFAULT_FLAGS)
Jonathan Austin 1:8aa5cdb4ab67 213 {
Jonathan Austin 1:8aa5cdb4ab67 214 if (handler == NULL)
Jonathan Austin 1:8aa5cdb4ab67 215 return MICROBIT_INVALID_PARAMETER;
Jonathan Austin 1:8aa5cdb4ab67 216
Jonathan Austin 1:8aa5cdb4ab67 217 MicroBitListener *newListener = new MicroBitListener(id, value, handler, arg, flags);
Jonathan Austin 1:8aa5cdb4ab67 218
Jonathan Austin 1:8aa5cdb4ab67 219 if(add(newListener) == MICROBIT_OK)
Jonathan Austin 1:8aa5cdb4ab67 220 return MICROBIT_OK;
Jonathan Austin 1:8aa5cdb4ab67 221
Jonathan Austin 1:8aa5cdb4ab67 222 delete newListener;
Jonathan Austin 1:8aa5cdb4ab67 223
Jonathan Austin 1:8aa5cdb4ab67 224 return MICROBIT_NOT_SUPPORTED;
Jonathan Austin 1:8aa5cdb4ab67 225 }
Jonathan Austin 1:8aa5cdb4ab67 226
Jonathan Austin 1:8aa5cdb4ab67 227 /**
Jonathan Austin 1:8aa5cdb4ab67 228 * Register a listener function.
Jonathan Austin 1:8aa5cdb4ab67 229 *
Jonathan Austin 1:8aa5cdb4ab67 230 * @param id The source of messages to listen for. Events sent from any other IDs will be filtered.
Jonathan Austin 1:8aa5cdb4ab67 231 * Use MICROBIT_ID_ANY to receive events from all components.
Jonathan Austin 1:8aa5cdb4ab67 232 *
Jonathan Austin 1:8aa5cdb4ab67 233 * @param value The value of messages to listen for. Events with any other values will be filtered.
Jonathan Austin 1:8aa5cdb4ab67 234 * Use MICROBIT_EVT_ANY to receive events of any value.
Jonathan Austin 1:8aa5cdb4ab67 235 *
Jonathan Austin 1:8aa5cdb4ab67 236 * @param hander The function to call when an event is received.
Jonathan Austin 1:8aa5cdb4ab67 237 *
Jonathan Austin 1:8aa5cdb4ab67 238 * @param flags User specified, implementation specific flags, that allow behaviour of this events listener
Jonathan Austin 1:8aa5cdb4ab67 239 * to be tuned.
Jonathan Austin 1:8aa5cdb4ab67 240 *
Jonathan Austin 1:8aa5cdb4ab67 241 * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object
Jonathan Austin 1:8aa5cdb4ab67 242 * pointers are NULL.
Jonathan Austin 1:8aa5cdb4ab67 243 *
Jonathan Austin 1:8aa5cdb4ab67 244 * @code
Jonathan Austin 1:8aa5cdb4ab67 245 * void SomeClass::onButtonBClicked(MicroBitEvent)
Jonathan Austin 1:8aa5cdb4ab67 246 * {
Jonathan Austin 1:8aa5cdb4ab67 247 * //do something
Jonathan Austin 1:8aa5cdb4ab67 248 * }
Jonathan Austin 1:8aa5cdb4ab67 249 *
Jonathan Austin 1:8aa5cdb4ab67 250 * SomeClass s = new SomeClass();
Jonathan Austin 1:8aa5cdb4ab67 251 *
Jonathan Austin 1:8aa5cdb4ab67 252 * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick);
Jonathan Austin 1:8aa5cdb4ab67 253 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 254 */
Jonathan Austin 1:8aa5cdb4ab67 255 template <typename T>
Jonathan Austin 1:8aa5cdb4ab67 256 int listen(uint16_t id, uint16_t value, T* object, void (T::*handler)(MicroBitEvent), uint16_t flags = EVENT_LISTENER_DEFAULT_FLAGS);
Jonathan Austin 1:8aa5cdb4ab67 257
Jonathan Austin 1:8aa5cdb4ab67 258
Jonathan Austin 1:8aa5cdb4ab67 259 /**
Jonathan Austin 1:8aa5cdb4ab67 260 * Unregister a listener function.
Jonathan Austin 1:8aa5cdb4ab67 261 * Listeners are identified by the Event ID, Event value and handler registered using listen().
Jonathan Austin 1:8aa5cdb4ab67 262 *
Jonathan Austin 1:8aa5cdb4ab67 263 * @param id The Event ID used to register the listener.
Jonathan Austin 1:8aa5cdb4ab67 264 * @param value The Event value used to register the listener.
Jonathan Austin 1:8aa5cdb4ab67 265 * @param handler The function used to register the listener.
Jonathan Austin 1:8aa5cdb4ab67 266 *
Jonathan Austin 1:8aa5cdb4ab67 267 * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler
Jonathan Austin 1:8aa5cdb4ab67 268 * given is NULL.
Jonathan Austin 1:8aa5cdb4ab67 269 *
Jonathan Austin 1:8aa5cdb4ab67 270 * Example:
Jonathan Austin 1:8aa5cdb4ab67 271 * @code
Jonathan Austin 1:8aa5cdb4ab67 272 * void onButtonBClick(MicroBitEvent)
Jonathan Austin 1:8aa5cdb4ab67 273 * {
Jonathan Austin 1:8aa5cdb4ab67 274 * //do something
Jonathan Austin 1:8aa5cdb4ab67 275 * }
Jonathan Austin 1:8aa5cdb4ab67 276 *
Jonathan Austin 1:8aa5cdb4ab67 277 * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);
Jonathan Austin 1:8aa5cdb4ab67 278 *
Jonathan Austin 1:8aa5cdb4ab67 279 * // the previously created listener is now ignored.
Jonathan Austin 1:8aa5cdb4ab67 280 * uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);
Jonathan Austin 1:8aa5cdb4ab67 281 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 282 */
Jonathan Austin 1:8aa5cdb4ab67 283 int ignore(int id, int value, void (*handler)(MicroBitEvent))
Jonathan Austin 1:8aa5cdb4ab67 284 {
Jonathan Austin 1:8aa5cdb4ab67 285 if (handler == NULL)
Jonathan Austin 1:8aa5cdb4ab67 286 return MICROBIT_INVALID_PARAMETER;
Jonathan Austin 1:8aa5cdb4ab67 287
Jonathan Austin 1:8aa5cdb4ab67 288 MicroBitListener listener(id, value, handler);
Jonathan Austin 1:8aa5cdb4ab67 289 remove(&listener);
Jonathan Austin 1:8aa5cdb4ab67 290
Jonathan Austin 1:8aa5cdb4ab67 291 return MICROBIT_OK;
Jonathan Austin 1:8aa5cdb4ab67 292 }
Jonathan Austin 1:8aa5cdb4ab67 293
Jonathan Austin 1:8aa5cdb4ab67 294 /**
Jonathan Austin 1:8aa5cdb4ab67 295 * Unregister a listener function.
Jonathan Austin 1:8aa5cdb4ab67 296 * Listeners are identified by the Event ID, Event value and handler registered using listen().
Jonathan Austin 1:8aa5cdb4ab67 297 *
Jonathan Austin 1:8aa5cdb4ab67 298 * @param id The Event ID used to register the listener.
Jonathan Austin 1:8aa5cdb4ab67 299 * @param value The Event value used to register the listener.
Jonathan Austin 1:8aa5cdb4ab67 300 * @param handler The function used to register the listener.
Jonathan Austin 1:8aa5cdb4ab67 301 *
Jonathan Austin 1:8aa5cdb4ab67 302 * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler
Jonathan Austin 1:8aa5cdb4ab67 303 * given is NULL.
Jonathan Austin 1:8aa5cdb4ab67 304 *
Jonathan Austin 1:8aa5cdb4ab67 305 * Example:
Jonathan Austin 1:8aa5cdb4ab67 306 * @code
Jonathan Austin 1:8aa5cdb4ab67 307 * void onButtonBClick(MicroBitEvent, void* data)
Jonathan Austin 1:8aa5cdb4ab67 308 * {
Jonathan Austin 1:8aa5cdb4ab67 309 * //do something
Jonathan Austin 1:8aa5cdb4ab67 310 * }
Jonathan Austin 1:8aa5cdb4ab67 311 *
Jonathan Austin 1:8aa5cdb4ab67 312 * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);
Jonathan Austin 1:8aa5cdb4ab67 313 *
Jonathan Austin 1:8aa5cdb4ab67 314 * // the previously created listener is now ignored.
Jonathan Austin 1:8aa5cdb4ab67 315 * uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);
Jonathan Austin 1:8aa5cdb4ab67 316 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 317 */
Jonathan Austin 1:8aa5cdb4ab67 318 int ignore(int id, int value, void (*handler)(MicroBitEvent, void*))
Jonathan Austin 1:8aa5cdb4ab67 319 {
Jonathan Austin 1:8aa5cdb4ab67 320 if (handler == NULL)
Jonathan Austin 1:8aa5cdb4ab67 321 return MICROBIT_INVALID_PARAMETER;
Jonathan Austin 1:8aa5cdb4ab67 322
Jonathan Austin 1:8aa5cdb4ab67 323 MicroBitListener listener(id, value, handler, NULL);
Jonathan Austin 1:8aa5cdb4ab67 324 remove(&listener);
Jonathan Austin 1:8aa5cdb4ab67 325
Jonathan Austin 1:8aa5cdb4ab67 326 return MICROBIT_OK;
Jonathan Austin 1:8aa5cdb4ab67 327 }
Jonathan Austin 1:8aa5cdb4ab67 328
Jonathan Austin 1:8aa5cdb4ab67 329 /**
Jonathan Austin 1:8aa5cdb4ab67 330 * Unregister a listener function.
Jonathan Austin 1:8aa5cdb4ab67 331 * Listners are identified by the Event ID, Event value and handler registered using listen().
Jonathan Austin 1:8aa5cdb4ab67 332 *
Jonathan Austin 1:8aa5cdb4ab67 333 * @param id The Event ID used to register the listener.
Jonathan Austin 1:8aa5cdb4ab67 334 * @param value The Event value used to register the listener.
Jonathan Austin 1:8aa5cdb4ab67 335 * @param handler The function used to register the listener.
Jonathan Austin 1:8aa5cdb4ab67 336 *
Jonathan Austin 1:8aa5cdb4ab67 337 * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object
Jonathan Austin 1:8aa5cdb4ab67 338 * pointers are NULL.
Jonathan Austin 1:8aa5cdb4ab67 339 *
Jonathan Austin 1:8aa5cdb4ab67 340 * Example:
Jonathan Austin 1:8aa5cdb4ab67 341 * @code
Jonathan Austin 1:8aa5cdb4ab67 342 *
Jonathan Austin 1:8aa5cdb4ab67 343 * void SomeClass::onButtonBClick()
Jonathan Austin 1:8aa5cdb4ab67 344 * {
Jonathan Austin 1:8aa5cdb4ab67 345 * //do something
Jonathan Austin 1:8aa5cdb4ab67 346 * }
Jonathan Austin 1:8aa5cdb4ab67 347 *
Jonathan Austin 1:8aa5cdb4ab67 348 * SomeClass s = new SomeClass();
Jonathan Austin 1:8aa5cdb4ab67 349 * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick);
Jonathan Austin 1:8aa5cdb4ab67 350 *
Jonathan Austin 1:8aa5cdb4ab67 351 * // the previously created listener is now ignored.
Jonathan Austin 1:8aa5cdb4ab67 352 * uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick);
Jonathan Austin 1:8aa5cdb4ab67 353 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 354 */
Jonathan Austin 1:8aa5cdb4ab67 355 template <typename T>
Jonathan Austin 1:8aa5cdb4ab67 356 int ignore(uint16_t id, uint16_t value, T* object, void (T::*handler)(MicroBitEvent));
Jonathan Austin 1:8aa5cdb4ab67 357
Jonathan Austin 1:8aa5cdb4ab67 358 };
Jonathan Austin 1:8aa5cdb4ab67 359
Jonathan Austin 1:8aa5cdb4ab67 360 /**
Jonathan Austin 1:8aa5cdb4ab67 361 * A registration function to allow C++ member functions (methods) to be registered as an event
Jonathan Austin 1:8aa5cdb4ab67 362 * listener.
Jonathan Austin 1:8aa5cdb4ab67 363 *
Jonathan Austin 1:8aa5cdb4ab67 364 * @param id The source of messages to listen for. Events sent from any other IDs will be filtered.
Jonathan Austin 1:8aa5cdb4ab67 365 * Use MICROBIT_ID_ANY to receive events from all components.
Jonathan Austin 1:8aa5cdb4ab67 366 *
Jonathan Austin 1:8aa5cdb4ab67 367 * @param value The value of messages to listen for. Events with any other values will be filtered.
Jonathan Austin 1:8aa5cdb4ab67 368 * Use MICROBIT_EVT_ANY to receive events of any value.
Jonathan Austin 1:8aa5cdb4ab67 369 *
Jonathan Austin 1:8aa5cdb4ab67 370 * @param object The object on which the method should be invoked.
Jonathan Austin 1:8aa5cdb4ab67 371 *
Jonathan Austin 1:8aa5cdb4ab67 372 * @param handler The method to call when an event is received.
Jonathan Austin 1:8aa5cdb4ab67 373 *
Jonathan Austin 1:8aa5cdb4ab67 374 * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object
Jonathan Austin 1:8aa5cdb4ab67 375 * pointers are NULL.
Jonathan Austin 1:8aa5cdb4ab67 376 */
Jonathan Austin 1:8aa5cdb4ab67 377 template <typename T>
Jonathan Austin 1:8aa5cdb4ab67 378 int EventModel::listen(uint16_t id, uint16_t value, T* object, void (T::*handler)(MicroBitEvent), uint16_t flags)
Jonathan Austin 1:8aa5cdb4ab67 379 {
Jonathan Austin 1:8aa5cdb4ab67 380 if (object == NULL || handler == NULL)
Jonathan Austin 1:8aa5cdb4ab67 381 return MICROBIT_INVALID_PARAMETER;
Jonathan Austin 1:8aa5cdb4ab67 382
Jonathan Austin 1:8aa5cdb4ab67 383 MicroBitListener *newListener = new MicroBitListener(id, value, object, handler, flags);
Jonathan Austin 1:8aa5cdb4ab67 384
Jonathan Austin 1:8aa5cdb4ab67 385 if(add(newListener) == MICROBIT_OK)
Jonathan Austin 1:8aa5cdb4ab67 386 return MICROBIT_OK;
Jonathan Austin 1:8aa5cdb4ab67 387
Jonathan Austin 1:8aa5cdb4ab67 388 delete newListener;
Jonathan Austin 1:8aa5cdb4ab67 389 return MICROBIT_NOT_SUPPORTED;
Jonathan Austin 1:8aa5cdb4ab67 390 }
Jonathan Austin 1:8aa5cdb4ab67 391
Jonathan Austin 1:8aa5cdb4ab67 392 /**
Jonathan Austin 1:8aa5cdb4ab67 393 * Unregister a listener function.
Jonathan Austin 1:8aa5cdb4ab67 394 * Listners are identified by the Event ID, Event value and handler registered using listen().
Jonathan Austin 1:8aa5cdb4ab67 395 *
Jonathan Austin 1:8aa5cdb4ab67 396 * @param id The Event ID used to register the listener.
Jonathan Austin 1:8aa5cdb4ab67 397 * @param value The Event value used to register the listener.
Jonathan Austin 1:8aa5cdb4ab67 398 * @param handler The function used to register the listener.
Jonathan Austin 1:8aa5cdb4ab67 399 *
Jonathan Austin 1:8aa5cdb4ab67 400 * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object
Jonathan Austin 1:8aa5cdb4ab67 401 * pointers are NULL.
Jonathan Austin 1:8aa5cdb4ab67 402 *
Jonathan Austin 1:8aa5cdb4ab67 403 * Example:
Jonathan Austin 1:8aa5cdb4ab67 404 * @code
Jonathan Austin 1:8aa5cdb4ab67 405 *
Jonathan Austin 1:8aa5cdb4ab67 406 * void SomeClass::onButtonBClick()
Jonathan Austin 1:8aa5cdb4ab67 407 * {
Jonathan Austin 1:8aa5cdb4ab67 408 * //do something
Jonathan Austin 1:8aa5cdb4ab67 409 * }
Jonathan Austin 1:8aa5cdb4ab67 410 *
Jonathan Austin 1:8aa5cdb4ab67 411 * SomeClass s = new SomeClass();
Jonathan Austin 1:8aa5cdb4ab67 412 * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick);
Jonathan Austin 1:8aa5cdb4ab67 413 *
Jonathan Austin 1:8aa5cdb4ab67 414 * // the previously created listener is now ignored.
Jonathan Austin 1:8aa5cdb4ab67 415 * uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick);
Jonathan Austin 1:8aa5cdb4ab67 416 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 417 */
Jonathan Austin 1:8aa5cdb4ab67 418 template <typename T>
Jonathan Austin 1:8aa5cdb4ab67 419 int EventModel::ignore(uint16_t id, uint16_t value, T* object, void (T::*handler)(MicroBitEvent))
Jonathan Austin 1:8aa5cdb4ab67 420 {
Jonathan Austin 1:8aa5cdb4ab67 421 if (handler == NULL)
Jonathan Austin 1:8aa5cdb4ab67 422 return MICROBIT_INVALID_PARAMETER;
Jonathan Austin 1:8aa5cdb4ab67 423
Jonathan Austin 1:8aa5cdb4ab67 424 MicroBitListener listener(id, value, object, handler);
Jonathan Austin 1:8aa5cdb4ab67 425 remove(&listener);
Jonathan Austin 1:8aa5cdb4ab67 426
Jonathan Austin 1:8aa5cdb4ab67 427 return MICROBIT_OK;
Jonathan Austin 1:8aa5cdb4ab67 428 }
Jonathan Austin 1:8aa5cdb4ab67 429
Jonathan Austin 1:8aa5cdb4ab67 430 #endif