AceButton  1.0.0
An Adjustable Compact Event-driven (ACE) button library for Arduino.
AceButton.h
1 /*
2  Copyright 2018 Brian T. Park
3 
4  Licensed under the Apache License, Version 2.0 (the "License");
5  you may not use this file except in compliance with the License.
6  You may obtain a copy of the License at
7 
8  http://www.apache.org/licenses/LICENSE-2.0
9 
10  Unless required by applicable law or agreed to in writing, software
11  distributed under the License is distributed on an "AS IS" BASIS,
12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  See the License for the specific language governing permissions and
14  limitations under the License.
15 */
16 
17 #ifndef ACE_BUTTON_H
18 #define ACE_BUTTON_H
19 
20 #include <Arduino.h>
21 #include "ButtonConfig.h"
22 
23 namespace ace_button {
24 
42 class AceButton {
43  public:
44  // The supported event types.
45 
47  static const uint8_t kEventPressed = 0;
48 
50  static const uint8_t kEventReleased = 1;
51 
56  static const uint8_t kEventClicked = 2;
57 
62  static const uint8_t kEventDoubleClicked = 3;
63 
68  static const uint8_t kEventLongPressed = 4;
69 
76  static const uint8_t kEventRepeatPressed = 5;
77 
82  static const uint8_t kButtonStateUnknown = 2;
83 
116  explicit AceButton(uint8_t pin = 0, uint8_t defaultReleasedState = HIGH,
117  uint8_t id = 0);
118 
124  void init(uint8_t pin = 0, uint8_t defaultReleasedState = HIGH,
125  uint8_t id = 0);
126 
128  ButtonConfig* getButtonConfig() ACE_BUTTON_INLINE {
129  return mButtonConfig;
130  }
131 
133  void setButtonConfig(ButtonConfig* buttonConfig) ACE_BUTTON_INLINE {
134  mButtonConfig = buttonConfig;
135  }
136 
147  ACE_BUTTON_INLINE {
148  mButtonConfig->setEventHandler(eventHandler);
149  }
150 
152  uint8_t getPin() ACE_BUTTON_INLINE { return mPin; }
153 
155  uint8_t getId() ACE_BUTTON_INLINE { return mId; }
156 
158  uint8_t getDefaultReleasedState();
159 
173  uint8_t getLastButtonState() ACE_BUTTON_INLINE {
174  return mLastButtonState;
175  }
176 
185  void check();
186 
202  bool isReleased(uint8_t buttonState) ACE_BUTTON_INLINE {
203  return buttonState == getDefaultReleasedState();
204  }
205 
206  // Some of these protected methods may be useful to the calling client but I
207  // don't want to release them to the public because I want to keep the API as
208  // small as possible for easier long term maintenance. (Once a method is
209  // released to the public, it must be supported forever to ensure backwards
210  // compatibility with older client code.)
211 
212  private:
213  // Disable copy-constructor and assignment operator
214  AceButton(const AceButton&) = delete;
215  AceButton& operator=(const AceButton&) = delete;
216 
218  void setPin(uint8_t pin) ACE_BUTTON_INLINE { mPin = pin; }
219 
227  void setDefaultReleasedState(uint8_t state);
228 
230  void setId(uint8_t id) ACE_BUTTON_INLINE { mId = id; }
231 
232  // Various bit masks to store a boolean flag in the 'mFlags' field.
233  // We use bit masks to save static RAM. If we had used a 'bool' type, each
234  // of these would consume one byte.
235  static const uint8_t kFlagDefaultReleasedState = 0x01;
236  static const uint8_t kFlagDebouncing = 0x02;
237  static const uint8_t kFlagPressed = 0x04;
238  static const uint8_t kFlagClicked = 0x08;
239  static const uint8_t kFlagDoubleClicked = 0x10;
240  static const uint8_t kFlagLongPressed = 0x20;
241  static const uint8_t kFlagRepeatPressed = 0x40;
242 
243  // Methods for accessing the button's internal states.
244  // I don't expect these to be useful to the outside world.
245 
246  // If this is set, then mLastDebounceTime is valid.
247  bool isDebouncing() ACE_BUTTON_INLINE {
248  return mFlags & kFlagDebouncing;
249  }
250 
251  void setDebouncing() ACE_BUTTON_INLINE {
252  mFlags |= kFlagDebouncing;
253  }
254 
255  void clearDebouncing() ACE_BUTTON_INLINE {
256  mFlags &= ~kFlagDebouncing;
257  }
258 
259  // If this is set, then mLastPressTime is valid.
260  bool isPressed() ACE_BUTTON_INLINE {
261  return mFlags & kFlagPressed;
262  }
263 
264  void setPressed() ACE_BUTTON_INLINE {
265  mFlags |= kFlagPressed;
266  }
267 
268  void clearPressed() ACE_BUTTON_INLINE {
269  mFlags &= ~kFlagPressed;
270  }
271 
272  // If this is set, then mLastClickTime is valid.
273  bool isClicked() ACE_BUTTON_INLINE {
274  return mFlags & kFlagClicked;
275  }
276 
277  void setClicked() ACE_BUTTON_INLINE {
278  mFlags |= kFlagClicked;
279  }
280 
281  void clearClicked() ACE_BUTTON_INLINE {
282  mFlags &= ~kFlagClicked;
283  }
284 
285  // A double click was detected. No need to store the last double-clicked
286  // time because we don't support a triple-click event (yet).
287  bool isDoubleClicked() ACE_BUTTON_INLINE {
288  return mFlags & kFlagDoubleClicked;
289  }
290 
291  void setDoubleClicked() ACE_BUTTON_INLINE {
292  mFlags |= kFlagDoubleClicked;
293  }
294 
295  void clearDoubleClicked() ACE_BUTTON_INLINE {
296  mFlags &= ~kFlagDoubleClicked;
297  }
298 
299  // If this is set, then mLastPressTime can be treated as the start
300  // of a long press.
301  bool isLongPressed() ACE_BUTTON_INLINE {
302  return mFlags & kFlagLongPressed;
303  }
304 
305  void setLongPressed() ACE_BUTTON_INLINE {
306  mFlags |= kFlagLongPressed;
307  }
308 
309  void clearLongPressed() ACE_BUTTON_INLINE {
310  mFlags &= ~kFlagLongPressed;
311  }
312 
313  // If this is set, then mLastRepeatPressTime is valid.
314  bool isRepeatPressed() ACE_BUTTON_INLINE {
315  return mFlags & kFlagRepeatPressed;
316  }
317 
318  void setRepeatPressed() ACE_BUTTON_INLINE {
319  mFlags |= kFlagRepeatPressed;
320  }
321 
322  void clearRepeatPressed() ACE_BUTTON_INLINE {
323  mFlags &= ~kFlagRepeatPressed;
324  }
325 
331  bool checkDebounced(uint16_t now, uint8_t buttonState);
332 
339  bool checkInitialized(uint16_t now, uint16_t buttonState);
340 
342  void checkLongPress(uint16_t now, uint8_t buttonState);
343 
345  void checkRepeatPress(uint16_t now, uint8_t buttonState);
346 
348  void checkChanged(uint16_t now, uint8_t buttonState);
349 
354  void checkReleased(uint16_t now, uint8_t buttonState);
355 
357  void checkPressed(uint16_t now, uint8_t buttonState);
358 
360  void checkClicked(uint16_t now, uint8_t buttonState);
361 
366  void checkDoubleClicked(uint16_t now, uint8_t buttonState);
367 
376  void checkOrphanedClick(uint16_t now, uint8_t buttonState);
377 
424  void handleEvent(uint8_t eventType);
425 
426  uint8_t mPin; // button pin number
427  uint8_t mId; // identifier, e.g. an index into an array
428 
429  // Internal states of the button debouncing and event handling.
430  // NOTE: We don't keep track of the lastDoubleClickTime, because we
431  // don't support a TripleClicked event. That may change in the future.
432  uint16_t mLastDebounceTime; // ms
433  uint16_t mLastClickTime; // ms
434  uint16_t mLastPressTime; // ms
435  uint16_t mLastRepeatPressTime; // ms
436 
438  uint8_t mFlags;
439 
444  uint8_t mLastButtonState;
445 
447  ButtonConfig* mButtonConfig;
448 };
449 
450 }
451 #endif
void setEventHandler(ButtonConfig::EventHandler eventHandler) ACE_BUTTON_INLINE
Convenience method to set the event handler.
Definition: AceButton.h:146
void setButtonConfig(ButtonConfig *buttonConfig) ACE_BUTTON_INLINE
Set the ButtonConfig associated with this Button.
Definition: AceButton.h:133
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:202
uint8_t getLastButtonState() ACE_BUTTON_INLINE
Return the button state that was last valid.
Definition: AceButton.h:173
static const uint8_t kEventRepeatPressed
Button was held down and auto generated multiple presses.
Definition: AceButton.h:76
void setEventHandler(EventHandler eventHandler) ACE_BUTTON_INLINE
Install the event handler.
Definition: ButtonConfig.h:242
static const uint8_t kButtonStateUnknown
Button state is unknown.
Definition: AceButton.h:82
ButtonConfig * getButtonConfig() ACE_BUTTON_INLINE
Get the ButtonConfig associated with this Button.
Definition: AceButton.h:128
Definition: AceButton.h:23
Class that defines the timing parameters and event handler of an AceButton or a group of AceButton in...
Definition: ButtonConfig.h:60
static const uint8_t kEventDoubleClicked
Button was double-clicked.
Definition: AceButton.h:62
uint8_t getDefaultReleasedState()
Get the initial released state of the button, HIGH or LOW.
Definition: AceButton.cpp:53
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:30
static const uint8_t kEventLongPressed
Button was held down for longer than ButtonConfig::getLongPressDelay()).
Definition: AceButton.h:68
uint8_t getId() ACE_BUTTON_INLINE
Get the custom identifier of the button.
Definition: AceButton.h:155
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:35
void(* EventHandler)(AceButton *button, uint8_t eventType, uint8_t buttonState)
The event handler signature.
Definition: ButtonConfig.h:148
uint8_t getPin() ACE_BUTTON_INLINE
Get the button&#39;s pin number.
Definition: AceButton.h:152
void check()
Check state of button and trigger event processing.
Definition: AceButton.cpp:59
An Adjustable Compact Event-driven (ACE) Button library that debounces and dispatches button events t...
Definition: AceButton.h:42
static const uint8_t kEventReleased
Button was released.
Definition: AceButton.h:50
static const uint8_t kEventPressed
Button was pressed.
Definition: AceButton.h:47
static const uint8_t kEventClicked
Button was clicked (Pressed and Released within ButtonConfig::getClickDelay()).
Definition: AceButton.h:56