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 ( )

virtualdefault

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 ( )

inlinevirtual

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 )

inlinevirtual

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)

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

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ EventHandler

◆ FeatureFlagType

Constructor & Destructor Documentation

◆ ~ButtonConfig()

Member Function Documentation

◆ dispatchEvent()

◆ getClock()

◆ getEventHandler()

◆ getRepeatPressDelay()

◆ readButton()

◆ resetFeatures()

◆ setEventHandler()

◆ setIEventHandler()

Member Data Documentation

◆ kFeatureDoubleClick

◆ kFeatureSuppressAfterDoubleClick

◆ kFeatureSuppressAll

◆ kFeatureSuppressClickBeforeDoubleClick