Use the GUI library with the Basic edition¶

This application note describes how to use the GUI library with the Basic edition.

The GUI library for the Basic edition provides a general GUI object and two elements, Text and Button, to design and operate a human machine interface.

It manages touch.

Danger

Because the GUI library uses the fast update mode, it requires the driver Driver_EPD_Touch_Small.

GUI¶

The GUI object stores and shares parameters used by the two elements, Text and Button.

Configure¶

Warning

Ensure the screen is declared and initialised according to the configuration procedure.

#include "hV_GUI.h"

The pre-processor statement includes the GUI library.

GUI myGUI(&myScreen);

The constructor GUI() sets the link to the screen.

Danger

Because the GUI library uses the fast update mode, it requires the driver Driver_EPD_Touch_Small.

Legacy release 8

Because the GUI library uses the fast update mode, it requires a screen of type Screen_EPD_EXT3_Fast provided by the PDLS_EXT3_Advanced_Fast, PDLS_EXT3_Advanced_Wide or PDLS_EXT3_Advanced_Touch libraries.

myGUI.begin();

begin() initialises the GUI with the default parameters.

The default parameters delegate the update to the interface elements and set the colours of the interface to black for text and white for background.

Then, if needed,

myGUI.delegate(true);
myGUI.setColours(myColours.black, myColours.white);

delegate(true) tells the GUI to manage the partial update of the interface elements.

When set to false, the update of the screen needs to be managed on the main code.

setColours() sets the front and back colours of the interface.

Note

For monochrome and colour e-paper screens, ensure the selected colours are supported.

Use¶

The GUI library exposes two elements:

Output Text;
Input Button.

Text¶

The text is an output element and defines an area with a text inside.

Configure¶

Warning

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

Text myText(&myGUI);

The constructor Text() creates a text and sets the link to the GUI myGUI.

myText.dDefine(10, 10, 80, 50,
    Font_Terminal8x12);

dDefine() defines the text 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 optional parameters is

The second line is optional and defines the size of the font, by default Font_Terminal6x8.

Use¶

myText.draw("Text");

draw() displays the text.

Button¶

The button is an input element and displays an interactive button.

Configure¶

Warning

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

Button myButton(&myGUI);

The constructor Button() creates a button and sets the link to the GUI myGUI.

myButton.dDefine(10, 10, 80, 50,
    "Button",
    Font_Terminal8x12);

dDefine() defines the button 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 contains the text of the label as a string;

The optional parameters is

The third line is optional and sets the size of the font, by default Font_Terminal6x8.

Use¶

myButton.draw();
bool result = myButton.check();

draw() displays the button.

check() polls the touch controller and returns true is the button is pressed.

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

checkNormal for normal check;
checkInstant for instant check.

Default mode is normal check.

Normal checkInstant check

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.

Example¶

The example Touch_GUI.ino displays two buttons, one with normal check mode and another with instant check mode, and a text.

The section below includes the SDK and the libraries, and defines the variables.

// SDK
#include "hV_HAL_Peripherals.h"

// Configuration
#include "hV_Configuration.h"

// Set parameters
#define DISPLAY_GUI_ELEMENT 1

// Define variables and constants
#include "PDLS_EXT3_Advanced_Touch.h"
//
// Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_271_KS_09_Touch, boardRaspberryPiPico_RP2040);
Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_370_PS_0C_Touch, boardRaspberryPiPico_RP2040);

// GUI
#include "hV_GUI.h"
GUI myGUI(&myScreen);

uint8_t fontMedium;

// Checks
#if (TOUCH_MODE == USE_TOUCH_NONE)
#error Required TOUCH_MODE USE_TOUCH_YES
#endif // TOUCH_MODE

The function below displays a count-down.

// Utilities
///
/// @brief Wait with countdown
/// @param second duration, s
///
void wait(uint8_t second)
{
    for (uint8_t i = second; i > 0; i--)
    {
        hV_HAL_Serial.print(formatString(" > %i  \r", i));
        hV_HAL_delayMilliseconds(1000);
    }
    hV_HAL_Serial.print("         \r");
}

The code below is the core of the example.

#if (DISPLAY_GUI == 1)

void displayGUI()
{
    myScreen.setOrientation(ORIENTATION_LANDSCAPE);
    myScreen.selectFont(fontMedium);

    myScreen.clear();

    myGUI.begin();

    Button myButtonNormal(&myGUI);
    Button myButtonInstant(&myGUI);
    Text myText(&myGUI);

    uint16_t x = myScreen.screenSizeX();
    uint16_t y = myScreen.screenSizeY();

    uint16_t dx = x / 7;
    uint16_t dy = y / 5;

    myGUI.delegate(false);

    myButtonNormal.dStringDefine(dx * 1, dy * 3, dx * 2, dy, "Normal", fontMedium);
    myButtonInstant.dStringDefine(dx * 4, dy * 3, dx * 2, dy, "Instant", fontMedium);
    myText.dDefine(0, dy, x, dy, fontMedium);

    myButtonNormal.draw();
    myButtonInstant.draw();
    myText.draw("Empty");

    myScreen.flush();

    myGUI.delegate(true);

    uint8_t k = 8;
    uint32_t chrono32;
    while (k > 0)
    {
        if (myScreen.getTouchInterrupt())
        {
            chrono32 = millis();
            if (myButtonNormal.check(checkNormal))
            {
                k -= 1;
                chrono32 = millis() - chrono32;
                myText.draw(formatString("%s in %i ms (%i left)", "Normal", chrono32, k));
                mySerial.println(formatString("%3i: %s in %i ms", k, "Normal", chrono32));
            }

            chrono32 = millis();
            if (myButtonInstant.check(checkInstant))
            {
                k -= 1;
                chrono32 = millis() - chrono32;
                myText.draw(formatString("%s in %i ms (%i left)", "Instant", chrono32, k));
                mySerial.println(formatString("%3i: %s in %i ms", k, "Instant", chrono32));
            }
        } // getTouchInterrupt

        delay(100);
    }

    myScreen.clear();
}

#endif // DISPLAY_GUI

The main code initialises the screen and the GUI, then calls the example for the element.

///
/// @brief Setup
///
void setup()
{
    // hV_HAL_Serial = Serial by default, otherwise edit hV_HAL_Peripherals.h
    hV_HAL_begin(); // with Serial at 115200

    hV_HAL_Serial_crlf();
    hV_HAL_log(LEVEL_INFO, __FILE__);
    hV_HAL_log(LEVEL_INFO, __DATE__ " " __TIME__);
    hV_HAL_Serial_crlf();

    // Screen
    myScreen.begin();

    myScreen.regenerate();

    // Fonts
#if (FONT_MODE == USE_FONT_TERMINAL)

    fontSmall = Font_Terminal6x8;
    fontMedium = Font_Terminal8x12;
    fontLarge = Font_Terminal12x16;
    fontVery = Font_Terminal16x24;

#else // FONT_MODE

    fontSmall = myScreen.addFont(Font_DejaVuSans12);
    fontSmall -= ((fontSmall > 0) ? 1 : 0);
    fontMedium = myScreen.addFont(Font_DejaVuSans16);
    fontMedium -= ((fontMedium > 0) ? 1 : 0);
    fontLarge = myScreen.addFont(Font_DejaVuSans24);
    fontLarge -= ((fontLarge > 0) ? 1 : 0);
    fontVery = myScreen.addFont(Font_DejaVuMono48);
    fontVery -= ((fontVery > 0) ? 1 : 0);

#endif // FONT_MODE

    // Example
#if (DISPLAY_GUI == 1)

    mySerial.println("DISPLAY_GUI");
    myScreen.clear();
    displayElement();
    wait(8);

#endif // DISPLAY_GUI

    hV_HAL_log(LEVEL_INFO, "Regenerate");
    myScreen.regenerate();

    hV_HAL_exit(0);
}

///
/// @brief Loop, empty
///
void loop()
{
    hV_HAL_delayMilliseconds(1000);
}