Reference Manual - TanPitch/ButtonKing GitHub Wiki

ButtonKing reference

*Strikeout functions were avilable in version older than 1.0.2

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.

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);

setTimeCount

*This function can use in version newer than 1.0.2

  • C++/Arduino Prototype:
void ButtonKing::setTimeCount(int ticks)

  • Description: To adjust the limit time (in milliseconds). The time that have to pass by before program finished counting pressing 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 : Limiting time in milliseconds.

  • Example:

button.setTimeCount(500);

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 setDoubleClick 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.setDoubleClick(DoubleClick); //when button1 was double-click will go to DoubleClick function

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

setDoublePress

*This function can use in version newer than 1.0.2

  • C++/Arduino Prototype:
void ButtonKing::setDoublePress(callbackFunction newFunction)

  • Description: call out function when button was click and then pressed. The setDoublePress 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.setDoublePress(DoublePress); //when button1 was click and then pressed will go to DoublePress function

void DoublePress () { // DoublePress function
  Serial.println("Button was Double Pressed.");
}

setTripleClick

*This function can use in version newer than 1.0.2

  • C++/Arduino Prototype:
void ButtonKing::setTripleClick(callbackFunction newFunction)

  • Description: call out function when button was triple-click. The setTripleClick 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.setTripleClick(TripleClcik); //when button1 was triple-click will go to TripleClick function

void TripleClick () { // TripleClick function
  Serial.println("Button was triple-click.");
}

setTriplePress

*This function can use in version newer than 1.0.2

  • C++/Arduino Prototype:
void ButtonKing::setTriplePress(callbackFunction newFunction)

  • Description: call out function when button was double click and then pressed. The setTriplePress 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.setTriplePress(TriplePress); //when button1 was double click and then pressed will go to TriplePress function

void TriplePress () { // TriplePress function
  Serial.println("Button was Triple Pressed.");
}

setPress

  • C++/Arduino Prototype:
void ButtonKing::setPress(callbackFunction newFunction)

  • Description: call out function when button was start pressing. The setPress 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) This function was the same as setShortClickStart or setLongClickStart in older version.

  • Arguments:

  • Example:

button.setPress(Press); //when button1 was start pressing will go to Press function

void Press() { // Press function
  Serial.println("Button was start pressing.");
}

setRelease

  • C++/Arduino Prototype:
void ButtonKing::setRelease(callbackFunction newFunction)

  • Description: call out function when button was stop pressing. The setReleaserequire 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) This function was the same as setLongClickStop in older version.

  • Arguments:

  • Example:

button.setRelease(Release); //when button1 was stop pressing will go to Release function

void Release() { // Press function
  Serial.println("Button was stop pressing.");
}

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 long period will go to startLongPress function

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

setLongClickStop

  • C++/Arduino Prototype:
void ButtonKing::setLongClickStop(callbackFunction newFunction)

  • Description: call out function when button was released from long press. The setLongClickStop 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.setLongClickStop(stopLongPress); //when button1 was released from long-press will go to stopLongPress function

void stopLongPress () { // stopLongPress function
  Serial.println("Button was release from the long-press.");
}

setShortDoubleStart

  • C++/Arduino Prototype:
void ButtonKing::setShortDoubleStart(callbackFunction newFunction)

  • Description: call out function when button was long pressed with a short period after first click. To adjust the time before button called "Double Short Press" by adjust the debounce time. The ShortDoubleStart 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.setShortDoubleStart(ShortDoubleStart); //when button was long-pressed for a short period after first click will go to ShortDoubleStart function

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

setLongDoubleStart

  • C++/Arduino Prototype:
void ButtonKing::setLongDoubleStart(callbackFunction newFunction)

  • Description: call out function when button was long pressed with a long period after first click.To adjust the time before button called "Double 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.setLongDoubleStart(setLongDoubleStart); //when button was long-pressed for a long period  after first click will go to setLongDoubleStart function

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

setLongDoubleStop

  • C++/Arduino Prototype:
void ButtonKing::setLongDoubleStop(callbackFunction newFunction)

  • Description: call out function when button was released from long press. The setLongDoubleStop 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.setLongDoubleStop(LongDoubleStop); //when button was released from double long-press will go to LongDoubleStop function

void LongDoubleStop() { // LongDoubleStop function
  Serial.println("Button was release from the double long-press.");
}

getPressedTimer

  • C++/Arduino Prototype:
void ButtonKing::getPressedTimer()

  • Description: call out function when button was released from long press. telling how long does the button was pressed. Before you use this function, you have to add button (using ButtonKing function)

  • Arguments:

  • Example:

Serial.println( button.getPressedTimer() ); //when button was released, this function will tell how long button was pressed