Skip to content

Keyboard

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

Configure

Warning

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(&myGUI);

The constructor Keyboard() creates a keyboard and sets the link to the GUI myGUI.

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.

Select

  • optionWithoutFrame or false for no frame between the keys;

  • optionWithFrame or true for a frame between the keys.

Note

Use literals instead of values for upward compatibility.

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.

Note

Use literals instead of values for upward compatibility.

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 for normal check mode;

  • checkInstant 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

The technical note Optimise GUI speed provides more details on the cinematic sequences of each check mode.

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

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

    Text myText(&myGUI);
    myText.dDefine(2 * dx, 0, 2 * dx, dy, 0, 0, fontMedium);

    const uint8_t maxColumn = 4;
    const uint8_t maxLine = 3;
    Keyboard myKeyboard(&myGUI);
    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));
        }
    }
}