AceButton  1.4.2
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 
224  void checkState(uint8_t buttonState);
225 
241  bool isReleased(uint8_t buttonState) {
242  return buttonState == getDefaultReleasedState();
243  }
244 
252  bool isPressedRaw() {
253  return !isReleased(mButtonConfig->readButton(mPin));
254  }
255 
256  // Some of these private methods may be useful to the calling client but I
257  // don't want to release them to the public because I want to keep the API as
258  // small as possible for easier long term maintenance. (Once a method is
259  // released to the public, it must be supported forever to ensure backwards
260  // compatibility with older client code.)
261 
262  private:
263  // Disable copy-constructor and assignment operator
264  AceButton(const AceButton&) = delete;
265  AceButton& operator=(const AceButton&) = delete;
266 
268  void setPin(uint8_t pin) { mPin = pin; }
269 
277  void setDefaultReleasedState(uint8_t state);
278 
280  void setId(uint8_t id) { mId = id; }
281 
282  // Various bit masks to store a boolean flag in the 'mFlags' field.
283  // We use bit masks to save static RAM. If we had used a 'bool' type, each
284  // of these would consume one byte.
285  static const uint8_t kFlagDefaultReleasedState = 0x01;
286  static const uint8_t kFlagDebouncing = 0x02;
287  static const uint8_t kFlagPressed = 0x04;
288  static const uint8_t kFlagClicked = 0x08;
289  static const uint8_t kFlagDoubleClicked = 0x10;
290  static const uint8_t kFlagLongPressed = 0x20;
291  static const uint8_t kFlagRepeatPressed = 0x40;
292  static const uint8_t kFlagClickPostponed = 0x80;
293 
294  // Methods for accessing the button's internal states.
295  // I don't expect these to be useful to the outside world.
296 
297  // If this is set, then mLastDebounceTime is valid.
298  bool isDebouncing() {
299  return mFlags & kFlagDebouncing;
300  }
301 
302  void setDebouncing() {
303  mFlags |= kFlagDebouncing;
304  }
305 
306  void clearDebouncing() {
307  mFlags &= ~kFlagDebouncing;
308  }
309 
310  // If this is set, then mLastPressTime is valid.
311  bool isPressed() {
312  return mFlags & kFlagPressed;
313  }
314 
315  void setPressed() {
316  mFlags |= kFlagPressed;
317  }
318 
319  void clearPressed() {
320  mFlags &= ~kFlagPressed;
321  }
322 
323  // If this is set, then mLastClickTime is valid.
324  bool isClicked() {
325  return mFlags & kFlagClicked;
326  }
327 
328  void setClicked() {
329  mFlags |= kFlagClicked;
330  }
331 
332  void clearClicked() {
333  mFlags &= ~kFlagClicked;
334  }
335 
336  // A double click was detected. No need to store the last double-clicked
337  // time because we don't support a triple-click event (yet).
338  bool isDoubleClicked() {
339  return mFlags & kFlagDoubleClicked;
340  }
341 
342  void setDoubleClicked() {
343  mFlags |= kFlagDoubleClicked;
344  }
345 
346  void clearDoubleClicked() {
347  mFlags &= ~kFlagDoubleClicked;
348  }
349 
350  // If this is set, then mLastPressTime can be treated as the start
351  // of a long press.
352  bool isLongPressed() {
353  return mFlags & kFlagLongPressed;
354  }
355 
356  void setLongPressed() {
357  mFlags |= kFlagLongPressed;
358  }
359 
360  void clearLongPressed() {
361  mFlags &= ~kFlagLongPressed;
362  }
363 
364  // If this is set, then mLastRepeatPressTime is valid.
365  bool isRepeatPressed() {
366  return mFlags & kFlagRepeatPressed;
367  }
368 
369  void setRepeatPressed() {
370  mFlags |= kFlagRepeatPressed;
371  }
372 
373  void clearRepeatPressed() {
374  mFlags &= ~kFlagRepeatPressed;
375  }
376 
377  bool isClickPostponed() {
378  return mFlags & kFlagClickPostponed;
379  }
380 
381  void setClickPostponed() {
382  mFlags |= kFlagClickPostponed;
383  }
384 
385  void clearClickPostponed() {
386  mFlags &= ~kFlagClickPostponed;
387  }
388 
394  bool checkDebounced(uint16_t now, uint8_t buttonState);
395 
402  bool checkInitialized(uint16_t buttonState);
403 
405  void checkEvent(uint16_t now, uint8_t buttonState);
406 
408  void checkLongPress(uint16_t now, uint8_t buttonState);
409 
411  void checkRepeatPress(uint16_t now, uint8_t buttonState);
412 
414  void checkChanged(uint16_t now, uint8_t buttonState);
415 
420  void checkReleased(uint16_t now, uint8_t buttonState);
421 
423  void checkPressed(uint16_t now, uint8_t buttonState);
424 
426  void checkClicked(uint16_t now);
427 
432  void checkDoubleClicked(uint16_t now);
433 
442  void checkOrphanedClick(uint16_t now);
443 
448  void checkPostponedClick(uint16_t now);
449 
496  void handleEvent(uint8_t eventType);
497 
499  ButtonConfig* mButtonConfig;
500 
502  uint8_t mPin;
503 
505  uint8_t mId;
506 
508  uint8_t mFlags;
509 
514  uint8_t mLastButtonState;
515 
516  // Internal states of the button debouncing and event handling.
517  // NOTE: We don't keep track of the lastDoubleClickTime, because we
518  // don't support a TripleClicked event. That may change in the future.
519  uint16_t mLastDebounceTime; // ms
520  uint16_t mLastClickTime; // ms
521  uint16_t mLastPressTime; // ms
522  uint16_t mLastRepeatPressTime; // ms
523 };
524 
525 }
526 #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:241
static const uint8_t kEventRepeatPressed
Button was held down and auto generated multiple presses.
Definition: AceButton.h:84
void checkState(uint8_t buttonState)
Version of check() used by EncodedButtonConfig.
Definition: AceButton.cpp:122
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:252
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