Reference Manual

ButtonKing reference

• hello World
• first Call
  • ButtonKing
• Setting the ButtonKing
  • setTimeDebounce
  • setTimeShort
  • setTimeLong
  • setTimeDouble
• Using the ButtonKing
  • setClick
  • setDoubleClick
  • setShortClickStart
  • setLongClickStart

hello_World

The ButtonKing library is the improved version of the OneButton that use to add more events to a single pushbutton. It shows how to use an digital input pin with a single pushbutton attached for detecting some of the typical button press events. This enables you to reuse the same button for multiple functions and lowers the hardware invests.

These're all events that ButtonKing can detect.

Events	OneButton	ButtonKing
single click	✔️	✔️
double clicks	✔️	✔️
short-time pressing	✔️	✔️
long-time pressing	✖️	✔️
long-time releasing	✔️	✔️
is button pressing	✔️	✖️
duration from press to release	✔️	✖️
short-time pressing after single click	✖️	✔️
long-time pressing after single click	✖️	✔️
long-time releasing after single click	✖️	✔️
triple click	✖️	✖️

• is button pressing can detect long-time came before
• duration from press to release can calculate by long-time releasing minus short-time pressing
• triple click can detect by double click and then single click

for the first time you use this library, here's the sample code

#include "ButtonKing.h"

ButtonKing button(A1, true);

void setup() {
  pinMode(13, OUTPUT);      // sets the digital pin as output
  button.setClick(myClickFunction); // link the myClickFunction function to be called on a click event.
}

void loop() {
  button.isClick();
}

void myClickFunction() {
  digitalWrite(13, HIGH);
}

for more example, go to example folder.

first_Call

ButtonKing

• C++/Arduino Prototype:

void ButtonKing::ButtonKing(int pin, int activeLow, bool pullupActive)

• Description: To add a button to the library, you have to use this function before using other functions. You can add buttons as much as you can.

• Arguments:

  • ButtonKing : Pointer to the ButtonKing structure (C interface only).
  • activeLow : Set button stage when the button pressed.
    • LOW : the button connects the input pin to GND when pressed.
    • HIGH : the button connects the input pin to VCC when pressed.
  • pullupActive : use the given pin as input and activate internal PULLUP resistor.
    • true : use the given pin as input and activate internal PULLUP resistor.
    • false : use the given pin as input

• Example:

ButtonKing button1(A1);
ButtonKing button1(A1, true);
ButtonKing button1(A1, LOW, true);

Setting_the_ButtonKing

setTimeDebounce

• C++/Arduino Prototype:

void ButtonKing::setTimeDebounce(int ticks)

• Description: To adjust the debounce time (in milliseconds). The time that have to pass by before program reads the button status again. Avoid the bouncing effect (button's contact bouncing) in mechanical button. Before you use this function, you have to add button (using ButtonKing function)

• Arguments:

  • ButtonKing : Pointer to the ButtonKing structure (C interface only).
  • ticks : Button debouncing time in milliseconds.

• Example:

button.setTimeDebounce(80);

setTimeShort

• C++/Arduino Prototype:

void ButtonKing::setTimeShort(int ticks)

• Description: To adjust the waiting time (in milliseconds) before button has "Short Pressing" stage. You can call out the short pressing stage by using setShortClickStart function. Before you use this function, you have to add button (using ButtonKing function)

• Arguments:

  • ButtonKing : Pointer to the ButtonKing structure (C interface only).
  • ticks : time in milliseconds to wait for being Short Pressing status.

• Example:

button.setTimeShort(500);

setTimeLong

• C++/Arduino Prototype:

void ButtonKing::setTimeLong(int ticks)

• Description: To adjust the waiting time (in milliseconds) before button has "Long Pressing" stage. You can call out the long pressing stage by using setLongClickStart function. The setLongClickStart will call out as many time as button stay in long pressing status. For more detail, setLongClickStart. Before you use this function, you have to add button (using ButtonKing function)

• Arguments:

  • ButtonKing : Pointer to the ButtonKing structure (C interface only).
  • ticks : time in milliseconds to wait for being Long Pressing status.

• Example:

button.setTimeLong(500);

setTimeDouble

• C++/Arduino Prototype:

void ButtonKing::setTimeDouble(int ticks)

• Description: To adjust the waiting time (in milliseconds) before button has "Double Click" stage. You can call out the double press stage by using setDoubleClick function. The setDoubleClick will call out even if button had pressed for more that 2 times. For more detail, setDoubleClick. Before you use this function, you have to add button (using ButtonKing function)

• Arguments:

  • ButtonKing : Pointer to the ButtonKing structure (C interface only).
  • ticks : time in milliseconds to wait for being Long Pressing status.

• Example:

button.setTimeDouble(500);

Using_the_ButtonKing

setClick

• C++/Arduino Prototype:

void ButtonKing::setClick(callbackFunction newFunction)

• Description: call out function when button was single press and no long press. To adjust the time before button called "Click" by adjust the debounce time and time before getting Short press stage. The setClick function require new custom function to complete task. For more detail, see Example below or go to Example folder. Before you use this function, you have to add button (using ButtonKing function)

• Arguments:

• Example:

button.setClick(click); //when button1 was click will go to click function

void click() { // click funciton
  Serial.println("Button click.");
}

setDoubleClick

• C++/Arduino Prototype:

void ButtonKing::setDoubleClick(callbackFunction newFunction)

• Description: call out function when button was double press and no long press. To adjust the time before button called "Double Click" by adjust the debounce time and time before getting Double press stage. The setDoubleClickfunction require new custom function to complete task. For more detail, see Example below or go to Example folder. Before you use this function, you have to add button (using ButtonKing function)

• Arguments:

• Example:

button.setDoubleClick(DoubleClick); //when button1 was double-click will go to DoubleClick function

void DoubleClick() { // DoubleClick funciton
  Serial.println("Button double-click.");
}

setShortClickStart

• C++/Arduino Prototype:

void ButtonKing::setShortClickStart(callbackFunction newFunction)

• Description: call out function when button was long press with a short period. To adjust the time before button called "Short Press" by adjust the debounce time. The setShortClickStart require new custom function to complete task. For more detail, see Example below or go to Example folder. Before you use this function, you have to add button (using ButtonKing function)

• Arguments:

• Example:

button.setShortClickStart(startShortPress); //when button1 was long-press for a short period will go to startShortPress function

void startShortPress () { // startShortPress function
  Serial.println("Button was start the short-press.");
}

setLongClickStart

• C++/Arduino Prototype:

void ButtonKing::setLongClickStart(callbackFunction newFunction)

• Description: call out function when button was long press with a long period. To adjust the time before button called "Long Press" by adjust the debounce time and time before getting Short press stage.The setLongClickStart will call out as many time as button stay in long pressing status. The setLongClickStart require new custom function to complete task. For more detail, see Example below or go to Example folder. Before you use this function, you have to add button (using ButtonKing function)

• Arguments:

• Example:

button.setLongClickStart(startLongPress); //when button1 was long-press for a short period will go to startLongPress function

void startLongPress() { // startLongPress function
  Serial.println("Button was start the long-press.");
}