AceButton 1.10.0 An adjustable, compact, event-driven button library for Arduino.

AceButton.h
1 /*
2 MIT License
3
4 Copyright (c) 2018 Brian T. Park
5
6 Permission is hereby granted, free of charge, to any person obtaining a copy
7 of this software and associated documentation files (the "Software"), to deal
8 in the Software without restriction, including without limitation the rights
9 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 copies of the Software, and to permit persons to whom the Software is
11 furnished to do so, subject to the following conditions:
12
13 The above copyright notice and this permission notice shall be included in all
14 copies or substantial portions of the Software.
15
16 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 SOFTWARE.
23 */
24
25 #ifndef ACE_BUTTON_ACE_BUTTON_H
26 #define ACE_BUTTON_ACE_BUTTON_H
27
28 #include <Arduino.h>
29 #include "ButtonConfig.h"
30
31 class __FlashStringHelper;
32
33 namespace ace_button {
34
54 class AceButton {
55 public:
56 // The supported event types.
57
59 static const uint8_t kEventPressed = 0;
60
62 static const uint8_t kEventReleased = 1;
63
68 static const uint8_t kEventClicked = 2;
69
74 static const uint8_t kEventDoubleClicked = 3;
75
80 static const uint8_t kEventLongPressed = 4;
81
88 static const uint8_t kEventRepeatPressed = 5;
89
99 static const uint8_t kEventLongReleased = 6;
100
111 static const uint8_t kEventHeartBeat = 7;
112
119 static const uint8_t kButtonStateUnknown = 127;
120
126 static __FlashStringHelper* eventName(uint8_t event);
127
160 explicit AceButton(
161 uint8_t pin = 0,
162 uint8_t defaultReleasedState = HIGH,
163 uint8_t id = 0
164 ) :
165 mButtonConfig(ButtonConfig::getSystemButtonConfig()) {
166 init(pin, defaultReleasedState, id);
167 }
168
192 explicit AceButton(
193 ButtonConfig* buttonConfig,
194 uint8_t pin = 0,
195 uint8_t defaultReleasedState = HIGH,
196 uint8_t id = 0) {
197 init(buttonConfig, pin, defaultReleasedState, id);
198 }
199
205 void init(
206 uint8_t pin = 0,
207 uint8_t defaultReleasedState = HIGH,
208 uint8_t id = 0);
209
216 void init(
217 ButtonConfig* buttonConfig,
218 uint8_t pin = 0,
219 uint8_t defaultReleasedState = HIGH,
220 uint8_t id = 0);
221
223 ButtonConfig* getButtonConfig() const {
224 return mButtonConfig;
225 }
226
232 void setButtonConfig(ButtonConfig* buttonConfig) {
233 mButtonConfig = buttonConfig;
234 }
235
266 void setEventHandler(ButtonConfig::EventHandler eventHandler) {
267 mButtonConfig->setEventHandler(eventHandler);
268 }
269
271 uint8_t getPin() const { return mPin; }
272
274 uint8_t getId() const { return mId; }
275
277 uint8_t getDefaultReleasedState() const;
278
292 uint8_t getLastButtonState() const {
293 return mLastButtonState;
294 }
295
303 void check();
304
309 void checkState(uint8_t buttonState);
310
326 bool isReleased(uint8_t buttonState) const {
327 return buttonState == getDefaultReleasedState();
328 }
329
337 bool isPressedRaw() const {
338 return !isReleased(mButtonConfig->readButton(mPin));
339 }
340
341 // Some of these private methods may be useful to the calling client but I
342 // don't want to release them to the public because I want to keep the API as
343 // small as possible for easier long term maintenance. (Once a method is
344 // released to the public, it must be supported forever to ensure backwards
345 // compatibility with older client code.)
346
347 private:
348 // Disable copy-constructor and assignment operator
349 AceButton(const AceButton&) = delete;
350 AceButton& operator=(const AceButton&) = delete;
351
353 void setPin(uint8_t pin) { mPin = pin; }
354
362 void setDefaultReleasedState(uint8_t state);
363
365 void setId(uint8_t id) { mId = id; }
366
367 // Various bit masks to store a boolean flag in the 'mFlags' field.
368 // We use bit masks to save static RAM. If we had used a 'bool' type, each
369 // of these would consume one byte.
370 typedef uint16_t FlagType;
371 static const FlagType kFlagDefaultReleasedState = 0x01;
372 static const FlagType kFlagDebouncing = 0x02;
373 static const FlagType kFlagPressed = 0x04; // mLastPressTime is valid
374 static const FlagType kFlagClicked = 0x08; // mLastClickTime valid
375 static const FlagType kFlagDoubleClicked = 0x10;
376 static const FlagType kFlagLongPressed = 0x20;
377 static const FlagType kFlagRepeatPressed = 0x40; // mLastRepeatPressTime
378 static const FlagType kFlagClickPostponed = 0x80;
379 static const FlagType kFlagHeartRunning = 0x100; // mLastHeartBeatTime valid
380
381 bool isFlag(FlagType flag) const {
382 return mFlags & flag;
383 }
384
385 void setFlag(FlagType flag) {
386 mFlags |= flag;
387 }
388
389 void clearFlag(FlagType flag) {
390 mFlags &= ~flag;
391 }
392
398 bool checkDebounced(uint16_t now, uint8_t buttonState);
399
406 bool checkInitialized(uint16_t buttonState);
407
409 void checkEvent(uint16_t now, uint8_t buttonState);
410
412 void checkLongPress(uint16_t now, uint8_t buttonState);
413
415 void checkRepeatPress(uint16_t now, uint8_t buttonState);
416
418 void checkChanged(uint16_t now, uint8_t buttonState);
419
424 void checkReleased(uint16_t now, uint8_t buttonState);
425
427 void checkPressed(uint16_t now, uint8_t buttonState);
428
430 void checkClicked(uint16_t now);
431
436 void checkDoubleClicked(uint16_t now);
437
446 void checkOrphanedClick(uint16_t now);
447
452 void checkPostponedClick(uint16_t now);
453
455 void checkHeartBeat(uint16_t now);
456
509 void handleEvent(uint8_t eventType);
510
511 private:
513 ButtonConfig* mButtonConfig;
514
516 uint8_t mPin;
517
519 uint8_t mId;
520
522 FlagType mFlags;
523
528 uint8_t mLastButtonState;
529
530 // Internal states of the button debouncing and event handling.
531 // NOTE: We don't keep track of the lastDoubleClickTime, because we
532 // don't support a TripleClicked event. That may change in the future.
533 uint16_t mLastDebounceTime; // ms
534 uint16_t mLastClickTime; // ms
535 uint16_t mLastPressTime; // ms
536 uint16_t mLastRepeatPressTime; // ms
537 uint16_t mLastHeartBeatTime; // ms
538 };
539
540 }
541 #endif
ace_button::AceButton
An Adjustable Compact Event-driven (ACE) Button library that debounces and dispatches button events t...
Definition: AceButton.h:54
ace_button::AceButton::setButtonConfig
void setButtonConfig(ButtonConfig *buttonConfig)
Set the ButtonConfig associated with this Button.
Definition: AceButton.h:232
ace_button::AceButton::kEventDoubleClicked
static const uint8_t kEventDoubleClicked
Button was double-clicked.
Definition: AceButton.h:74
ace_button::AceButton::init
void init(uint8_t pin=0, uint8_t defaultReleasedState=HIGH, uint8_t id=0)
Reset the button to the initial constructed state.
Definition: AceButton.cpp:88
ace_button::AceButton::kEventClicked
static const uint8_t kEventClicked
Button was clicked (Pressed and Released within ButtonConfig::getClickDelay()).
Definition: AceButton.h:68
ace_button::AceButton::getId
uint8_t getId() const
Get the custom identifier of the button.
Definition: AceButton.h:274
ace_button::AceButton::AceButton
AceButton(ButtonConfig *buttonConfig, uint8_t pin=0, uint8_t defaultReleasedState=HIGH, uint8_t id=0)
Constructor that accepts a ButtonConfig as a dependency.
Definition: AceButton.h:192
ace_button::AceButton::eventName
static __FlashStringHelper * eventName(uint8_t event)
Return the human-readable name of the event.
Definition: AceButton.cpp:79
ace_button::AceButton::AceButton
AceButton(uint8_t pin=0, uint8_t defaultReleasedState=HIGH, uint8_t id=0)
Constructor defines parameters of the button that changes from button to button.
Definition: AceButton.h:160
ace_button::AceButton::checkState
void checkState(uint8_t buttonState)
Version of check() used by EncodedButtonConfig.
Definition: AceButton.cpp:121
ace_button::AceButton::getDefaultReleasedState
uint8_t getDefaultReleasedState() const
Get the initial released state of the button, HIGH or LOW.
Definition: AceButton.cpp:110
ace_button::AceButton::kEventLongPressed
static const uint8_t kEventLongPressed
Button was held down for longer than ButtonConfig::getLongPressDelay()).
Definition: AceButton.h:80
ace_button::AceButton::setEventHandler
void setEventHandler(ButtonConfig::EventHandler eventHandler)
Convenience method to set the event handler.
Definition: AceButton.h:266
ace_button::AceButton::getButtonConfig
ButtonConfig * getButtonConfig() const
Get the ButtonConfig associated with this Button.
Definition: AceButton.h:223
ace_button::AceButton::isPressedRaw
bool isPressedRaw() const
Read the button state directly using ButtonConfig and return true if the button is in the Pressed sta...
Definition: AceButton.h:337
ace_button::AceButton::kEventRepeatPressed
static const uint8_t kEventRepeatPressed
Button was held down and auto generated multiple presses.
Definition: AceButton.h:88
ace_button::AceButton::kEventLongReleased
static const uint8_t kEventLongReleased
Button was released after a long press.
Definition: AceButton.h:99
ace_button::AceButton::getPin
uint8_t getPin() const
Get the button's pin number.
Definition: AceButton.h:271
ace_button::AceButton::getLastButtonState
uint8_t getLastButtonState() const
Return the button state that was last valid.
Definition: AceButton.h:292
ace_button::AceButton::isReleased
bool isReleased(uint8_t buttonState) const
Returns true if the given buttonState represents a 'Released' state for the button.
Definition: AceButton.h:326
ace_button::AceButton::kEventHeartBeat
static const uint8_t kEventHeartBeat
An event that fires every time interval defined by getHeartBeatInterval().
Definition: AceButton.h:111
ace_button::AceButton::kEventReleased
static const uint8_t kEventReleased
Button was released.
Definition: AceButton.h:62
ace_button::AceButton::kEventPressed
static const uint8_t kEventPressed
Button was pressed.
Definition: AceButton.h:59
ace_button::AceButton::check
void check()
Check state of button and trigger event processing.
Definition: AceButton.cpp:116
ace_button::AceButton::kButtonStateUnknown
static const uint8_t kButtonStateUnknown
Button state is unknown.
Definition: AceButton.h:119
ace_button::ButtonConfig
Class that defines the timing parameters and event handler of an AceButton or a group of AceButton in...
Definition: ButtonConfig.h:66
ace_button::ButtonConfig::readButton
virtual int readButton(uint8_t pin)
Return the HIGH or LOW state of the button.
Definition: ButtonConfig.h:317
ace_button::ButtonConfig::EventHandler
void(* EventHandler)(AceButton *button, uint8_t eventType, uint8_t buttonState)
The event handler signature.
Definition: ButtonConfig.h:182
ace_button::ButtonConfig::setEventHandler
void setEventHandler(EventHandler eventHandler)
Install the EventHandler function pointer.
Definition: ButtonConfig.h:390