AceButton  1.8
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 namespace ace_button {
32 
51 class AceButton {
52  public:
53  // The supported event types.
54 
56  static const uint8_t kEventPressed = 0;
57 
59  static const uint8_t kEventReleased = 1;
60 
65  static const uint8_t kEventClicked = 2;
66 
71  static const uint8_t kEventDoubleClicked = 3;
72 
77  static const uint8_t kEventLongPressed = 4;
78 
85  static const uint8_t kEventRepeatPressed = 5;
86 
96  static const uint8_t kEventLongReleased = 6;
97 
104  static const uint8_t kButtonStateUnknown = 127;
105 
138  explicit AceButton(uint8_t pin = 0, uint8_t defaultReleasedState = HIGH,
139  uint8_t id = 0);
140 
150  explicit AceButton(ButtonConfig* buttonConfig, uint8_t pin = 0,
151  uint8_t defaultReleasedState = HIGH, uint8_t id = 0);
152 
158  void init(uint8_t pin = 0, uint8_t defaultReleasedState = HIGH,
159  uint8_t id = 0);
160 
167  void init(ButtonConfig* buttonConfig, uint8_t pin = 0,
168  uint8_t defaultReleasedState = HIGH, uint8_t id = 0);
169 
172  return mButtonConfig;
173  }
174 
180  void setButtonConfig(ButtonConfig* buttonConfig) {
181  mButtonConfig = buttonConfig;
182  }
183 
215  mButtonConfig->setEventHandler(eventHandler);
216  }
217 
219  uint8_t getPin() const { return mPin; }
220 
222  uint8_t getId() const { return mId; }
223 
225  uint8_t getDefaultReleasedState() const;
226 
240  uint8_t getLastButtonState() const {
241  return mLastButtonState;
242  }
243 
251  void check();
252 
257  void checkState(uint8_t buttonState);
258 
274  bool isReleased(uint8_t buttonState) const {
275  return buttonState == getDefaultReleasedState();
276  }
277 
285  bool isPressedRaw() const {
286  return !isReleased(mButtonConfig->readButton(mPin));
287  }
288 
289  // Some of these private methods may be useful to the calling client but I
290  // don't want to release them to the public because I want to keep the API as
291  // small as possible for easier long term maintenance. (Once a method is
292  // released to the public, it must be supported forever to ensure backwards
293  // compatibility with older client code.)
294 
295  private:
296  // Disable copy-constructor and assignment operator
297  AceButton(const AceButton&) = delete;
298  AceButton& operator=(const AceButton&) = delete;
299 
301  void setPin(uint8_t pin) { mPin = pin; }
302 
310  void setDefaultReleasedState(uint8_t state);
311 
313  void setId(uint8_t id) { mId = id; }
314 
315  // Various bit masks to store a boolean flag in the 'mFlags' field.
316  // We use bit masks to save static RAM. If we had used a 'bool' type, each
317  // of these would consume one byte.
318  static const uint8_t kFlagDefaultReleasedState = 0x01;
319  static const uint8_t kFlagDebouncing = 0x02;
320  static const uint8_t kFlagPressed = 0x04;
321  static const uint8_t kFlagClicked = 0x08;
322  static const uint8_t kFlagDoubleClicked = 0x10;
323  static const uint8_t kFlagLongPressed = 0x20;
324  static const uint8_t kFlagRepeatPressed = 0x40;
325  static const uint8_t kFlagClickPostponed = 0x80;
326 
327  // Methods for accessing the button's internal states.
328  // I don't expect these to be useful to the outside world.
329 
330  // If this is set, then mLastDebounceTime is valid.
331  bool isDebouncing() const {
332  return mFlags & kFlagDebouncing;
333  }
334 
335  void setDebouncing() {
336  mFlags |= kFlagDebouncing;
337  }
338 
339  void clearDebouncing() {
340  mFlags &= ~kFlagDebouncing;
341  }
342 
343  // If this is set, then mLastPressTime is valid.
344  bool isPressed() const {
345  return mFlags & kFlagPressed;
346  }
347 
348  void setPressed() {
349  mFlags |= kFlagPressed;
350  }
351 
352  void clearPressed() {
353  mFlags &= ~kFlagPressed;
354  }
355 
356  // If this is set, then mLastClickTime is valid.
357  bool isClicked() const {
358  return mFlags & kFlagClicked;
359  }
360 
361  void setClicked() {
362  mFlags |= kFlagClicked;
363  }
364 
365  void clearClicked() {
366  mFlags &= ~kFlagClicked;
367  }
368 
369  // A double click was detected. No need to store the last double-clicked
370  // time because we don't support a triple-click event (yet).
371  bool isDoubleClicked() const {
372  return mFlags & kFlagDoubleClicked;
373  }
374 
375  void setDoubleClicked() {
376  mFlags |= kFlagDoubleClicked;
377  }
378 
379  void clearDoubleClicked() {
380  mFlags &= ~kFlagDoubleClicked;
381  }
382 
383  // If this is set, then mLastPressTime can be treated as the start
384  // of a long press.
385  bool isLongPressed() const {
386  return mFlags & kFlagLongPressed;
387  }
388 
389  void setLongPressed() {
390  mFlags |= kFlagLongPressed;
391  }
392 
393  void clearLongPressed() {
394  mFlags &= ~kFlagLongPressed;
395  }
396 
397  // If this is set, then mLastRepeatPressTime is valid.
398  bool isRepeatPressed() const {
399  return mFlags & kFlagRepeatPressed;
400  }
401 
402  void setRepeatPressed() {
403  mFlags |= kFlagRepeatPressed;
404  }
405 
406  void clearRepeatPressed() {
407  mFlags &= ~kFlagRepeatPressed;
408  }
409 
410  bool isClickPostponed() const {
411  return mFlags & kFlagClickPostponed;
412  }
413 
414  void setClickPostponed() {
415  mFlags |= kFlagClickPostponed;
416  }
417 
418  void clearClickPostponed() {
419  mFlags &= ~kFlagClickPostponed;
420  }
421 
427  bool checkDebounced(uint16_t now, uint8_t buttonState);
428 
435  bool checkInitialized(uint16_t buttonState);
436 
438  void checkEvent(uint16_t now, uint8_t buttonState);
439 
441  void checkLongPress(uint16_t now, uint8_t buttonState);
442 
444  void checkRepeatPress(uint16_t now, uint8_t buttonState);
445 
447  void checkChanged(uint16_t now, uint8_t buttonState);
448 
453  void checkReleased(uint16_t now, uint8_t buttonState);
454 
456  void checkPressed(uint16_t now, uint8_t buttonState);
457 
459  void checkClicked(uint16_t now);
460 
465  void checkDoubleClicked(uint16_t now);
466 
475  void checkOrphanedClick(uint16_t now);
476 
481  void checkPostponedClick(uint16_t now);
482 
535  void handleEvent(uint8_t eventType);
536 
538  ButtonConfig* mButtonConfig;
539 
541  uint8_t mPin;
542 
544  uint8_t mId;
545 
547  uint8_t mFlags;
548 
553  uint8_t mLastButtonState;
554 
555  // Internal states of the button debouncing and event handling.
556  // NOTE: We don't keep track of the lastDoubleClickTime, because we
557  // don't support a TripleClicked event. That may change in the future.
558  uint16_t mLastDebounceTime; // ms
559  uint16_t mLastClickTime; // ms
560  uint16_t mLastPressTime; // ms
561  uint16_t mLastRepeatPressTime; // ms
562 };
563 
564 }
565 #endif
ace_button::AceButton::check
void check()
Check state of button and trigger event processing.
Definition: AceButton.cpp:94
ace_button::AceButton::kEventRepeatPressed
static const uint8_t kEventRepeatPressed
Button was held down and auto generated multiple presses.
Definition: AceButton.h:85
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:285
ace_button::AceButton::kEventLongReleased
static const uint8_t kEventLongReleased
Button was released after a long press.
Definition: AceButton.h:96
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.cpp:54
ace_button::AceButton::getId
uint8_t getId() const
Get the custom identifier of the button.
Definition: AceButton.h:222
ace_button::AceButton::kEventReleased
static const uint8_t kEventReleased
Button was released.
Definition: AceButton.h:59
ace_button::AceButton::getPin
uint8_t getPin() const
Get the button's pin number.
Definition: AceButton.h:219
ace_button::AceButton::getDefaultReleasedState
uint8_t getDefaultReleasedState() const
Get the initial released state of the button, HIGH or LOW.
Definition: AceButton.cpp:88
ace_button::AceButton::getButtonConfig
ButtonConfig * getButtonConfig() const
Get the ButtonConfig associated with this Button.
Definition: AceButton.h:171
ace_button::ButtonConfig::setEventHandler
void setEventHandler(EventHandler eventHandler)
Install the EventHandler function pointer.
Definition: ButtonConfig.h:376
ace_button::AceButton
An Adjustable Compact Event-driven (ACE) Button library that debounces and dispatches button events t...
Definition: AceButton.h:51
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::EventHandler
void(* EventHandler)(AceButton *button, uint8_t eventType, uint8_t buttonState)
The event handler signature.
Definition: ButtonConfig.h:176
ace_button::AceButton::kEventLongPressed
static const uint8_t kEventLongPressed
Button was held down for longer than ButtonConfig::getLongPressDelay()).
Definition: AceButton.h:77
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:274
ace_button::AceButton::kEventClicked
static const uint8_t kEventClicked
Button was clicked (Pressed and Released within ButtonConfig::getClickDelay()).
Definition: AceButton.h:65
ace_button::AceButton::setButtonConfig
void setButtonConfig(ButtonConfig *buttonConfig)
Set the ButtonConfig associated with this Button.
Definition: AceButton.h:180
ace_button::AceButton::kEventPressed
static const uint8_t kEventPressed
Button was pressed.
Definition: AceButton.h:56
ace_button::AceButton::kButtonStateUnknown
static const uint8_t kButtonStateUnknown
Button state is unknown.
Definition: AceButton.h:104
ace_button::AceButton::getLastButtonState
uint8_t getLastButtonState() const
Return the button state that was last valid.
Definition: AceButton.h:240
ace_button::AceButton::checkState
void checkState(uint8_t buttonState)
Version of check() used by EncodedButtonConfig.
Definition: AceButton.cpp:99
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:64
ace_button::AceButton::kEventDoubleClicked
static const uint8_t kEventDoubleClicked
Button was double-clicked.
Definition: AceButton.h:71
ace_button::AceButton::setEventHandler
void setEventHandler(ButtonConfig::EventHandler eventHandler)
Convenience method to set the event handler.
Definition: AceButton.h:214
ace_button::ButtonConfig::readButton
virtual int readButton(uint8_t pin)
Return the HIGH or LOW state of the button.
Definition: ButtonConfig.h:303