AceButton 1.10.0 An adjustable, compact, event-driven button library for Arduino.

Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
ace_button::ButtonConfig Class Reference

Class that defines the timing parameters and event handler of an AceButton or a group of AceButton instances. More...

`#include <ButtonConfig.h>`

Inheritance diagram for ace_button::ButtonConfig:
[legend]

## Public Types
typedef uint16_t | FeatureFlagType
| Type of the feature flag. More...
typedef void(* | EventHandler) (AceButton *button, uint8_t eventType, uint8_t buttonState)
| The event handler signature. More...

## Public Member Functions
| ButtonConfig ()=default
| Constructor.
virtual | ~ButtonConfig ()=default
| If the ButtonConfig is created and deleted on the heap, a virtual destructor is technically required by the C++ language to prevent memory leaks. More...
uint16_t | getDebounceDelay () const
| Milliseconds to wait for debouncing.
uint16_t | getClickDelay () const
| Milliseconds to wait for a possible click.
uint16_t | getDoubleClickDelay () const
| Milliseconds between the first and second click to register as a double-click.
uint16_t | getLongPressDelay () const
| Milliseconds for a long press event.
uint16_t | getRepeatPressDelay () const
| Milliseconds that a button needs to be Pressed down before the start of the sequence of RepeatPressed events. More...
uint16_t | getRepeatPressInterval () const
| Milliseconds between two successive RepeatPressed events.
uint16_t | getHeartBeatInterval () const
| Milliseconds between two successive HeartBeat events.
void | setDebounceDelay (uint16_t debounceDelay)
| Set the debounceDelay milliseconds.
void | setClickDelay (uint16_t clickDelay)
| Set the clickDelay milliseconds.
void | setDoubleClickDelay (uint16_t doubleClickDelay)
| Set the doubleClickDelay milliseconds.
void | setLongPressDelay (uint16_t longPressDelay)
| Set the longPressDelay milliseconds.
void | setRepeatPressDelay (uint16_t repeatPressDelay)
| Set the repeatPressDelay milliseconds.
void | setRepeatPressInterval (uint16_t repeatPressInterval)
| Set the repeatPressInterval milliseconds.
void | setHeartBeatInterval (uint16_t heartBeatInterval)
| Set the heartBeatInterval milliseconds.
virtual unsigned long | getClock ()
| Return the milliseconds of the internal clock. More...
virtual int | readButton (uint8_t pin)
| Return the HIGH or LOW state of the button. More...
bool | isFeature (FeatureFlagType features) const
| Check if the given features are enabled.
void | setFeature (FeatureFlagType features)
| Enable the given features.
void | clearFeature (FeatureFlagType features)
| Disable the given features.
void | resetFeatures ()
| Disable all (externally visible) features. More...
EventHandler | getEventHandler () const ACE_BUTTON_DEPRECATED
| Return the eventHandler function pointer. More...
void | dispatchEvent (AceButton *button, uint8_t eventType, uint8_t buttonState) const
| Dispatch the event to the handler. More...
void | setEventHandler (EventHandler eventHandler)
| Install the EventHandler function pointer. More...
void | setIEventHandler (IEventHandler *eventHandler)
| Install the IEventHandler object pointer. More...

## Static Public Member Functions
static ButtonConfig * | getSystemButtonConfig ()
| Return a pointer to the singleton instance of the ButtonConfig which is attached to all AceButton instances by default.

## Static Public Attributes
static const uint16_t | kDebounceDelay = 20
| Default milliseconds returned by getDebounceDelay().
static const uint16_t | kClickDelay = 200
| Default milliseconds returned by getClickDelay().
static const uint16_t | kDoubleClickDelay = 400
| Default milliseconds returned by getDoubleClickDelay().
static const uint16_t | kLongPressDelay = 1000
| Default milliseconds returned by getLongPressDelay().
static const uint16_t | kRepeatPressDelay = 1000
| Default milliseconds returned by getRepeatPressDelay().
static const uint16_t | kRepeatPressInterval = 200
| Default milliseconds returned by getRepeatPressInterval().
static const uint16_t | kHeartBeatInterval = 5000
| Default milliseconds returned by getHeartBeatInterval().
static const FeatureFlagType | kFeatureClick = 0x01
| Flag to activate the AceButton::kEventClicked event.
static const FeatureFlagType | kFeatureDoubleClick = 0x02
| Flag to activate the AceButton::kEventDoubleClicked event. More...
static const FeatureFlagType | kFeatureLongPress = 0x04
| Flag to activate the AceButton::kEventLongPress event.
static const FeatureFlagType | kFeatureRepeatPress = 0x08
| Flag to activate the AceButton::kEventRepeatPressed event.
static const FeatureFlagType | kFeatureSuppressAfterClick = 0x10
| Flag to suppress kEventReleased after a kEventClicked.
static const FeatureFlagType | kFeatureSuppressAfterDoubleClick = 0x20
| Flag to suppress kEventReleased after a kEventDoubleClicked. More...
static const FeatureFlagType | kFeatureSuppressAfterLongPress = 0x40
| Flag to suppress kEventReleased after a kEventLongPressed.
static const FeatureFlagType | kFeatureSuppressAfterRepeatPress = 0x80
| Flag to suppress kEventReleased after a kEventRepeatPressed.
static const FeatureFlagType | kFeatureSuppressClickBeforeDoubleClick = 0x100
| Flag to suppress kEventClicked before a kEventDoubleClicked. More...
static const FeatureFlagType | kFeatureHeartBeat = 0x200
| Flag to enable periodic kEventHeartBeat.
static const FeatureFlagType | kInternalFeatureIEventHandler = 0x8000
| Internal flag to indicate that mEventHandler is an IEventHandler object pointer instead of an EventHandler function pointer.
static const FeatureFlagType | kFeatureSuppressAll
| Convenience flag to suppress all suppressions. More...

## Detailed Description

Class that defines the timing parameters and event handler of an AceButton or a group of AceButton instances.

It is assumed that in many cases, a group of multiple buttons will need to be assigned the same configuration parameters. For example, various timing delays and the EventHandler. Instead of storing these parameters in each instance of AceButton (which consumes static memory), we save space by collecting them into a separate ButtonConfig class. Each AceButton instance contains a pointer to an instance of ButtonConfig, and an instance of ButtonConfig will be shared among multiple AceButtons.

Various timing parameters are given default values. They can be overridden by the user.

A single default "System" ButtonConfig instance is created automatically and can be accessed using the ButtConfig::getSystemButtonConfig() static method. For convenience and ease of use, every instance of AceButton is attached to this "System" ButtonConfig by default. The client code can override this association by attaching another ButtonConfig instance using the AceButton(ButtonConfig*) constuctor (the recommended solution) or the AceButton::setButtonConfig() method.

Definition at line 66 of file ButtonConfig.h.

## Member Typedef Documentation

## ◆ EventHandler

typedef void(* ace_button::ButtonConfig::EventHandler) (AceButton *button, uint8_t eventType, uint8_t buttonState)

The event handler signature.

Parameters

  button | pointer to the AceButton that generated the event
  eventType | the event type which trigger the call
  buttonState | the state of the button that triggered the event

Definition at line 182 of file ButtonConfig.h.

## ◆ FeatureFlagType

typedef uint16_t ace_button::ButtonConfig::FeatureFlagType

Type of the feature flag.

It used to be a uint8_t but got changed to a uint16_t when more than 8 flags were needed. Let's define a typedef to make it easier to change this in the future.

Definition at line 110 of file ButtonConfig.h.

## Constructor & Destructor Documentation

## ◆ ~ButtonConfig()

virtual ace_button::ButtonConfig::~ButtonConfig | ( |  | ) |
| virtual default

If the ButtonConfig is created and deleted on the heap, a virtual destructor is technically required by the C++ language to prevent memory leaks.

But ButtonConfig does not have any memory to leak, so everything is fine even without a virtual destructor. This virtual destructor definition is provided for the sole purpose of keeping the compiler quiet.

The problem is that for 8-bit AVR processors, the addition of a virtual destructor causes the flash memory size of the library to increase by 600 bytes, which is far too large compared to the ~1000 bytes consumed by the entire library. For 32-bit processors, the virtual destructor seems to increase the code size by 60-120 bytes, probably because the malloc/free are pulled in by something else already. This small increase in flash memory is tiny compared to the ~1 MB of total flash memory space offered by the ESP8266 and ESP32.

Therefore, I expose the virtual destructor only to non-AVR microcontrollers, which I hope means that only 32-bit chips with large flash memory will pay the cost of the virtual destructor. The check for the ARDUINO_ARCH_AVR macro seems to cover the ATmega328 chips (e.g. Arduino Nano), the ATmega32U4 (e.g. SparkFun Pro Micro), and the ATtiny85 (e.g. DigiSparks ATtiny85).

If there are other Arduino compatible boards with low flash memory that need to be excluded from the virtual destructor, we need to figure out the appropriate ARDUINO_ARCH_xxx macro, and add it to the `#if` statement above.

## Member Function Documentation

## ◆ dispatchEvent()

void ace_button::ButtonConfig::dispatchEvent | ( | AceButton * | button,
|  | uint8_t | eventType,
|  | uint8_t | buttonState
| ) |  | const
| inline

Dispatch the event to the handler.

This is meant to be an internal method.

Definition at line 370 of file ButtonConfig.h.

## ◆ getClock()

virtual unsigned long ace_button::ButtonConfig::getClock | ( |  | ) |
| inline virtual

Return the milliseconds of the internal clock.

Override to use something other than millis(). The return type is 'unsigned long' instead of uint16_t because that's the return type of millis().

Note: This should have been a const function. I cannot change it now without breaking backwards compatibility.

Definition at line 307 of file ButtonConfig.h.

## ◆ getEventHandler()

EventHandler ace_button::ButtonConfig::getEventHandler | ( |  | ) | const
| inline

Return the eventHandler function pointer.

This is meant to be an internal method.

Deprecated as of v1.6 because the event handler can now be either a function pointer or an object pointer. AceButton class now calls dispatchEvent() which correctly handles both cases. Application code should never need to retrieve the event handler directly.

Definition at line 362 of file ButtonConfig.h.

## ◆ getRepeatPressDelay()

uint16_t ace_button::ButtonConfig::getRepeatPressDelay | ( |  | ) | const
| inline

Milliseconds that a button needs to be Pressed down before the start of the sequence of RepeatPressed events.

The first event will fire as soon as this delay has passed. Subsequent events will fire after getRepeatPressInterval() time.

Definition at line 246 of file ButtonConfig.h.

## ◆ readButton()

virtual int ace_button::ButtonConfig::readButton | ( | uint8_t | pin | ) |
| inline virtual

Return the HIGH or LOW state of the button.

Override to use something other than digitalRead(). The return type is 'int' instead of uint16_t because that's the return type of digitalRead().

Note: This should have been a const function. I cannot change it now without breaking backwards compatibility.

Reimplemented in ace_button::ButtonConfigFast1< T_PIN0 >, ace_button::LadderButtonConfig, ace_button::ButtonConfigFast3< T_PIN0, T_PIN1, T_PIN2 >, ace_button::ButtonConfigFast2< T_PIN0, T_PIN1 >, ace_button::EncodedButtonConfig, ace_button::Encoded8To3ButtonConfig, and ace_button::Encoded4To2ButtonConfig.

Definition at line 317 of file ButtonConfig.h.

## ◆ resetFeatures()

void ace_button::ButtonConfig::resetFeatures | ( |  | ) |
| inline

Disable all (externally visible) features.

Useful when the ButtonConfig is reused in different configurations. Also useful for testing. Internal feature flags (e.g. kInternalFeatureIEventHandler) are not cleared.

Definition at line 344 of file ButtonConfig.h.

## ◆ setEventHandler()

void ace_button::ButtonConfig::setEventHandler | ( | EventHandler | eventHandler | ) |
| inline

Install the EventHandler function pointer.

The event handler must be defined for the AceButton to be useful.

Definition at line 390 of file ButtonConfig.h.

## ◆ setIEventHandler()

void ace_button::ButtonConfig::setIEventHandler | ( | IEventHandler * | eventHandler | ) |
| inline

Install the IEventHandler object pointer.

The event handler must be defined for the AceButton to be useful.

Definition at line 399 of file ButtonConfig.h.

## Member Data Documentation

## ◆ kFeatureDoubleClick

const FeatureFlagType ace_button::ButtonConfig::kFeatureDoubleClick = 0x02
| static

Flag to activate the AceButton::kEventDoubleClicked event.

Activating this automatically activates kEventClicked since there is no double-click without a click.

Definition at line 120 of file ButtonConfig.h.

## ◆ kFeatureSuppressAfterDoubleClick

const FeatureFlagType ace_button::ButtonConfig::kFeatureSuppressAfterDoubleClick = 0x20
| static

Flag to suppress kEventReleased after a kEventDoubleClicked.

A kEventClicked is always suppressed after a kEventDoubleClicked to prevent generating 2 double-clicks if the user performed a triple-click.

Definition at line 136 of file ButtonConfig.h.

## ◆ kFeatureSuppressAll

const FeatureFlagType ace_button::ButtonConfig::kFeatureSuppressAll
| static

Initial value:
= (
kFeatureSuppressAfterClick
| kFeatureSuppressAfterDoubleClick
| kFeatureSuppressAfterLongPress
| kFeatureSuppressAfterRepeatPress
| kFeatureSuppressClickBeforeDoubleClick)
ace_button::ButtonConfig::kFeatureSuppressAfterLongPress
static const FeatureFlagType kFeatureSuppressAfterLongPress
Flag to suppress kEventReleased after a kEventLongPressed.
Definition: ButtonConfig.h:139
ace_button::ButtonConfig::kFeatureSuppressAfterClick
static const FeatureFlagType kFeatureSuppressAfterClick
Flag to suppress kEventReleased after a kEventClicked.
Definition: ButtonConfig.h:129
ace_button::ButtonConfig::kFeatureSuppressAfterRepeatPress
static const FeatureFlagType kFeatureSuppressAfterRepeatPress
Flag to suppress kEventReleased after a kEventRepeatPressed.
Definition: ButtonConfig.h:142
ace_button::ButtonConfig::kFeatureSuppressAfterDoubleClick
static const FeatureFlagType kFeatureSuppressAfterDoubleClick
Flag to suppress kEventReleased after a kEventDoubleClicked.
Definition: ButtonConfig.h:136
ace_button::ButtonConfig::kFeatureSuppressClickBeforeDoubleClick
static const FeatureFlagType kFeatureSuppressClickBeforeDoubleClick
Flag to suppress kEventClicked before a kEventDoubleClicked.
Definition: ButtonConfig.h:150

Convenience flag to suppress all suppressions.

Calling setFeature(kFeatureSuppressAll) suppresses all and clearFeature(kFeatureSuppressAll) clears all suppression. Note however that isFeature(kFeatureSuppressAll) currently means "is ANY feature enabled?" not "are ALL features enabled?".

Definition at line 168 of file ButtonConfig.h.

## ◆ kFeatureSuppressClickBeforeDoubleClick

const FeatureFlagType ace_button::ButtonConfig::kFeatureSuppressClickBeforeDoubleClick = 0x100
| static

Flag to suppress kEventClicked before a kEventDoubleClicked.

This causes the notification of a kEventClicked to be delayed until the delay time of getDoubleClickDelay() has passed so that we can determine if there was a kEventDoubleClicked.

Definition at line 150 of file ButtonConfig.h.

The documentation for this class was generated from the following files:

- /home/brian/src/AceButton/src/ace_button/ButtonConfig.h
- /home/brian/src/AceButton/src/ace_button/ButtonConfig.cpp