GUI library

This document provides comprehensive documentation for the Paxos GUI library, detailing its core components, element types, and usage examples.

Core Class: ElementBase

The ElementBase class serves as the foundation for all GUI elements within the Paxos library. It defines common properties and methods inherited by all other element types.

Members:

m_x: X-coordinate of the element's top-left corner.
m_y: Y-coordinate of the element's top-left corner.
m_width: Width of the element.
m_height: Height of the element.
m_backgroundColor: Background color of the element.
m_borderColor: Border color of the element.
m_borderSize: Thickness of the element's border.
m_borderRadius: Radius of the element's rounded corners.
m_parent: Pointer to the parent element (if any).
m_children: Vector of child elements.
m_isEnabled: Boolean indicating whether the element is enabled.
m_surface: Pointer to the underlying graphics surface.

Methods:

render(): Virtual function responsible for rendering the element's visual representation. Must be overridden by derived classes.
update(): Updates the element's state and handles user interaction.
setX(uint16_t x): Sets the X-coordinate.
setY(uint16_t y): Sets the Y-coordinate.
setWidth(uint16_t width): Sets the width.
setHeight(uint16_t height): Sets the height.
getX() const: Returns the X-coordinate.
getY() const: Returns the Y-coordinate.
getWidth() const: Returns the width.
getHeight() const: Returns the height.
setBackgroundColor(color_t color): Sets the background color.
setBorderColor(color_t color): Sets the border color.
setRadius(uint16_t r): Sets the border radius.
getRadius() const: Returns the border radius.
setBorderSize(uint16_t size): Sets the border size.
getBorderSize() const: Returns the border size.
getBackgroundColor() const: Returns the background color.
getBorderColor() const: Returns the border color.
isTouched(): Returns true if the element was touched and released.
isFocused(bool forced = false): Returns true if the element is currently being touched.
enable(): Enables the element.
disable(): Disables the element.
setEnabled(bool enabled): Sets the enabled state.
isEnabled() const: Returns the enabled state.
addChild(ElementBase *child): Adds a child element.
getSurface(): Returns a pointer to the surface.
forceUpdate(): Forces a graphical update.

Example:

#include "ElementBase.hpp"

// Create a derived class
class MyElement : public gui::ElementBase {
public:
    MyElement(uint16_t x, uint16_t y, uint16_t width, uint16_t height) : ElementBase() {
        setX(x);
        setY(y);
        setWidth(width);
        setHeight(height);
        setBackgroundColor(COLOR_RED);
    }

    void render() override {
      m_surface->fillRect(0,0, getWidth(), getHeight(), getBackgroundColor());
    }
};

int main() {
    // Initialize graphics (implementation-specific)
    // ...

    // Create an instance of MyElement
    MyElement myElement(10, 10, 50, 50);

    // Add to window
    gui::elements::Window win;
    win.addChild(&myElement);

    while (true)
    {
      win.updateAll();
    }

    return 0;
}

GUI Elements

1. Box

A simple rectangular box element.

Members:

Inherits all members from ElementBase.

Methods:

Box(uint16_t x, uint16_t y, uint16_t width, uint16_t height): Constructor.
render() override: Renders the box.

Example:

#include "Box.hpp"

gui::elements::Box myBox(10, 20, 100, 50);
myBox.setBackgroundColor(COLOR_BLUE);
myBox.setBorderColor(COLOR_BLACK);
myBox.setBorderSize(2);
myBox.setRadius(5);

2. Button

A clickable button element.

Members:

m_label: Pointer to the button's label.
m_image: Pointer to the button's image.
m_theme: Boolean representing the button theme (e.g., light or dark).

Methods:

Button(uint16_t x, uint16_t y, uint16_t width, uint16_t height): Constructor.
render() override: Renders the button.
setText(std::string text): Sets the button text.
setIcon(storage::Path path): Sets the button icon.
getText(): Returns the button text.
setTheme(bool value): Sets the button theme.
onClick() override: Called when the button is clicked.
onReleased() override: Called when the button is released

Example:

#include "Button.hpp"

gui::elements::Button myButton(10, 20, 80, 30);
myButton.setText("Click Me");

// In the update loop:
if (myButton.isTouched()) {
    // Handle button click
}

3. Canvas

A drawable surface for custom graphics.

Members:

Inherits members from ElementBase.

Methods:

Canvas(uint16_t x, uint16_t y, uint16_t width, uint16_t height): Constructor.
render() override: Dummy render function (drawing is done directly on the surface).
setPixel(int16_t x, int16_t y, color_t color): Sets a pixel's color.
drawRect(...), fillRect(...), drawCircle(...), fillCircle(...), drawRoundRect(...), fillRoundRect(...), drawPolygon(...), fillPolygon(...), drawLine(...): Drawing functions.
drawText(...): Draw text with optional font size.
drawTextCentered(...): Draw centered text with optional alignment parameters.

Example:

#include "Canvas.hpp"

gui::elements::Canvas myCanvas(10, 20, 200, 100);
myCanvas.setPixel(50, 50, COLOR_RED);
myCanvas.drawLine(0, 0, 100, 50, COLOR_BLUE);
std::string text = "Hello";
myCanvas.drawText(0,0, text, COLOR_BLACK);

4. Checkbox

A checkbox element.

Members:

m_state: Boolean indicating whether the checkbox is checked.

Methods:

Checkbox(uint16_t x, uint16_t y): Constructor.
render() override: Renders the checkbox.
setState(bool state): Sets the checked state.
getState(): Returns the checked state.

Example:

#include "Checkbox.hpp"

gui::elements::Checkbox myCheckbox(10, 20);

// In the update loop:
if (myCheckbox.isTouched()) {
    bool isChecked = myCheckbox.getState();
    // ...
}

5. Filter (Deprecated)

Marked as deprecated; avoid using.

6. Image

Displays an image from storage.

Members:

m_path: Path to the image file.

Methods:

Image(storage::Path path, uint16_t x, uint16_t y, uint16_t width, uint16_t height): Constructor.
render() override: Renders the image.
load(): Loads the image from the specified path.

Example:

#include "Image.hpp"

gui::elements::Image myImage(storage::Path("/path/to/image.png"), 10, 20, 50, 50);
myImage.load();

7. Input

A text input field.

Members:

m_text: The inputted text.
m_placeHolder: Placeholder text displayed when the input is empty.

Methods:

Input(uint16_t x, uint16_t y): Constructor.
render() override: Renders the input field.
setText(const std::string& text): Sets the input text.
setPlaceHolder(const std::string& text): Sets the placeholder text.
getText(): Returns the input text.
getPlaceHolder(): Returns the placeholder text.

Example:

#include "Input.hpp"

gui::elements::Input myInput(10, 20);
myInput.setPlaceHolder("Enter text...");

// In the update loop:
if (myInput.isTouched()) {
   std::string inputText = myInput.getText();
  // ...
}

8. Keyboard

An on-screen keyboard for text input.

Members:

(Numerous members related to keyboard layout and state - see Keyboard.hpp for full list)

Methods:

Keyboard(const std::string &defaultText = ""): Constructor.
render() override: Renders the keyboard.
widgetUpdate() override: Handles key presses and other keyboard interactions.
getText(): Returns the entered text and clears the keyboard buffer.
hasExitKeyBeenPressed(): Checks if the exit key has been pressed.
setPlaceholder(const std::string &placeholder): Sets placeholder text for the input field.

Example:

#include "Keyboard.hpp"

gui::elements::Keyboard keyboard;

// In the update loop:
keyboard.updateAll();

if (keyboard.hasExitKeyBeenPressed()) {
   std::string enteredText = keyboard.getText();
   // ...
}

9. Label

Displays static text.

Members:

m_text: The text to display.
m_textColor: Color of the text.
m_fontSize: Size of the font.

Methods:

Label(uint16_t x, uint16_t y, uint16_t width, uint16_t height): Constructor.
render() override: Renders the label.
setText(const std::string& text): Sets the text.
getText() const: Gets the text.
setTextColor(color_t color): Sets text color.
setFontSize(uint16_t fontSize): Set font size.
setHorizontalAlignment(Alignement alignment): Sets horizontal alignment.
setVerticalAlignment(Alignement alignment): Sets vertical alignment.

Example:

#include "Label.hpp"

gui::elements::Label myLabel(10, 20, 100, 20);
myLabel.setText("Hello, world!");
myLabel.setTextColor(COLOR_GREEN);
myLabel.setHorizontalAlignment(gui::elements::Label::CENTER);

10. List (VerticalList & HorizontalList)

Creates scrollable lists of elements.

Members: (VerticalList)

m_lineSpace: Spacing between list items.
m_focusedIndex: Index of the currently focused item.

Methods: (VerticalList)

VerticalList(uint16_t x, uint16_t y, uint16_t width, uint16_t height): Constructor.
render() override: Renders the list.
add(ElementBase* widget): Adds an element to the list.
setSpaceLine(uint16_t y): Sets spacing between lines.
onScrollUp(): Called when scrolling up.
onScrollDown(): Called when scrolling down.

Methods: (HorizontalList)

HorizontalList(uint16_t x, uint16_t y, uint16_t width, uint16_t height): Constructor.
render() override: Renders the list.
add(ElementBase* widget): Adds an element to the list.
setSpaceLine(uint16_t y): Sets spacing between lines.

Example (VerticalList):

#include "List.hpp"
#include "Label.hpp"


gui::elements::VerticalList myList(10, 20, 100, 200);

for (int i = 0; i < 20; ++i) {
  gui::elements::Label* label = new gui::elements::Label(0, 0, 80, 20);
  label->setText("Item " + std::to_string(i));
  myList.add(label);
}


// In the update loop:
myList.updateAll();

11. Radio

A radio button element.

Members:

m_state: Boolean indicating whether the radio button is selected.

Methods:

Radio(uint16_t x, uint16_t y): Constructor.
render() override: Renders the radio button.
setState(bool state): Sets the selected state.
getState(): Returns the selected state.

Example:

#include "Radio.hpp"

gui::elements::Radio myRadio(10, 20);

// In the update loop:
if (myRadio.isTouched()) {
   bool isSelected = myRadio.getState();
    // ...
}

12. Switch

A toggle switch element.

Members:

m_state: Boolean indicating the switch state (on/off).

Methods:

Switch(uint16_t x, uint16_t y): Constructor.
render() override: Renders the switch.
setState(bool state): Sets the switch state.
getState(): Returns the switch state.

Example:

#include "Switch.hpp"

gui::elements::Switch mySwitch(10, 20);

// In the update loop:
if (mySwitch.isTouched()) {
    bool isOn = mySwitch.getState();
    // ...
}

13. Window

A top-level window element.

Members:

windows: A static vector containing all created windows.

Methods:

Window(): Constructor.
render() override: Renders the window.

Example:

#include "Window.hpp"

gui::elements::Window myWindow;

// Add other elements to the window using myWindow.addChild(...);

// In the main loop:
while(true) {
    myWindow.updateAll();
}

GuiManager

A singleton class providing utility functions for the GUI.

Methods:

getInstance(): Returns the singleton instance.
getWindow(): Returns the main window.
showInfoMessage(const std::string& msg ): Shows an info message popup.
showWarningMessage(const std::string& msg ): Shows a warning message popup.
showErrorMessage(const std::string& msg ): Shows an error message popup.

Example:

#include "GuiManager.hpp"

GuiManager& guiManager = GuiManager::getInstance();
gui::elements::Window& mainWindow = guiManager.getWindow();

// Add some elements to mainWindow

// ... later in the code
guiManager.showErrorMessage("Something went wrong!");

while(true) {
    mainWindow.updateAll();
}

This documentation provides a basic overview of the Paxos GUI library. Refer to the individual header files (.hpp) for more detailed information about each class and its members. Remember to consult the graphics library documentation for specifics on color definitions and other graphics-related functions.