AceButton  1.0.6
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 
184  void check();
185 
201  bool isReleased(uint8_t buttonState) ACE_BUTTON_INLINE {
202  return buttonState == getDefaultReleasedState();
203  }
204 
205  // Some of these private methods may be useful to the calling client but I
206  // don't want to release them to the public because I want to keep the API as
207  // small as possible for easier long term maintenance. (Once a method is
208  // released to the public, it must be supported forever to ensure backwards
209  // compatibility with older client code.)
210 
211  private:
212  // Disable copy-constructor and assignment operator
213  AceButton(const AceButton&) = delete;
214  AceButton& operator=(const AceButton&) = delete;
215 
217  void setPin(uint8_t pin) ACE_BUTTON_INLINE { mPin = pin; }
218 
226  void setDefaultReleasedState(uint8_t state);
227 
229  void setId(uint8_t id) ACE_BUTTON_INLINE { mId = id; }
230 
231  // Various bit masks to store a boolean flag in the 'mFlags' field.
232  // We use bit masks to save static RAM. If we had used a 'bool' type, each
233  // of these would consume one byte.
234  static const uint8_t kFlagDefaultReleasedState = 0x01;
235  static const uint8_t kFlagDebouncing = 0x02;
236  static const uint8_t kFlagPressed = 0x04;
237  static const uint8_t kFlagClicked = 0x08;
238  static const uint8_t kFlagDoubleClicked = 0x10;
239  static const uint8_t kFlagLongPressed = 0x20;
240  static const uint8_t kFlagRepeatPressed = 0x40;
241  static const uint8_t kFlagClickPostponed = 0x80;
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 
326  bool isClickPostponed() ACE_BUTTON_INLINE {
327  return mFlags & kFlagClickPostponed;
328  }
329 
330  void setClickPostponed() ACE_BUTTON_INLINE {
331  mFlags |= kFlagClickPostponed;
332  }
333 
334  void clearClickPostponed() ACE_BUTTON_INLINE {
335  mFlags &= ~kFlagClickPostponed;
336  }
337 
343  bool checkDebounced(uint16_t now, uint8_t buttonState);
344 
351  bool checkInitialized(uint16_t buttonState);
352 
354  void checkLongPress(uint16_t now, uint8_t buttonState);
355 
357  void checkRepeatPress(uint16_t now, uint8_t buttonState);
358 
360  void checkChanged(uint16_t now, uint8_t buttonState);
361 
366  void checkReleased(uint16_t now, uint8_t buttonState);
367 
369  void checkPressed(uint16_t now, uint8_t buttonState);
370 
372  void checkClicked(uint16_t now);
373 
378  void checkDoubleClicked(uint16_t now);
379 
388  void checkOrphanedClick(uint16_t now);
389 
394  void checkPostponedClick(uint16_t now);
395 
442  void handleEvent(uint8_t eventType);
443 
444  uint8_t mPin; // button pin number
445  uint8_t mId; // identifier, e.g. an index into an array
446 
447  // Internal states of the button debouncing and event handling.
448  // NOTE: We don't keep track of the lastDoubleClickTime, because we
449  // don't support a TripleClicked event. That may change in the future.
450  uint16_t mLastDebounceTime; // ms
451  uint16_t mLastClickTime; // ms
452  uint16_t mLastPressTime; // ms
453  uint16_t mLastRepeatPressTime; // ms
454 
456  uint8_t mFlags;
457 
462  uint8_t mLastButtonState;
463 
465  ButtonConfig* mButtonConfig;
466 };
467 
468 }
469 #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
uint8_t getDefaultReleasedState()
Get the initial released state of the button, HIGH or LOW.
Definition: AceButton.cpp:60
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:201
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:258
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
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:42
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
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(* EventHandler)(AceButton *button, uint8_t eventType, uint8_t buttonState)
The event handler signature.
Definition: ButtonConfig.h:164
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:66
An Adjustable Compact Event-driven (ACE) Button library that debounces and dispatches button events t...
Definition: AceButton.h:42
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:37
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