Wendy Warne / microbit-dal

updates

Dependencies:   BLE_API mbed-dev-bin nRF51822

Fork of microbit-dal-eddystone by Martin Woolley

inc/core/EventModel.h@36:6837feb07da4, 2016-07-13 (annotated)

Committer:
LancasterUniversity
Date:
Wed Jul 13 12:18:15 2016 +0100
Revision:
36:6837feb07da4
Parent:
1:8aa5cdb4ab67 
Synchronized with git rev 4e71d613

Author: James Devine

microbit-dal: Added setPull to MicroBitPin



This new member function allows the configuration of the pull currently

applied to the MicroBitPin instance. This member function only has

affect when the MicroBitPin instance is in a digital input mode.

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