Skip to content

GUI library

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 touch, it requires the library Pervasive_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);
GUI()
The constructor creates a GUI object and sets the link to the screen.

Danger

Because the GUI library uses touch, it requires the library Pervasive_Touch_Small.

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:

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);
Text()
The constructor creates a text and sets the link to the GUI myGUI.
1
2
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);
Button()
The constructor creates a button and sets the link to the GUI myGUI.
1
2
3
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.

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

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.

// Set parameters
#define DISPLAY_GUI_ELEMENT 1

// SDK and configuration
#include "PDLS_Common.h"

// Driver
#include "Pervasive_Touch_Small.h"
// Driver_EPD myDriver(eScreen_EPD_370_PS_0C_Touch, boardRaspberryPiPico_RP2040);
Pervasive_Touch_Small myDriver(eScreen_EPD_271_KS_09_Touch, boardRaspberryPiPico_RP2040);

// Screen
#include "PDLS_Basic.h"
Screen_EPD myScreen(&myDriver);

// 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 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
    fontSmall = Font_Terminal6x8;
    fontMedium = Font_Terminal8x12;
    fontLarge = Font_Terminal12x16;
    fontVery = Font_Terminal16x24;

    // Example
#if (DISPLAY_GUI == 1)

    mySerial.println("DISPLAY_GUI");
    myScreen.clear();
    displayElement();
    hV_HAL_delayMilliseconds(8000);

#endif // DISPLAY_GUI

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

    hV_HAL_exit(RESULT_SUCCESS);
}

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