AceButton  1.3.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 
134  explicit AceButton(ButtonConfig* buttonConfig);
135 
141  void init(uint8_t pin = 0, uint8_t defaultReleasedState = HIGH,
142  uint8_t id = 0);
143 
146  return mButtonConfig;
147  }
148 
154  void setButtonConfig(ButtonConfig* buttonConfig) {
155  mButtonConfig = buttonConfig;
156  }
157 
168  mButtonConfig->setEventHandler(eventHandler);
169  }
170 
172  uint8_t getPin() { return mPin; }
173 
175  uint8_t getId() { return mId; }
176 
178  uint8_t getDefaultReleasedState();
179 
193  uint8_t getLastButtonState() {
194  return mLastButtonState;
195  }
196 
204  void check();
205 
221  bool isReleased(uint8_t buttonState) {
222  return buttonState == getDefaultReleasedState();
223  }
224 
232  bool isPressedRaw() {
233  return !isReleased(mButtonConfig->readButton(mPin));
234  }
235 
236  // Some of these private methods may be useful to the calling client but I
237  // don't want to release them to the public because I want to keep the API as
238  // small as possible for easier long term maintenance. (Once a method is
239  // released to the public, it must be supported forever to ensure backwards
240  // compatibility with older client code.)
241 
242  private:
243  // Disable copy-constructor and assignment operator
244  AceButton(const AceButton&) = delete;
245  AceButton& operator=(const AceButton&) = delete;
246 
248  void setPin(uint8_t pin) { mPin = pin; }
249 
257  void setDefaultReleasedState(uint8_t state);
258 
260  void setId(uint8_t id) { mId = id; }
261 
262  // Various bit masks to store a boolean flag in the 'mFlags' field.
263  // We use bit masks to save static RAM. If we had used a 'bool' type, each
264  // of these would consume one byte.
265  static const uint8_t kFlagDefaultReleasedState = 0x01;
266  static const uint8_t kFlagDebouncing = 0x02;
267  static const uint8_t kFlagPressed = 0x04;
268  static const uint8_t kFlagClicked = 0x08;
269  static const uint8_t kFlagDoubleClicked = 0x10;
270  static const uint8_t kFlagLongPressed = 0x20;
271  static const uint8_t kFlagRepeatPressed = 0x40;
272  static const uint8_t kFlagClickPostponed = 0x80;
273 
274  // Methods for accessing the button's internal states.
275  // I don't expect these to be useful to the outside world.
276 
277  // If this is set, then mLastDebounceTime is valid.
278  bool isDebouncing() {
279  return mFlags & kFlagDebouncing;
280  }
281 
282  void setDebouncing() {
283  mFlags |= kFlagDebouncing;
284  }
285 
286  void clearDebouncing() {
287  mFlags &= ~kFlagDebouncing;
288  }
289 
290  // If this is set, then mLastPressTime is valid.
291  bool isPressed() {
292  return mFlags & kFlagPressed;
293  }
294 
295  void setPressed() {
296  mFlags |= kFlagPressed;
297  }
298 
299  void clearPressed() {
300  mFlags &= ~kFlagPressed;
301  }
302 
303  // If this is set, then mLastClickTime is valid.
304  bool isClicked() {
305  return mFlags & kFlagClicked;
306  }
307 
308  void setClicked() {
309  mFlags |= kFlagClicked;
310  }
311 
312  void clearClicked() {
313  mFlags &= ~kFlagClicked;
314  }
315 
316  // A double click was detected. No need to store the last double-clicked
317  // time because we don't support a triple-click event (yet).
318  bool isDoubleClicked() {
319  return mFlags & kFlagDoubleClicked;
320  }
321 
322  void setDoubleClicked() {
323  mFlags |= kFlagDoubleClicked;
324  }
325 
326  void clearDoubleClicked() {
327  mFlags &= ~kFlagDoubleClicked;
328  }
329 
330  // If this is set, then mLastPressTime can be treated as the start
331  // of a long press.
332  bool isLongPressed() {
333  return mFlags & kFlagLongPressed;
334  }
335 
336  void setLongPressed() {
337  mFlags |= kFlagLongPressed;
338  }
339 
340  void clearLongPressed() {
341  mFlags &= ~kFlagLongPressed;
342  }
343 
344  // If this is set, then mLastRepeatPressTime is valid.
345  bool isRepeatPressed() {
346  return mFlags & kFlagRepeatPressed;
347  }
348 
349  void setRepeatPressed() {
350  mFlags |= kFlagRepeatPressed;
351  }
352 
353  void clearRepeatPressed() {
354  mFlags &= ~kFlagRepeatPressed;
355  }
356 
357  bool isClickPostponed() {
358  return mFlags & kFlagClickPostponed;
359  }
360 
361  void setClickPostponed() {
362  mFlags |= kFlagClickPostponed;
363  }
364 
365  void clearClickPostponed() {
366  mFlags &= ~kFlagClickPostponed;
367  }
368 
374  bool checkDebounced(uint16_t now, uint8_t buttonState);
375 
382  bool checkInitialized(uint16_t buttonState);
383 
385  void checkEvent(uint16_t now, uint8_t buttonState);
386 
388  void checkLongPress(uint16_t now, uint8_t buttonState);
389 
391  void checkRepeatPress(uint16_t now, uint8_t buttonState);
392 
394  void checkChanged(uint16_t now, uint8_t buttonState);
395 
400  void checkReleased(uint16_t now, uint8_t buttonState);
401 
403  void checkPressed(uint16_t now, uint8_t buttonState);
404 
406  void checkClicked(uint16_t now);
407 
412  void checkDoubleClicked(uint16_t now);
413 
422  void checkOrphanedClick(uint16_t now);
423 
428  void checkPostponedClick(uint16_t now);
429 
476  void handleEvent(uint8_t eventType);
477 
478  uint8_t mPin; // button pin number
479  uint8_t mId; // identifier, e.g. an index into an array
480 
481  // Internal states of the button debouncing and event handling.
482  // NOTE: We don't keep track of the lastDoubleClickTime, because we
483  // don't support a TripleClicked event. That may change in the future.
484  uint16_t mLastDebounceTime; // ms
485  uint16_t mLastClickTime; // ms
486  uint16_t mLastPressTime; // ms
487  uint16_t mLastRepeatPressTime; // ms
488 
490  uint8_t mFlags;
491 
496  uint8_t mLastButtonState;
497 
499  ButtonConfig* mButtonConfig;
500 };
501 
502 }
503 #endif
uint8_t getDefaultReleasedState()
Get the initial released state of the button, HIGH or LOW.
Definition: AceButton.cpp:83
bool isReleased(uint8_t buttonState)
Returns true if the given buttonState represents a &#39;Released&#39; state for the button.
Definition: AceButton.h:221
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:172
ButtonConfig * getButtonConfig()
Get the ButtonConfig associated with this Button.
Definition: AceButton.h:145
void setButtonConfig(ButtonConfig *buttonConfig)
Set the ButtonConfig associated with this Button.
Definition: AceButton.h:154
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:193
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:232
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:175
void setEventHandler(ButtonConfig::EventHandler eventHandler)
Convenience method to set the event handler.
Definition: AceButton.h:167
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:89
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