Skip to content

Keyboard

The keyboard is an input element and displays a keyboard with multiple columns and lines.

Configure

Ensure the GUI library is included and initialised according to the configuration procedure.

item myKey = setItem(0x0011, "11");

Each key of the keyboard is defined by an item, with a label 11 to display and an index 0x0011 to return.

// Three lines of four rows
item myKeys[] =
{
    {0x0011, "11"}, {0x0021, "21"}, {0x0031, "31"}, {0x0041, "41"}, // first line
    {0x0012, "12"}, {0x0022, "22"}, {0x0032, "32"}, {0x0042, "42"}, // second line
    {0x0013, "13"}, {0x0023, "23"}, {0x0033, "33"}, {0x0043, "43"} // third line
};

myKeys is the array of those items. The number of items should match the size of the keyboard.

Alternatively,

// Three lines of four rows
item myKeys[] =
{
    setItem(0x0011, "11"), setItem(0x0021, "21"), setItem(0x0031, "31"), setItem(0x0041, "41"), // first line
    setItem(0x0012, "12"), setItem(0x0022, "22"), setItem(0x0032, "32"), setItem(0x0042, "42"), // second line
    setItem(0x0013, "13"), setItem(0x0023, "23"), setItem(0x0033, "33"), setItem(0x0043, "43") // third line
};
The array can be set dynamically with setItem().

keyboard myKeyboard;

The constructor creates a keyboard.

1
2
3
4
myKeyboard.dDefine(dx / 2, dy, dx * 4, dy * 4, 
    myKeys,
    4, 3,
    fontSizeAutomatic);

dDefine() defines the keyboard with vector coordinates.

The required parameters are

  • The first line specifies the vector coordinates: top-left coordinates x-y then width and height in pixels.

  • The second line specifies the keys, defined as an array of items.

The number of items of the array should match the number of keys of the keyboard.

The optional parameters are

  • The third line is optional and specifies the numbers of columns and lines, by default four columns and three lines;

  • The fourth line is optional and sets the size of the font, by default fontSizeAutomatic for automatic.

The number of columns and lines should match the number of keys of the keyboard.

By default, the keyboard is enabled according to the GUI setting.

Then,

myKeyboard.setOption(optionWithFrame);
myKeyboard.drawInitial();
myKeyboard.setState(stateEnkeyboardd);

setOption() displays a frame between the keys.

Without and with a frame

Select

  • optionWithoutFrame or false for no frame between the keys;
  • optionWithFrame or true for a frame between the keys.

Default is false for no frame.

drawInitial() draws the initial keyboard with the keys.

setState() defines whether touch is enabled for the element.

Select

  • stateDisabled or false for touch disabled;
  • stateEnabledd or true for touch enabled.

By default, the keyboard is enabled according to the GUI setting.

Use

if (myKeyboard.check())
{
    uint16_t indexKey = 0x0000;
    indexKey = myKeyboard.getIndex();
    myText.draw(formatString("0x%04x", indexKey));
}

check() polls the touch controller and returns true if a key is pressed.

An optional parameter defines the mode of how the element is checked:

  • checkNormal or false for normal check mode;
  • checkInstant or true for instant check mode.

Default mode is normal check mode.

In normal check mode, the element raises the event when the finger is released from the element. Additionally, the element goes through a cinematic sequence.

Start, press, release

In instant check mode, the element raises the event when the finger touches the element. No cinematic sequence is performed.

Start, press

getIndex() returns the index attached to the key.

Example

This is the core of the code from example GUI_Keyboard.ino.

void displayKeyboard()
{
    // Three lines of four columns
    item myKeys[] =
    {
        {0x0011, "11"}, {0x0021, "21"}, {0x0031, "31"}, {0x0041, "41"}, // first line
        {0x0012, "12"}, {0x0022, "22"}, {0x0032, "32"}, {0x0042, "42"}, // second line
        {0x0013, "13"}, {0x0023, "23"}, {0x0033, "33"}, {0x0043, "43"} // third line
    };

    myScreen.setOrientation(myOrientation);
    uint16_t x, y, dx, dy;

    x = myScreen.screenSizeX();
    y = myScreen.screenSizeY();
    dx = x / 5;
    dy = y / 5;

    myGUI.delegate(false);

    dLabel(0, 0, x, dy, "Keyboard", myColours.black, myColours.white, -1, 1, fontLarge);

    text myText;
    myText.dDefine(2 * dx, 0, 2 * dx, dy, 0, 0, fontMedium);

    const uint8_t maxColumn = 4;
    const uint8_t maxLine = 3;
    keyboard myKeyboard;
    myKeyboard.dDefine(dx / 2, dy, dx * 4, dy * 4, myKeys, maxColumn, maxLine);
    myKeyboard.setOption(optionWithFrame);
    myKeyboard.drawInitial();

    drawNext();
    myScreen.flushFast();
    myKeyboard.setState(stateEnabled);

    myGUI.delegate(true);
    uint16_t indexKey = 0x0000;
    while (!checkNext())
    {
        if (myKeyboard.check())
        {
            indexKey = myKeyboard.getIndex();
            myText.draw(formatString("0x%04x", indexKey));
        }
    }
}