Description

The EventEncoderButton class combines the EventEncoder class with the EventButton class and is used for the common encoder buttons.

This class provides all the EventEncoder & EventButton events with the addition of CHANGED_PRESSED & CHANGED_RELEASED which is fired when the encoder is turned while pressed.

The following InputEventTypes are fired by EventEncoderButton:

InputEventType::ENABLED - fired when the input is enabled.
InputEventType::DISABLED - fired when the input is disabled.
InputEventType::IDLE - fired after no other event (except ENABLED & DISABLED) has been fired for a specified time. Each input can define its own idle timeout. Default is 10 seconds.
InputEventType::PRESSED - fired after (as) a button is pressed
InputEventType::RELEASED - fired after a button is released.
InputEventType::CLICKED - fired after RELEASED if not LONG_CLICKED and button is pressed and released once.
InputEventType::DOUBLE_CLICKED - fired after RELEASED if not LONG_CLICKED and button is pressed and released twice.
InputEventType::MULTI_CLICKED - fired after RELEASED if not LONG_CLICKED and button is pressed and released more than twice (no limit!). The method clickCount() returns the number of clicks.
InputEventType::LONG_PRESS - fired during a long press (hence change of tense). Will repeat by default but this can be turned off.
InputEventType::LONG_CLICKED - fired after a long press.
InputEventType::CHANGED - fired on each change of position (if min/max limits are not exceeded and wrapping if false)
InputEventType::CHANGED_PRESSED - fired on each change of position while pressed (if min/max limits are not exceeded and wrapping if false)
InputEventType::CHANGED_RELEASED - fired after a button is released if the encoder was turned while pressed and a PRESSED_CHANGED event has fired.

‍Note: When the encoder is not pressed and turned, its button behaves just like a regular EventButton but if the encoder is turned while pressed, the following changes to events occur:

on release, the button's RELEASED event is translated to a CHANGED_RELEASED event if a PRESSED_CHANGED event has been fired

the LONG_PRESS, CLICKED and LONG_CLICKED are not fired.

#include <EventEncoderButton.h>

Inheritance diagram for EventEncoderButton:

[legend]

Public Member Functions
Constructors
	EventEncoderButton (EncoderAdapter *encoderAdapter, byte buttonPin, bool useDefaultDebouncer=true)
	Construct an EventEncoderButton input from an EncoderAdapter and a pin. More...

	EventEncoderButton (EncoderAdapter encoderAdapter, PinAdapter _pinAdapter, bool useDefaultDebouncer=true)
	Construct a new EventButton with a PinAdapter and optionally use the default debouncer. More...

	EventEncoderButton (EncoderAdapter encoderAdapter, PinAdapter _pinAdapter, DebounceAdapter *debounceAdapter)
	Construct a new EventButton with a PinAdapter and a DebounceAdapter. More...

Common Methods
These methods are common to all InputEvent classes. Additional methods for input enable, timeout, event blocking and user ID/value are also inherited from the EventInputBase class.
void	begin ()
	Initialise the EventEncoderButton. More...

void	setCallback (CallbackFunction f)
	Set the Callback function. More...

template<typename T >
void	setCallback (T instance, void(T::method)(InputEventType, EventEncoderButton &))
	Set the Callback function to a class method. More...

void	unsetCallback () override
	Unset a previously set callback function or method. More...

void	update ()
	Update the state from the underlying encoder library and button pin. More...

Getting the State
These methods return the current state of the input (as set during the last update() )
int16_t	increment ()
	Returns a positive (CW) or negative (CCW) integer. More...

int32_t	position ()
	The current position of the encoder. Can be reset with resetPosition()

int32_t	pressedPosition ()
	The current pressed position of the encoder. Can be reset with resetPressedPosition()

uint8_t	clickCount ()
	The number of clicks that have been fired in the MULTI_CLICKED event. More...

uint8_t	longPressCount ()
	The number of times the long press has occurred during a button press. More...

bool	isPressed ()
	Returns true if button is pressed.

uint32_t	currentDuration ()
	Duration in milliseconds of the current button state. More...

uint32_t	previousDuration ()
	Duration in milliseconds of the previous button state. More...

Setting limits for position() and pressedPosition().
High and low limits can be set for both position() and pressedPosition(). If either setMinPosition() or setMaxPosition() are non zero, the limits will be applied to position() If either setMinPressedPosition() or setMaxPressedPosition() are non zero, the limits will be applied to pressedPosition() There are two behaviours defined by wrapMinMaxPosition() and wrapMinMaxPressedPosition(). The default (false) is to not wrap.
void	setMinPosition (int32_t minPosition=0)
	Set a lower limit for the encoder position. More...

void	setMaxPosition (int32_t maxPosition=0)
	Set an upper limit for the encoder position. More...

void	wrapMinMaxPosition (bool wrap)
	Wrap the max -> min -> max ... (default is to not wrap) More...

void	setMinPressedPosition (int32_t minPressedPosition=0)
	Set a lower limit for the encoder pressed position. More...

void	setMaxPressedPosition (int32_t maxPressedPosition=0)
	Set an upper limit for the encoder pressed position. More...

void	wrapMinMaxPressedPosition (bool wrap)
	Wrap the max -> min -> max ... (default is to not wrap) More...

Other Configuration Settings
void	setRateLimit (long ms)
	Encoder callbacks are normally fired on every loop() but for MPG style encoders this can fire a huge number of events (that may swamp a serial connection). More...

void	setPositionDivider (uint8_t divider=4)
	Quadrature encoders usually have four states for each 'click' of the rotary control, although some have just 2. More...

uint8_t	getPositionDivider ()
	Get the currently set position divider value. More...

void	resetPosition (int32_t pos=0)
	Reset the counted position of the EventEncoderButton. More...

void	resetPressedPosition (int32_t pos)
	Reset the counted pressed position of the EventEncoderButton. More...

void	enableLongPressRepeat (bool repeat=true)
	Choose whether to repeat the long press callback. (true by default) More...

void	setLongClickDuration (uint16_t longDurationMs=750)
	Set the number of milliseconds that define the first long click duration. More...

void	setLongPressInterval (uint16_t intervalMs=500)
	Set the number of milliseconds that define the subbsequent long click intervals. More...

void	setMultiClickInterval (uint16_t intervalMs=250)
	Set the multi click interval. More...

void	setDebouncer (DebounceAdapter *debounceAdapter)
	Set the debouncer. Note: When planning to use `setDebouncer()` you must ensure `useDefaultDebouncer` is set to `false` in the button or switch constructor. Previously set debouncers are not deleted. *. More...

bool	setDebounceInterval (uint16_t intervalMs=10)
	Set the DebounceAdapter debounce interval. Default is 10ms. More...

void	setPressedState (bool state=LOW)
	Set the pin state that represents 'pressed' for the button. By default this is `LOW` (ie pulled down for pressed). More...

Public Member Functions inherited from EventInputBase
bool	isCallbackSet ()
	Returns true if the callback is set.

void	update ()
	Update the state of the input. More...

bool	isEnabled ()
	Returns true if input is enabled. More...

void	enable (bool e=true)
	Enable or disable an input. More...

void	setIdleTimeout (unsigned int timeoutMs=10000)
	Set the idle timeout in milliseconds (default 10000, 10 seconds) More...

unsigned long	msSinceLastEvent ()
	Returns the number of ms since any event was fired for this input.

bool	isIdle ()
	Return true if no activity for longer than setIdleTimeout - irrespective of whether the idle (or changed) callback has been fired. More...

void	resetIdleTimer ()
	Reset the idle timer. The IDLE event will fire setIdleTimeout ms after this is called. More...

void	blockEvent (InputEventType et)
	Stop an event from firing. More...

void	allowEvent (InputEventType et)
	Allow a a previously blocked event tto fire. More...

void	blockAllEvents ()
	Stop all events from firing - usually used in conjunction with allowEvent()

void	allowAllEvents ()
	Clear all blocked events.

bool	isEventAllowed (InputEventType et)
	Returns true if the event is not blocked.

void	setInputId (uint8_t id)
	Set the input ID (for use by user, not used internally). Not unique, default is 0.

uint8_t	getInputId ()
	Get the input ID (for use by user, not used internally). Not unique, default is 0.

void	setInputValue (uint8_t val)
	Set the input value (for use by user, not used internally). Not unique, default is 0.

uint8_t	getInputValue ()
	Get the input value (for use by user, not used internally). Not unique, default is 0.

Protected Types
typedef std::function< void(InputEventType et, EventEncoderButton &ie)>	CallbackFunction
	If `std::function` is supported, this creates the callback type.

typedef void(*	CallbackFunction) (InputEventType et, EventEncoderButton &)
	Used to create the callback type as pointer if `std::function` is not supported.

Protected Member Functions
void	invoke (InputEventType et) override
	To be overriden by derived classes. More...

void	onEnabled () override
	Can be ovrriden by derived classes but base method must be called. More...

void	onDisabled () override
	Can be ovrriden by derived classes but base method must be called. More...

void	onIdle () override
	Can be ovrriden by derived classes but base method must be called. More...

void	onInputCallback (InputEventType et, EventInputBase &ie)

Protected Member Functions inherited from EventInputBase
bool	isInvokable (InputEventType et)

virtual void	invoke (InputEventType et)=0
	To be overriden by derived classes. More...

virtual void	onEnabled ()
	Can be ovrriden by derived classes but base method must be called. More...

virtual void	onDisabled ()
	Can be ovrriden by derived classes but base method must be called. More...

virtual void	onIdle ()
	Can be ovrriden by derived classes but base method must be called. More...

Protected Attributes
CallbackFunction	callbackFunction = nullptr
	The callback function member.

EventEncoder	encoder
	the EventEncoder instance

EventButton	button
	the EventButton onstance

Protected Attributes inherited from EventInputBase
uint8_t	input_id = 0
	Input ID, not used internally.

uint8_t	input_value = 0
	Input value, not used internally.

bool	_enabled = true
	Input enabled flag.

bool	idleFlagged = true
	True if input is idle.

unsigned long	lastEventMs = millis()
	number of milliseconds since the last event

unsigned long	idleTimeout = 10000
	The idle timeout in milliseconds.

bool	callbackIsSet = false
	Required because in C/C++ callback has to be defined in derived classes... :-/.

Constructor & Destructor Documentation

◆ EventEncoderButton() [1/3]

EventEncoderButton::EventEncoderButton	(	EncoderAdapter *	encoderAdapter,
		byte	buttonPin,
		bool	useDefaultDebouncer = `true`
	)

Construct an EventEncoderButton input from an EncoderAdapter and a pin.

Please see EncoderAdapter Notes

‍Note: The EncoderAdapter's begin() method will be called from the EventEncoderButton's begin() method.

Parameters

encoderAdapter	Pass a previously created EncoderAdapter by reference.
buttonPin	The pin for the button

GPLv2 Licence https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt

◆ EventEncoderButton() [2/3]

EventEncoderButton::EventEncoderButton	(	EncoderAdapter *	encoderAdapter,
		PinAdapter *	_pinAdapter,
		bool	useDefaultDebouncer = `true`
	)

Construct a new EventButton with a PinAdapter and optionally use the default debouncer.

Parameters

encoderAdapter	Pass a previously created EncoderAdapter by reference.
pinAdapter

◆ EventEncoderButton() [3/3]

EventEncoderButton::EventEncoderButton	(	EncoderAdapter *	encoderAdapter,
		PinAdapter *	_pinAdapter,
		DebounceAdapter *	debounceAdapter
	)

Construct a new EventButton with a PinAdapter and a DebounceAdapter.

Parameters

encoderAdapter	Pass a previously created EncoderAdapter by reference.
pinAdapter
debounceAdapter

Member Function Documentation

◆ begin()

void EventEncoderButton::begin ( )

virtual

Initialise the EventEncoderButton.

Must be called from within setup()

Implements EventInputBase.

◆ clickCount()

unsigned char EventEncoderButton::clickCount ( )

The number of clicks that have been fired in the MULTI_CLICKED event.

This is also set do CLICK and DOUBLE_CLICKED and is reset to zero after any CLICKED event is fired.

Returns: uint8_t Number of clicks

◆ currentDuration()

uint32_t EventEncoderButton::currentDuration ( )

Duration in milliseconds of the current button state.

Returns: Current state duration in milliseconds

◆ enableLongPressRepeat()

void EventEncoderButton::enableLongPressRepeat ( bool repeat = true )

Choose whether to repeat the long press callback. (true by default)

Parameters

repeat Pass true to repeat, false to not repeat.

◆ getPositionDivider()

uint8_t EventEncoderButton::getPositionDivider ( )

Get the currently set position divider value.

Returns: uint8_t

◆ increment()

int16_t EventEncoderButton::increment ( )

inline

Returns a positive (CW) or negative (CCW) integer.

The returned value normally 1 or -1 but if your loop() has lots of processing, your Arduino is slow or you setRateLimit() this will report the actual number of increments made by the encoder since the update().

◆ invoke()

void EventEncoderButton::invoke ( InputEventType et )

overrideprotectedvirtual

To be overriden by derived classes.

Parameters

et	Enum of type `InputEventType`

Implements EventInputBase.

◆ longPressCount()

uint8_t EventEncoderButton::longPressCount ( )

The number of times the long press has occurred during a button press.

This is oncremented even if the setLongPressRepeat is false, so can be read in the LONC_CLICKED event. This is reset to zero after LONG_CLICKED is fired.

Returns: uint8_t A count of long press occurences

◆ onDisabled()

void EventEncoderButton::onDisabled ( )

overrideprotectedvirtual

Can be ovrriden by derived classes but base method must be called.

Reimplemented from EventInputBase.

◆ onEnabled()

void EventEncoderButton::onEnabled ( )

overrideprotectedvirtual

Can be ovrriden by derived classes but base method must be called.

Reimplemented from EventInputBase.

◆ onIdle()

void EventEncoderButton::onIdle ( )

inlineoverrideprotectedvirtual

Can be ovrriden by derived classes but base method must be called.

Reimplemented from EventInputBase.

◆ onInputCallback()

void EventEncoderButton::onInputCallback	(	InputEventType	et,
		EventInputBase &	ie
	)

protected

Convert the encoder & button callbacks to a EventEncoderButton callbacks

◆ previousDuration()

uint32_t EventEncoderButton::previousDuration ( )

Duration in milliseconds of the previous button state.

Returns: Previous state duration in milliseconds

◆ resetPosition()

void EventEncoderButton::resetPosition ( int32_t pos = 0 )

inline

Reset the counted position of the EventEncoderButton.

Note: This does not reset the position on the underlying encoder libraries may only allow a 'reset' to 0, not the setting of a specific value.

It also does not check if the passed position is within any min/max limits you may have set.

◆ resetPressedPosition()

void EventEncoderButton::resetPressedPosition ( int32_t pos )

inline

Reset the counted pressed position of the EventEncoderButton.

Note: This only resets the EventEncoderButton pressedPosition, it does not change the underlying encoder library position.

It also does not check if the passed position is within any min/max limits you may have set.

◆ setCallback() [1/2]

void EventEncoderButton::setCallback ( CallbackFunction f )

inline

Set the Callback function.

Parameters

f	A function of type `EventEncoderButton::CallbackFunction` type.

◆ setCallback() [2/2]

template<typename T >

void EventEncoderButton::setCallback	(	T *	instance,
		void(T::*)(InputEventType, EventEncoderButton &)	method
	)

inline

Set the Callback function to a class method.

Note: This method is only available if std:function is supported.

Parameters

instance	The instance of a class implementing a CallbackFunction method.
method	The class method of type `EventEncoderButton::CallbackFunction` type.

◆ setDebounceInterval()

bool EventEncoderButton::setDebounceInterval ( uint16_t intervalMs = 10 )

Set the DebounceAdapter debounce interval. Default is 10ms.

Returns: true If the debounce interval has been updated; false If the debouncer interval has not been updated (ie no debouncer set)

◆ setDebouncer()

void EventEncoderButton::setDebouncer ( DebounceAdapter * debounceAdapter )

Set the debouncer. Note: When planning to use setDebouncer() you must ensure useDefaultDebouncer is set to false in the button or switch constructor. Previously set debouncers are not deleted. *.

Parameters

debounceAdapter

◆ setLongClickDuration()

void EventEncoderButton::setLongClickDuration ( uint16_t longDurationMs = 750 )

Set the number of milliseconds that define the first long click duration.

The LONG_PRESS event will fire after this duration, then repeat at the interval setLongPressInterval(ms) (default 500ms) if enableLongPressRepeat() is true. After the button is released, a LONG_CLICK event will fire.

Parameters

longDurationMs Default 750ms

◆ setLongPressInterval()

void EventEncoderButton::setLongPressInterval ( uint16_t intervalMs = 500 )

Set the number of milliseconds that define the subbsequent long click intervals.

If enableLongPressRepeat() is true a LONG_PRESS event will fire every intervalMs after the first LONG_PRESS has fired.

Parameters

intervalMs The interval in milliseconds (default is 500ms).

◆ setMaxPosition()

void EventEncoderButton::setMaxPosition ( int32_t maxPosition = 0 )

Set an upper limit for the encoder position.

If position() is higher than the passed value, then it will be set to maxPosition.

Parameters

maxPosition The highest position required

◆ setMaxPressedPosition()

void EventEncoderButton::setMaxPressedPosition ( int32_t maxPressedPosition = 0 )

Set an upper limit for the encoder pressed position.

If either setMinPressedPosition() or setMaxPressedPosition() are non zero, the limits will be applied.

If wrapMinMaxPressedPosition() is set to true, the pressedPosition() will be wrapped from max to min or min to max.

Parameters

maxPressedPosition The highest pressed position required

◆ setMinPosition()

void EventEncoderButton::setMinPosition ( int32_t minPosition = 0 )

Set a lower limit for the encoder position.

If position() is lower than the passed value, then it will be set to minPosition.

Parameters

minPosition The lowest position required

◆ setMinPressedPosition()

void EventEncoderButton::setMinPressedPosition ( int32_t minPressedPosition = 0 )

Set a lower limit for the encoder pressed position.

If pressedPosition() is higher than the passed value, then it will be set to maxPressedPosition.

Parameters

minPressedPosition The lowest pressed position required

◆ setMultiClickInterval()

void EventEncoderButton::setMultiClickInterval ( uint16_t intervalMs = 250 )

Set the multi click interval.

Parameters

intervalMs The interval in milliseconds between double, triple or multi clicks

◆ setPositionDivider()

void EventEncoderButton::setPositionDivider ( uint8_t divider = 4 )

Quadrature encoders usually have four states for each 'click' of the rotary control, although some have just 2.

Normally we only want to fire an event once per click so the default positionDivider is 4. You can set this to any positive integer eg 8 would increment the position every 2 clicks. Affects pressed+turning too.

◆ setPressedState()

void EventEncoderButton::setPressedState ( bool state = LOW )

Set the pin state that represents 'pressed' for the button. By default this is LOW (ie pulled down for pressed).

If you set this value to HIGH, you must also pass INPUT_PULLDOWN to the GpioPinAdapter constructor.

If your board does not support INPUT_PULLDOWN, pass INPUT and use an external resistor.

Parameters

state Either LOW (default) or HIGH

◆ setRateLimit()

void EventEncoderButton::setRateLimit ( long ms )

Encoder callbacks are normally fired on every loop() but for MPG style encoders this can fire a huge number of events (that may swamp a serial connection).

The encoder interupts will sitll be called but this will limit the call back firing to every set ms - read the EncoderButton.increment() for lossless counting of encoder. Set to zero (default) for no rate limit.

Parameters

ms	Number of milliseconds between each update()

◆ unsetCallback()

void EventEncoderButton::unsetCallback ( )

overridevirtual

Unset a previously set callback function or method.

Must be called before the set function or method is destoyed.

Reimplemented from EventInputBase.

◆ update()

void EventEncoderButton::update ( )

Update the state from the underlying encoder library and button pin.

Must be called from within loop()

◆ wrapMinMaxPosition()

void EventEncoderButton::wrapMinMaxPosition ( bool wrap )

inline

Wrap the max -> min -> max ... (default is to not wrap)

If pressedPosition() is lower than the passed value, then it will be set to minPressedPosition.

Parameters

wrap	Pass true to wrap and false for default behaviour.

◆ wrapMinMaxPressedPosition()

void EventEncoderButton::wrapMinMaxPressedPosition ( bool wrap )

inline

Wrap the max -> min -> max ... (default is to not wrap)

If wrapMinMaxPressedPosition() is set to false (the default), the pressedPosition() will be stopped at the min or max limit.

If wrapMinMaxPressedPosition() is set to true, the pressedPosition() will be wrapped from max -> min -> max ...

Parameters

wrap	Pass true to wrap and false for default behaviour.

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

src/EventEncoderButton.h
src/EventEncoderButton.cpp

Description

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ EventEncoderButton() [1/3]

◆ EventEncoderButton() [2/3]

◆ EventEncoderButton() [3/3]

Member Function Documentation

◆ begin()

◆ clickCount()

◆ currentDuration()

◆ enableLongPressRepeat()

◆ getPositionDivider()

◆ increment()

◆ invoke()

◆ longPressCount()

◆ onDisabled()

◆ onEnabled()

◆ onIdle()

◆ onInputCallback()

◆ previousDuration()

◆ resetPosition()

◆ resetPressedPosition()

◆ setCallback() [1/2]

◆ setCallback() [2/2]

◆ setDebounceInterval()

◆ setDebouncer()

◆ setLongClickDuration()

◆ setLongPressInterval()

◆ setMaxPosition()

◆ setMaxPressedPosition()

◆ setMinPosition()

◆ setMinPressedPosition()

◆ setMultiClickInterval()

◆ setPositionDivider()

◆ setPressedState()

◆ setRateLimit()

◆ unsetCallback()

◆ update()

◆ wrapMinMaxPosition()

◆ wrapMinMaxPressedPosition()