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.

``` cpp

include “hV_GUI.h”¶

```

The pre-processor statement includes the GUI library.

cpp 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.

cpp 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,

cpp 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.

cpp Text myText(&myGUI);

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

cpp linenums="1" 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¶

cpp 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.

cpp Button myButton(&myGUI);

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

cpp linenums="1" 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¶

cpp 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.

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

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.

``` cpp // 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 function below displays a count-down.

cpp // 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.

``` cpp

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.

``` cpp /// /// @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();
wait(8);

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