# r89m Buttons This library makes working with buttons easy. Easily handle button events such as ```onPress```, ```onHold```, ```onHoldRepeat``` and ```onRelease```. The same callback functions can be used with multiple buttons, helping to keep your code cleaner and more manageable. Swap button types whenever you want - there's currently 3 supported types - [```PushButton```](https://github.com/r89m/PushButton), [```CapacitiveButton```](https://github.com/r89m/CapacitiveButton) and [```MPR121Button```](https://github.com/r89m/MPR121Button) but it is easy to create your own. ## Examples Here's some basic examples to show you just how easy using this library is! ```c++ #include #include #include // Create an instance of BasicButton reading digital pin 5 BasicButton button = BasicButton(5); void setup(){ // When the button is first pressed, call the function onButtonPressed button.onPress(onButtonPressed); } void loop(){ // Check the state of the button button.update(); } void onButtonPressed(Button& btn){ // The button was pressed - do something! } ``` ```c++ #include #include #include // Create an instance of BasicButton reading digital pin 5 BasicButton button = BasicButton(5); void setup(){ // Open up the serial port so that we can write to it Serial.begin(9600); // When the button is first pressed, call the function onButtonPressed button.onPress(onButtonPressed); // Once the button has been held for 1 second (1000ms) call onButtonHeld. Call it again every 0.5s (500ms) until it is let go button.onHoldRepeat(1000, 500, onButtonHeld); // When the button is released, call onButtonReleased button.onRelease(onButtonReleased); } void loop(){ // Check the state of the button button.update(); } // btn is a reference to the button that fired the event. That means you can use the same event handler for many buttons void onButtonPressed(Button& btn){ Serial.println("button pressed"); } // duration reports back how long it has been since the button was originally pressed. // repeatCount tells us how many times this function has been called by this button. void onButtonHeld(Button& btn, uint16_t duration, uint16_t repeatCount){ Serial.print("button has been held for "); Serial.print(duration); Serial.print(" ms; this event has been fired "); Serial.print(repeatCount); Serial.println(" times"); } // duration reports back the total time that the button was held down void onButtonReleased(Button& btn, uint16_t duration){ Serial.print("button released after "); Serial.print(duration); Serial.println(" ms"); } ``` ## Built-in Button Types ### [PushButton](https://github.com/r89m/PushButton) A simple push button debounced using the Bounce library Check out the [examples!](https://github.com/r89m/PushButton/tree/master/examples) ### [CapacitiveButton](https://github.com/r89m/CapacitiveButton) A capacitive touch button utilising the CapSense library Check out the [examples!](https://github.com/r89m/CapacitiveButton/tree/master/examples) ### [MPR121Button](https://github.com/r89m/MPR121Button) A capacitive touch button utilising the MPR121 touch switch IC Check out the [examples!](https://github.com/r89m/MPR121Button/tree/master/examples) ### BasicButton (not recommended!) A simple button using digitalRead() to determine the state of the button. Does not perform any kind of debouncing, so false positives and multiple calls are likely. Use PushButton instead for a simple button. This is only included so that you can get an example up-and-running quickly without needing any other dependencies. ## Methods ### ```boolean update()``` Update the button state - this will call any callbacks that are necessary. Returns ```true``` if the state changes. ### ```boolean is(Button& btn)``` Return whether or not the button is the same as the ```btn``` passed ### ```boolean isPressed()``` Return whether or not the button is currently pressed. ## Callbacks ### ```CallbackAttachedResponse onPress(onPressCallbackFunction)``` ```onPressCallbackFunction``` is a function which will be called as soon as the button is pressed. It must be defined with the parameters shown below ```c++ void callThisFunctionOnPress(Button& btn){ // btn is a reference to the button that was pressed. } ``` ### ```CallbackAttachedResponse onRelease``` There are 3 variations of onRelease: #### ```CallbackAttachedResponse onRelease(onReleaseCallbackFunction)``` ```onReleaseCallbackFunction``` is a function which is called when the button is released. It must be defined with the parameters shown below ```c++ void callThisFunctionOnRelease(Button& btn, uint_16t duration){ // btn is a reference to the button that was pressed // duration is how long the button was pressed for } ``` #### ```CallbackAttachedResponse onRelease(uint_16t wait, onReleaseCallbackFunction)``` As above, plus: ```wait``` if the button is held for at-least ```wait```ms ```onReleaseCallbackFunction``` will be called. #### ```CallbackAttachedResponse onRelease(uint_16t wait, uint_16t max_wait, onReleaseCallbackFunction)``` As above, plus: ```max_wait``` if the button is held for more than ```max_wait```ms ```onReleaseCallbackFunction``` will not be called. ### ```CallbackAttachedResponse onHold(uint_16t duration, onHoldCallbackFunction)``` ```duration``` how long the button must be held before ```onHoldCallbackFunction``` is called. ```onHoldCallbackFunction``` is a function which is called when the button is held. It must be defined with the parameters shown below ```c++ void callThisFuntionOnHold(Button& btn, uint_16t duration){ // btn is a reference to the button that was held // duration is how long the button was held for } ``` ### ```CallbackAttachedResponse onHoldAndRepeat(uint_16t duration, uint_16t repeat_every, onHoldAndRepeatCallbackFunction)``` ```duration``` how long the button must be held before ```onHoldAndRepeatCallbackFunction``` is called. ```repeat_every``` how long to wait before ```onHoldAndRepeatCallbackFunction``` is called repeatedly. ```onHoldAndRepeatCallbackFunction``` is a function which is called repeatedly when the button is held. It must be defined with the parameters shown below ```c++ void callThisFunctionOnHoldAndRepeat(Button& btn, uint16_t duration, uint8_t repeat_count){ // btn is a reference to the button that was held // duration is how long the button has been held for // repeat_count is the number of times the callback has been called } ``` ## Enums ### ```CallbackAttachedResponse``` ```attSuccessful``` returned when a callback has successfully been attached ```attNoMoreRoom``` returned when a callback could not be attached because there is not enough room. Check ```MAX_CALLBACKS_PER_BUTTON```. ## Constants ### ```MAX_CALLBACKS_PER_BUTTON (default=3)``` Defines the maximum number of callbacks per button. Increasing this number will allow more callbacks but will use marginally more memory and processing power. This can be changed on a sketch by sketch basis, simply define ```#MAX_CALLBACKS_PER_BUTTON``` before your ```#include```s.