AceButton  1.1.0
An adjustable, compact, event-driven (ACE) 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 
90  static const uint8_t kButtonStateUnknown = 2;
91 
124  explicit AceButton(uint8_t pin = 0, uint8_t defaultReleasedState = HIGH,
125  uint8_t id = 0);
126 
132  void init(uint8_t pin = 0, uint8_t defaultReleasedState = HIGH,
133  uint8_t id = 0);
134 
136  ButtonConfig* getButtonConfig() ACE_BUTTON_INLINE {
137  return mButtonConfig;
138  }
139 
141  void setButtonConfig(ButtonConfig* buttonConfig) ACE_BUTTON_INLINE {
142  mButtonConfig = buttonConfig;
143  }
144 
155  ACE_BUTTON_INLINE {
156  mButtonConfig->setEventHandler(eventHandler);
157  }
158 
160  uint8_t getPin() ACE_BUTTON_INLINE { return mPin; }
161 
163  uint8_t getId() ACE_BUTTON_INLINE { return mId; }
164 
166  uint8_t getDefaultReleasedState();
167 
181  uint8_t getLastButtonState() ACE_BUTTON_INLINE {
182  return mLastButtonState;
183  }
184 
192  void check();
193 
209  bool isReleased(uint8_t buttonState) ACE_BUTTON_INLINE {
210  return buttonState == getDefaultReleasedState();
211  }
212 
213  // Some of these private methods may be useful to the calling client but I
214  // don't want to release them to the public because I want to keep the API as
215  // small as possible for easier long term maintenance. (Once a method is
216  // released to the public, it must be supported forever to ensure backwards
217  // compatibility with older client code.)
218 
219  private:
220  // Disable copy-constructor and assignment operator
221  AceButton(const AceButton&) = delete;
222  AceButton& operator=(const AceButton&) = delete;
223 
225  void setPin(uint8_t pin) ACE_BUTTON_INLINE { mPin = pin; }
226 
234  void setDefaultReleasedState(uint8_t state);
235 
237  void setId(uint8_t id) ACE_BUTTON_INLINE { mId = id; }
238 
239  // Various bit masks to store a boolean flag in the 'mFlags' field.
240  // We use bit masks to save static RAM. If we had used a 'bool' type, each
241  // of these would consume one byte.
242  static const uint8_t kFlagDefaultReleasedState = 0x01;
243  static const uint8_t kFlagDebouncing = 0x02;
244  static const uint8_t kFlagPressed = 0x04;
245  static const uint8_t kFlagClicked = 0x08;
246  static const uint8_t kFlagDoubleClicked = 0x10;
247  static const uint8_t kFlagLongPressed = 0x20;
248  static const uint8_t kFlagRepeatPressed = 0x40;
249  static const uint8_t kFlagClickPostponed = 0x80;
250 
251  // Methods for accessing the button's internal states.
252  // I don't expect these to be useful to the outside world.
253 
254  // If this is set, then mLastDebounceTime is valid.
255  bool isDebouncing() ACE_BUTTON_INLINE {
256  return mFlags & kFlagDebouncing;
257  }
258 
259  void setDebouncing() ACE_BUTTON_INLINE {
260  mFlags |= kFlagDebouncing;
261  }
262 
263  void clearDebouncing() ACE_BUTTON_INLINE {
264  mFlags &= ~kFlagDebouncing;
265  }
266 
267  // If this is set, then mLastPressTime is valid.
268  bool isPressed() ACE_BUTTON_INLINE {
269  return mFlags & kFlagPressed;
270  }
271 
272  void setPressed() ACE_BUTTON_INLINE {
273  mFlags |= kFlagPressed;
274  }
275 
276  void clearPressed() ACE_BUTTON_INLINE {
277  mFlags &= ~kFlagPressed;
278  }
279 
280  // If this is set, then mLastClickTime is valid.
281  bool isClicked() ACE_BUTTON_INLINE {
282  return mFlags & kFlagClicked;
283  }
284 
285  void setClicked() ACE_BUTTON_INLINE {
286  mFlags |= kFlagClicked;
287  }
288 
289  void clearClicked() ACE_BUTTON_INLINE {
290  mFlags &= ~kFlagClicked;
291  }
292 
293  // A double click was detected. No need to store the last double-clicked
294  // time because we don't support a triple-click event (yet).
295  bool isDoubleClicked() ACE_BUTTON_INLINE {
296  return mFlags & kFlagDoubleClicked;
297  }
298 
299  void setDoubleClicked() ACE_BUTTON_INLINE {
300  mFlags |= kFlagDoubleClicked;
301  }
302 
303  void clearDoubleClicked() ACE_BUTTON_INLINE {
304  mFlags &= ~kFlagDoubleClicked;
305  }
306 
307  // If this is set, then mLastPressTime can be treated as the start
308  // of a long press.
309  bool isLongPressed() ACE_BUTTON_INLINE {
310  return mFlags & kFlagLongPressed;
311  }
312 
313  void setLongPressed() ACE_BUTTON_INLINE {
314  mFlags |= kFlagLongPressed;
315  }
316 
317  void clearLongPressed() ACE_BUTTON_INLINE {
318  mFlags &= ~kFlagLongPressed;
319  }
320 
321  // If this is set, then mLastRepeatPressTime is valid.
322  bool isRepeatPressed() ACE_BUTTON_INLINE {
323  return mFlags & kFlagRepeatPressed;
324  }
325 
326  void setRepeatPressed() ACE_BUTTON_INLINE {
327  mFlags |= kFlagRepeatPressed;
328  }
329 
330  void clearRepeatPressed() ACE_BUTTON_INLINE {
331  mFlags &= ~kFlagRepeatPressed;
332  }
333 
334  bool isClickPostponed() ACE_BUTTON_INLINE {
335  return mFlags & kFlagClickPostponed;
336  }
337 
338  void setClickPostponed() ACE_BUTTON_INLINE {
339  mFlags |= kFlagClickPostponed;
340  }
341 
342  void clearClickPostponed() ACE_BUTTON_INLINE {
343  mFlags &= ~kFlagClickPostponed;
344  }
345 
351  bool checkDebounced(uint16_t now, uint8_t buttonState);
352 
359  bool checkInitialized(uint16_t buttonState);
360 
362  void checkEvent(uint16_t now, uint8_t buttonState);
363 
365  void checkLongPress(uint16_t now, uint8_t buttonState);
366 
368  void checkRepeatPress(uint16_t now, uint8_t buttonState);
369 
371  void checkChanged(uint16_t now, uint8_t buttonState);
372 
377  void checkReleased(uint16_t now, uint8_t buttonState);
378 
380  void checkPressed(uint16_t now, uint8_t buttonState);
381 
383  void checkClicked(uint16_t now);
384 
389  void checkDoubleClicked(uint16_t now);
390 
399  void checkOrphanedClick(uint16_t now);
400 
405  void checkPostponedClick(uint16_t now);
406 
453  void handleEvent(uint8_t eventType);
454 
455  uint8_t mPin; // button pin number
456  uint8_t mId; // identifier, e.g. an index into an array
457 
458  // Internal states of the button debouncing and event handling.
459  // NOTE: We don't keep track of the lastDoubleClickTime, because we
460  // don't support a TripleClicked event. That may change in the future.
461  uint16_t mLastDebounceTime; // ms
462  uint16_t mLastClickTime; // ms
463  uint16_t mLastPressTime; // ms
464  uint16_t mLastRepeatPressTime; // ms
465 
467  uint8_t mFlags;
468 
473  uint8_t mLastButtonState;
474 
476  ButtonConfig* mButtonConfig;
477 };
478 
479 }
480 #endif
void setEventHandler(ButtonConfig::EventHandler eventHandler) ACE_BUTTON_INLINE
Convenience method to set the event handler.
Definition: AceButton.h:154
void setButtonConfig(ButtonConfig *buttonConfig) ACE_BUTTON_INLINE
Set the ButtonConfig associated with this Button.
Definition: AceButton.h:141
uint8_t getDefaultReleasedState()
Get the initial released state of the button, HIGH or LOW.
Definition: AceButton.cpp:62
bool isReleased(uint8_t buttonState) ACE_BUTTON_INLINE
Returns true if the given buttonState represents a &#39;Released&#39; state for the button.
Definition: AceButton.h:209
uint8_t getLastButtonState() ACE_BUTTON_INLINE
Return the button state that was last valid.
Definition: AceButton.h:181
static const uint8_t kEventRepeatPressed
Button was held down and auto generated multiple presses.
Definition: AceButton.h:84
void setEventHandler(EventHandler eventHandler) ACE_BUTTON_INLINE
Install the event handler.
Definition: ButtonConfig.h:274
static const uint8_t kButtonStateUnknown
Button state is unknown.
Definition: AceButton.h:90
ButtonConfig * getButtonConfig() ACE_BUTTON_INLINE
Get the ButtonConfig associated with this Button.
Definition: AceButton.h:136
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:44
Class that defines the timing parameters and event handler of an AceButton or a group of AceButton in...
Definition: ButtonConfig.h:68
static const uint8_t kEventDoubleClicked
Button was double-clicked.
Definition: AceButton.h:70
static const uint8_t kEventLongPressed
Button was held down for longer than ButtonConfig::getLongPressDelay()).
Definition: AceButton.h:76
uint8_t getId() ACE_BUTTON_INLINE
Get the custom identifier of the button.
Definition: AceButton.h:163
void(* EventHandler)(AceButton *button, uint8_t eventType, uint8_t buttonState)
The event handler signature.
Definition: ButtonConfig.h:172
uint8_t getPin() ACE_BUTTON_INLINE
Get the button&#39;s pin number.
Definition: AceButton.h:160
void check()
Check state of button and trigger event processing.
Definition: AceButton.cpp:68
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:39
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