Add ToggleButton derived class.

Author: JChristensen

README.md

@@ -3,7 +3,7 @@ https://github.com/JChristensen/JC_Button
 README file  
 
 ## License
-Arduino Button Library Copyright (C) 2018 Jack Christensen GNU GPL v3.0
+Arduino Button Library Copyright (C) 2018-2019 Jack Christensen GNU GPL v3.0
 
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License v3.0 as published by the Free Software Foundation.
 
@@ -16,14 +16,18 @@ The Button library is for debouncing and reading momentary contact switches like
 
 The simplest way to use a button with an AVR microcontroller is to wire the button between a GPIO pin and ground, and turn on the AVR internal pullup resistor. The Button class constructor takes four arguments, but three have default values that work for a button wired in this manner.
 
+A derived class, ToggleButton, implements button objects that need only "push-on, push-off" functionality.
+
 ## Examples
 The following example sketches are included with the **Button** library:
 
 - **SimpleOnOff**: Just turns the Arduino's pin 13 LED on and off.
 - **LongPress**: Demonstrates detecting long and short button presses.
 - **UpDown**: Counts up or down, one number at a time or rapidly by holding the button down.
+- **Toggle**: Demonstrates ToggleButton functionality.
+
 
-## Constructor
+## Constructors
 
 ### Button(pin, dbTime, puEnable, invert)
 ##### Description
@@ -50,7 +54,38 @@ Button myButton(3, 50);
 Button myButton(4, 25, false, false);
 
 ```
-## Library Functions
+
+### ToggleButton(pin, initialState, dbTime, puEnable, invert)
+##### Description
+The constructor defines a toggle button object, which has "push-on, push-off" functionality. The initial state can be on or off. See the section, [ToggleButton Library Functions](https://github.com/JChristensen/JC_Button#togglebutton-library-functions) for functions that apply specifically to the ToggleButton object. The ToggleButton class is derived from the Button class, so all Button functions are available, but because it is inherently a more limited concept, the special ToggleButton functions will be most useful, along with `begin()` and `read()`.
+##### Syntax
+`ToggleButton(pin, initialState, dbTime, puEnable, invert);`
+##### Required parameter
+**pin:** Arduino pin number that the button is connected to *(byte)*  
+##### Optional parameters
+**initialState:** Initial state for the button. Defaults to off (false) if not given. *(bool)*  
+**dbTime:** Debounce time in milliseconds. Defaults to 25ms if not given. *(unsigned long)*  
+**puEnable:** *true* to enable the microcontroller's internal pull-up resistor, else *false*. Defaults to *true* if not given. *(bool)*  
+**invert:** *false* interprets a high logic level to mean the button is pressed, *true* interprets a low level as pressed. *true* should be used when a pull-up resistor is employed, *false* for a pull-down resistor. Defaults to *true* if not given. *(bool)*
+##### Returns
+None.
+##### Example
+```c++
+// button connected from pin 2 to ground, initial state off,
+// 25ms debounce, pullup enabled, logic inverted
+ToggleButton myToggle(2);
+
+// same as above but this button is initially "on" and also
+// needs a longer debounce time (50ms).
+ToggleButton myToggle(3, true, 50);
+
+// a button wired from the MCU pin to Vcc with an external pull-down resistor,
+// initial state is off.
+Button myButton(4, false, 25, false, false);
+
+```
+
+## Button Library Functions
 
 ### begin()
 ##### Description
@@ -73,7 +108,7 @@ Reads the button and returns a *boolean* value (*true* or *false*) to indicate w
 ##### Parameters
 None.
 ##### Returns
-*true* if the button is pressed, *else* false *(bool)*
+*true* if the button is pressed, else *false* *(bool)*
 ##### Example
 ```c++
 myButton.read();
@@ -153,3 +188,47 @@ The time in milliseconds when the button last changed state *(unsigned long)*
 ```c++
 unsigned long msLastChange = myButton.lastChange();
 ```
+
+## ToggleButton Library Functions
+
+### changed()
+##### Description
+Returns a boolean value (true or false) to indicate whether the toggle button changed state the last time `read()` was called.
+##### Syntax
+`myToggle.changed();`
+##### Parameters
+None.
+##### Returns
+*true* if the toggle state changed, else *false* *(bool)*
+##### Example
+```c++
+if (myToggle.changed())
+{
+    // do something
+}
+else
+{
+    // do something different
+}
+```
+
+### toggleState()
+##### Description
+Returns a boolean value (true or false) to indicate the toggle button state as of the last time `read()` was called.
+##### Syntax
+`myToggle.toggleState();`
+##### Parameters
+None.
+##### Returns
+*true* if the toggle is "on", else *false* *(bool)*
+##### Example
+```c++
+if (myToggle.toggleState())
+{
+    // do something
+}
+else
+{
+    // do something different
+}
+```

examples/Toggle/Toggle.ino

@@ -0,0 +1,45 @@
+// Arduino Button Library
+// https://github.com/JChristensen/JC_Button
+// Copyright (C) 2018 by Jack Christensen and licensed under
+// GNU GPL v3.0, https://www.gnu.org/licenses/gpl.html
+//
+// Example sketch to demonstrate toggle buttons.
+
+#include <JC_Button.h>          // https://github.com/JChristensen/JC_Button
+
+// pin assignments
+const byte
+    LED1_PIN(5),                // connect an LED to ground, through an appropriate current limiting resistor
+    LED2_PIN(6),                // connect an LED to ground, through an appropriate current limiting resistor
+    BUTTON1_PIN(7),             // connect a button switch from this pin to ground
+    BUTTON2_PIN(8);             // connect a button switch from this pin to ground
+
+ToggleButton                    // define the buttons
+    btn1(BUTTON1_PIN),          // this button's initial state is off
+    btn2(BUTTON2_PIN, true);    // this button's initial state is on
+
+void setup()
+{
+    // initialize the button objects
+    btn1.begin();
+    btn2.begin();
+
+    // set the LED pins as outputs
+    pinMode(LED1_PIN, OUTPUT);
+    pinMode(LED2_PIN, OUTPUT);
+
+    // show the initial states
+    digitalWrite(LED1_PIN, btn1.toggleState());
+    digitalWrite(LED2_PIN, btn2.toggleState());
+}
+
+void loop()
+{
+    // read the buttons
+    btn1.read();
+    btn2.read();
+
+    // if button state changed, update the LEDs
+    if (btn1.changed()) digitalWrite(LED1_PIN, btn1.toggleState());
+    if (btn2.changed()) digitalWrite(LED2_PIN, btn2.toggleState());
+}

keywords.txt

@@ -1,4 +1,5 @@
 Button	KEYWORD1
+ToggleButton	KEYWORD1
 begin	KEYWORD2
 read	KEYWORD2
 isPressed	KEYWORD2
@@ -8,3 +9,5 @@ wasReleased	KEYWORD2
 pressedFor	KEYWORD2
 releasedFor	KEYWORD2
 lastChange	KEYWORD2
+changed	KEYWORD2
+toggleState	KEYWORD2

library.properties

@@ -1,9 +1,9 @@
 name=JC_Button
-version=2.0.1
+version=2.1.0
 author=Jack Christensen <jack.christensen@outlook.com>
 maintainer=Jack Christensen <jack.christensen@outlook.com>
 sentence=Arduino library to debounce button switches, detect presses, releases, and long presses.
-paragraph=The Button library is for debouncing and reading momentary contact switches like tactile button switches. "Long presses" of arbitrary length can be detected. Works well in state machine constructs. Use the read() function to read each button in the main loop, which should execute as fast as possible.
+paragraph=Copyright (C) 2018-2019 by Jack Christensen and licensed under GNU GPL v3.0.
 category=Signal Input/Output
 url=https://github.com/JChristensen/JC_Button
 architectures=avr

src/JC_Button.h

@@ -70,4 +70,42 @@ class Button
         uint32_t m_time;        // time of current state (ms from millis)
         uint32_t m_lastChange;  // time of last state change (ms)
 };
+
+// a derived class for a "push-on, push-off" (toggle) type button.
+// initial state can be given, default is off (false).
+class ToggleButton : public Button
+{
+    public:
+    
+        // constructor is similar to Button, but includes the initial state for the toggle.
+        ToggleButton(uint8_t pin, bool initialState=false, uint32_t dbTime=25, uint8_t puEnable=true, uint8_t invert=true)
+            : Button(pin, dbTime, puEnable, invert), m_toggleState(initialState) {}
+
+        // read the button and return its state.
+        // should be called frequently.
+        bool read()
+        {
+            Button::read();
+            if (wasPressed())
+            {
+                m_toggleState = !m_toggleState;
+                m_changed = true;
+            }
+            else
+            {
+                m_changed = false;
+            }
+            return m_toggleState;
+        }
+
+        // has the state changed?
+        bool changed() {return m_changed;}
+
+        // return the current state
+        bool toggleState() {return m_toggleState;}
+
+    private:
+        bool m_toggleState;
+        bool m_changed;
+};
 #endif