AceButton  1.2
An adjustable, compact, event-driven (ACE) button library for Arduino.
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | 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:
Inheritance graph
[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 ()
 Constructor. More...
 
virtual uint16_t getDebounceDelay ()
 Milliseconds to wait for debouncing. More...
 
virtual uint16_t getClickDelay ()
 Milliseconds to wait for a possible click. More...
 
virtual uint16_t getDoubleClickDelay ()
 Milliseconds between the first and second click to register as a double-click.
 
virtual uint16_t getLongPressDelay ()
 Milliseconds for a long press event. More...
 
virtual uint16_t getRepeatPressDelay ()
 Milliseconds that a button needs to be Pressed down before the start of the sequence of RepeatPressed events. More...
 
virtual uint16_t getRepeatPressInterval ()
 Milliseconds between two successive RepeatPressed events.
 
virtual unsigned long getClock ()
 Return the milliseconds of the internal clock. More...
 
virtual unsigned long getClockMicros ()
 Return the microseconds 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) ACE_BUTTON_INLINE
 Check if the given features are enabled. More...
 
void setFeature (FeatureFlagType features) ACE_BUTTON_INLINE
 Enable the given features. More...
 
void clearFeature (FeatureFlagType features) ACE_BUTTON_INLINE
 Disable the given features. More...
 
EventHandler getEventHandler () ACE_BUTTON_INLINE
 Return the eventHandler. More...
 
void setEventHandler (EventHandler eventHandler) ACE_BUTTON_INLINE
 Install the event handler. More...
 
void setTimingStats (TimingStats *timingStats)
 Set the timing stats object. More...
 
TimingStatsgetTimingStats ()
 Get the timing stats. More...
 

Static Public Member Functions

static ButtonConfiggetSystemButtonConfig () ACE_BUTTON_INLINE
 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 = 50
 Default value returned by getDebounceDelay(). More...
 
static const uint16_t kClickDelay = 200
 Default value returned by getClickDelay(). More...
 
static const uint16_t kDoubleClickDelay = 400
 Default value returned by getDoubleClickDelay(). More...
 
static const uint16_t kLongPressDelay = 1000
 Default value returned by getLongPressDelay(). More...
 
static const uint16_t kRepeatPressDelay = 1000
 Default value returned by getRepeatPressDelay(). More...
 
static const uint16_t kRepeatPressInterval = 200
 Default value returned by getRepeatPressInterval(). More...
 
static const FeatureFlagType kFeatureClick = 0x01
 Flag to activate the AceButton::kEventClicked event. More...
 
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. More...
 
static const FeatureFlagType kFeatureRepeatPress = 0x08
 Flag to activate the AceButton::kEventRepeatPressed event. More...
 
static const FeatureFlagType kFeatureSuppressAfterClick = 0x10
 Flag to suppress kEventReleased after a kEventClicked. More...
 
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. More...
 
static const FeatureFlagType kFeatureSuppressAfterRepeatPress = 0x80
 Flag to suppress kEventReleased after a kEventRepeatPressed. More...
 
static const FeatureFlagType kFeatureSuppressClickBeforeDoubleClick = 0x100
 Flag to suppress kEventClicked before a kEventDoubleClicked. More...
 
static const FeatureFlagType kFeatureSuppressAll
 Convenience flag to suppress all suppressions. More...
 

Protected Member Functions

virtual void init ()
 Initialize to its pristine state, except for the EventHandler which is unchanged. 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.

Most of the parameters are actually hardwired into the various virtual methods below. This has the advantage of reducing memory consumption of even this class. If a parameter needs to be changed, there are 2 options:

  1. Use the AdjustableButtonConfig subclass which allows all of these parameters to be changed at runtime, at the cost of additional static memory usage to hold those parameters.
  2. Subclass this ButtonConfig class, then override only the specific method to modify the specific timing parameter. This has the advantage of consuming no additional static RAM, at the expense of creating another class.

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 69 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
buttonpointer to the AceButton that generated the event
eventTypethe event type which trigger the call
buttonStatethe state of the button that triggered the event

Definition at line 173 of file ButtonConfig.h.

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

ace_button::ButtonConfig::ButtonConfig ( )

Constructor.

Definition at line 32 of file ButtonConfig.cpp.

Member Function Documentation

◆ clearFeature()

void ace_button::ButtonConfig::clearFeature ( FeatureFlagType  features)
inline

Disable the given features.

Definition at line 260 of file ButtonConfig.h.

◆ getClickDelay()

virtual uint16_t ace_button::ButtonConfig::getClickDelay ( )
inlinevirtual

Milliseconds to wait for a possible click.

Reimplemented in ace_button::AdjustableButtonConfig.

Definition at line 188 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().

Definition at line 229 of file ButtonConfig.h.

◆ getClockMicros()

virtual unsigned long ace_button::ButtonConfig::getClockMicros ( )
inlinevirtual

Return the microseconds of the internal clock.

Can be overridden for testing purposes.

Definition at line 235 of file ButtonConfig.h.

◆ getDebounceDelay()

virtual uint16_t ace_button::ButtonConfig::getDebounceDelay ( )
inlinevirtual

Milliseconds to wait for debouncing.

Reimplemented in ace_button::AdjustableButtonConfig.

Definition at line 185 of file ButtonConfig.h.

◆ getEventHandler()

EventHandler ace_button::ButtonConfig::getEventHandler ( )
inline

Return the eventHandler.

Definition at line 267 of file ButtonConfig.h.

◆ getLongPressDelay()

virtual uint16_t ace_button::ButtonConfig::getLongPressDelay ( )
inlinevirtual

Milliseconds for a long press event.

Reimplemented in ace_button::AdjustableButtonConfig.

Definition at line 199 of file ButtonConfig.h.

◆ getRepeatPressDelay()

virtual uint16_t ace_button::ButtonConfig::getRepeatPressDelay ( )
inlinevirtual

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.

Reimplemented in ace_button::AdjustableButtonConfig.

Definition at line 209 of file ButtonConfig.h.

◆ getTimingStats()

TimingStats* ace_button::ButtonConfig::getTimingStats ( )
inline

Get the timing stats.

Can return nullptr.

Definition at line 287 of file ButtonConfig.h.

◆ init()

virtual void ace_button::ButtonConfig::init ( )
inlineprotectedvirtual

Initialize to its pristine state, except for the EventHandler which is unchanged.

This is intended mostly for testing purposes.

Reimplemented in ace_button::AdjustableButtonConfig.

Definition at line 302 of file ButtonConfig.h.

◆ isFeature()

bool ace_button::ButtonConfig::isFeature ( FeatureFlagType  features)
inline

Check if the given features are enabled.

Definition at line 250 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().

Definition at line 242 of file ButtonConfig.h.

◆ setEventHandler()

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

Install the event handler.

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

Definition at line 275 of file ButtonConfig.h.

◆ setFeature()

void ace_button::ButtonConfig::setFeature ( FeatureFlagType  features)
inline

Enable the given features.

Definition at line 255 of file ButtonConfig.h.

◆ setTimingStats()

void ace_button::ButtonConfig::setTimingStats ( TimingStats timingStats)
inline

Set the timing stats object.

The timingStats can be nullptr.

Definition at line 282 of file ButtonConfig.h.

Member Data Documentation

◆ kClickDelay

const uint16_t ace_button::ButtonConfig::kClickDelay = 200
static

Default value returned by getClickDelay().

Definition at line 89 of file ButtonConfig.h.

◆ kDebounceDelay

const uint16_t ace_button::ButtonConfig::kDebounceDelay = 50
static

Default value returned by getDebounceDelay().

Definition at line 86 of file ButtonConfig.h.

◆ kDoubleClickDelay

const uint16_t ace_button::ButtonConfig::kDoubleClickDelay = 400
static

Default value returned by getDoubleClickDelay().

Definition at line 92 of file ButtonConfig.h.

◆ kFeatureClick

const FeatureFlagType ace_button::ButtonConfig::kFeatureClick = 0x01
static

Flag to activate the AceButton::kEventClicked event.

Definition at line 113 of file ButtonConfig.h.

◆ 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.

◆ kFeatureLongPress

const FeatureFlagType ace_button::ButtonConfig::kFeatureLongPress = 0x04
static

Flag to activate the AceButton::kEventLongPress event.

Definition at line 123 of file ButtonConfig.h.

◆ kFeatureRepeatPress

const FeatureFlagType ace_button::ButtonConfig::kFeatureRepeatPress = 0x08
static

Flag to activate the AceButton::kEventRepeatPressed event.

Definition at line 126 of file ButtonConfig.h.

◆ kFeatureSuppressAfterClick

const FeatureFlagType ace_button::ButtonConfig::kFeatureSuppressAfterClick = 0x10
static

Flag to suppress kEventReleased after a kEventClicked.

Definition at line 129 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.

◆ kFeatureSuppressAfterLongPress

const FeatureFlagType ace_button::ButtonConfig::kFeatureSuppressAfterLongPress = 0x40
static

Flag to suppress kEventReleased after a kEventLongPressed.

Definition at line 139 of file ButtonConfig.h.

◆ kFeatureSuppressAfterRepeatPress

const FeatureFlagType ace_button::ButtonConfig::kFeatureSuppressAfterRepeatPress = 0x80
static

Flag to suppress kEventReleased after a kEventRepeatPressed.

Definition at line 142 of file ButtonConfig.h.

◆ kFeatureSuppressAll

const FeatureFlagType ace_button::ButtonConfig::kFeatureSuppressAll
static
Initial value:

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 159 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.

◆ kLongPressDelay

const uint16_t ace_button::ButtonConfig::kLongPressDelay = 1000
static

Default value returned by getLongPressDelay().

Definition at line 95 of file ButtonConfig.h.

◆ kRepeatPressDelay

const uint16_t ace_button::ButtonConfig::kRepeatPressDelay = 1000
static

Default value returned by getRepeatPressDelay().

Definition at line 98 of file ButtonConfig.h.

◆ kRepeatPressInterval

const uint16_t ace_button::ButtonConfig::kRepeatPressInterval = 200
static

Default value returned by getRepeatPressInterval().

Definition at line 101 of file ButtonConfig.h.


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