AceButton  1.4
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 
50 class AceButton {
51  public:
52  // The supported event types.
53 
55  static const uint8_t kEventPressed = 0;
56 
58  static const uint8_t kEventReleased = 1;
59 
64  static const uint8_t kEventClicked = 2;
65 
70  static const uint8_t kEventDoubleClicked = 3;
71 
76  static const uint8_t kEventLongPressed = 4;
77 
84  static const uint8_t kEventRepeatPressed = 5;
85 
92  static const uint8_t kButtonStateUnknown = 127;
93 
126  explicit AceButton(uint8_t pin = 0, uint8_t defaultReleasedState = HIGH,
127  uint8_t id = 0);
128 
138  explicit AceButton(ButtonConfig* buttonConfig, uint8_t pin = 0,
139  uint8_t defaultReleasedState = HIGH, uint8_t id = 0);
140 
146  void init(uint8_t pin = 0, uint8_t defaultReleasedState = HIGH,
147  uint8_t id = 0);
148 
155  void init(ButtonConfig* buttonConfig, uint8_t pin = 0,
156  uint8_t defaultReleasedState = HIGH, uint8_t id = 0);
157 
160  return mButtonConfig;
161  }
162 
168  void setButtonConfig(ButtonConfig* buttonConfig) {
169  mButtonConfig = buttonConfig;
170  }
171 
182  mButtonConfig->setEventHandler(eventHandler);
183  }
184 
186  uint8_t getPin() { return mPin; }
187 
189  uint8_t getId() { return mId; }
190 
192  uint8_t getDefaultReleasedState();
193 
207  uint8_t getLastButtonState() {
208  return mLastButtonState;
209  }
210 
218  void check();
219 
235  bool isReleased(uint8_t buttonState) {
236  return buttonState == getDefaultReleasedState();
237  }
238 
246  bool isPressedRaw() {
247  return !isReleased(mButtonConfig->readButton(mPin));
248  }
249 
250  // Some of these private methods may be useful to the calling client but I
251  // don't want to release them to the public because I want to keep the API as
252  // small as possible for easier long term maintenance. (Once a method is
253  // released to the public, it must be supported forever to ensure backwards
254  // compatibility with older client code.)
255 
256  private:
257  // Disable copy-constructor and assignment operator
258  AceButton(const AceButton&) = delete;
259  AceButton& operator=(const AceButton&) = delete;
260 
262  void setPin(uint8_t pin) { mPin = pin; }
263 
271  void setDefaultReleasedState(uint8_t state);
272 
274  void setId(uint8_t id) { mId = id; }
275 
276  // Various bit masks to store a boolean flag in the 'mFlags' field.
277  // We use bit masks to save static RAM. If we had used a 'bool' type, each
278  // of these would consume one byte.
279  static const uint8_t kFlagDefaultReleasedState = 0x01;
280  static const uint8_t kFlagDebouncing = 0x02;
281  static const uint8_t kFlagPressed = 0x04;
282  static const uint8_t kFlagClicked = 0x08;
283  static const uint8_t kFlagDoubleClicked = 0x10;
284  static const uint8_t kFlagLongPressed = 0x20;
285  static const uint8_t kFlagRepeatPressed = 0x40;
286  static const uint8_t kFlagClickPostponed = 0x80;
287 
288  // Methods for accessing the button's internal states.
289  // I don't expect these to be useful to the outside world.
290 
291  // If this is set, then mLastDebounceTime is valid.
292  bool isDebouncing() {
293  return mFlags & kFlagDebouncing;
294  }
295 
296  void setDebouncing() {
297  mFlags |= kFlagDebouncing;
298  }
299 
300  void clearDebouncing() {
301  mFlags &= ~kFlagDebouncing;
302  }
303 
304  // If this is set, then mLastPressTime is valid.
305  bool isPressed() {
306  return mFlags & kFlagPressed;
307  }
308 
309  void setPressed() {
310  mFlags |= kFlagPressed;
311  }
312 
313  void clearPressed() {
314  mFlags &= ~kFlagPressed;
315  }
316 
317  // If this is set, then mLastClickTime is valid.
318  bool isClicked() {
319  return mFlags & kFlagClicked;
320  }
321 
322  void setClicked() {
323  mFlags |= kFlagClicked;
324  }
325 
326  void clearClicked() {
327  mFlags &= ~kFlagClicked;
328  }
329 
330  // A double click was detected. No need to store the last double-clicked
331  // time because we don't support a triple-click event (yet).
332  bool isDoubleClicked() {
333  return mFlags & kFlagDoubleClicked;
334  }
335 
336  void setDoubleClicked() {
337  mFlags |= kFlagDoubleClicked;
338  }
339 
340  void clearDoubleClicked() {
341  mFlags &= ~kFlagDoubleClicked;
342  }
343 
344  // If this is set, then mLastPressTime can be treated as the start
345  // of a long press.
346  bool isLongPressed() {
347  return mFlags & kFlagLongPressed;
348  }
349 
350  void setLongPressed() {
351  mFlags |= kFlagLongPressed;
352  }
353 
354  void clearLongPressed() {
355  mFlags &= ~kFlagLongPressed;
356  }
357 
358  // If this is set, then mLastRepeatPressTime is valid.
359  bool isRepeatPressed() {
360  return mFlags & kFlagRepeatPressed;
361  }
362 
363  void setRepeatPressed() {
364  mFlags |= kFlagRepeatPressed;
365  }
366 
367  void clearRepeatPressed() {
368  mFlags &= ~kFlagRepeatPressed;
369  }
370 
371  bool isClickPostponed() {
372  return mFlags & kFlagClickPostponed;
373  }
374 
375  void setClickPostponed() {
376  mFlags |= kFlagClickPostponed;
377  }
378 
379  void clearClickPostponed() {
380  mFlags &= ~kFlagClickPostponed;
381  }
382 
388  bool checkDebounced(uint16_t now, uint8_t buttonState);
389 
396  bool checkInitialized(uint16_t buttonState);
397 
399  void checkEvent(uint16_t now, uint8_t buttonState);
400 
402  void checkLongPress(uint16_t now, uint8_t buttonState);
403 
405  void checkRepeatPress(uint16_t now, uint8_t buttonState);
406 
408  void checkChanged(uint16_t now, uint8_t buttonState);
409 
414  void checkReleased(uint16_t now, uint8_t buttonState);
415 
417  void checkPressed(uint16_t now, uint8_t buttonState);
418 
420  void checkClicked(uint16_t now);
421 
426  void checkDoubleClicked(uint16_t now);
427 
436  void checkOrphanedClick(uint16_t now);
437 
442  void checkPostponedClick(uint16_t now);
443 
490  void handleEvent(uint8_t eventType);
491 
493  ButtonConfig* mButtonConfig;
494 
496  uint8_t mPin;
497 
499  uint8_t mId;
500 
502  uint8_t mFlags;
503 
508  uint8_t mLastButtonState;
509 
510  // Internal states of the button debouncing and event handling.
511  // NOTE: We don't keep track of the lastDoubleClickTime, because we
512  // don't support a TripleClicked event. That may change in the future.
513  uint16_t mLastDebounceTime; // ms
514  uint16_t mLastClickTime; // ms
515  uint16_t mLastPressTime; // ms
516  uint16_t mLastRepeatPressTime; // ms
517 };
518 
519 }
520 #endif
uint8_t getDefaultReleasedState()
Get the initial released state of the button, HIGH or LOW.
Definition: AceButton.cpp:89
bool isReleased(uint8_t buttonState)
Returns true if the given buttonState represents a &#39;Released&#39; state for the button.
Definition: AceButton.h:235
static const uint8_t kEventRepeatPressed
Button was held down and auto generated multiple presses.
Definition: AceButton.h:84
static const uint8_t kButtonStateUnknown
Button state is unknown.
Definition: AceButton.h:92
void setEventHandler(EventHandler eventHandler)
Install the event handler.
Definition: ButtonConfig.h:292
uint8_t getPin()
Get the button&#39;s pin number.
Definition: AceButton.h:186
ButtonConfig * getButtonConfig()
Get the ButtonConfig associated with this Button.
Definition: AceButton.h:159
void setButtonConfig(ButtonConfig *buttonConfig)
Set the ButtonConfig associated with this Button.
Definition: AceButton.h:168
virtual int readButton(uint8_t pin)
Return the HIGH or LOW state of the button.
Definition: ButtonConfig.h:259
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:65
uint8_t getLastButtonState()
Return the button state that was last valid.
Definition: AceButton.h:207
Class that defines the timing parameters and event handler of an AceButton or a group of AceButton in...
Definition: ButtonConfig.h:56
static const uint8_t kEventDoubleClicked
Button was double-clicked.
Definition: AceButton.h:70
bool isPressedRaw()
Read the button state directly using ButtonConfig and return true if the button is in the Pressed sta...
Definition: AceButton.h:246
static const uint8_t kEventLongPressed
Button was held down for longer than ButtonConfig::getLongPressDelay()).
Definition: AceButton.h:76
uint8_t getId()
Get the custom identifier of the button.
Definition: AceButton.h:189
void setEventHandler(ButtonConfig::EventHandler eventHandler)
Convenience method to set the event handler.
Definition: AceButton.h:181
void(* EventHandler)(AceButton *button, uint8_t eventType, uint8_t buttonState)
The event handler signature.
Definition: ButtonConfig.h:160
void check()
Check state of button and trigger event processing.
Definition: AceButton.cpp:95
An Adjustable Compact Event-driven (ACE) Button library that debounces and dispatches button events t...
Definition: AceButton.h:50
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:55
static const uint8_t kEventReleased
Button was released.
Definition: AceButton.h:58
static const uint8_t kEventPressed
Button was pressed.
Definition: AceButton.h:55
static const uint8_t kEventClicked
Button was clicked (Pressed and Released within ButtonConfig::getClickDelay()).
Definition: AceButton.h:64