Skip to content

UIPanel

Visual container that draws a background and border around a child element.

Description

UIPanel provides a retro-style window/panel appearance with a background color and border. Typically contains a UILayout or other UI elements. Useful for dialogs, menus, and information panels.

The panel wraps a single child element and draws a background rectangle and border around it.

Namespace

namespace pixelroot32::graphics::ui {
    class UIPanel : public UIElement {
        // ...
    };
}

Inheritance

  • Inherits from: UIElement
  • Inherited by: Your custom panel classes (if needed)

Constructors

UIPanel(float x, float y, float w, float h)

Constructs a new UIPanel.

Parameters: - x (float): X position of the panel - y (float): Y position of the panel - w (float): Width of the panel - h (float): Height of the panel

Example: 

#include "graphics/ui/UIPanel.h"

// Create dialog panel
pixelroot32::graphics::ui::UIPanel* dialog = 
    new pixelroot32::graphics::ui::UIPanel(
        20.0f, 30.0f,  // position
        88.0f, 68.0f   // size
    );

Public Methods

void setChild(UIElement* element)

Sets the child element.

Parameters: - element (UIElement*): Pointer to the UI element to wrap (typically a UILayout)

Returns: - void

Notes: - Child element is positioned inside the panel (with padding) - Typically a layout (VerticalLayout, etc.)

Example: 

// Create panel
auto* panel = new UIPanel(20, 30, 88, 68);

// Create layout for panel content
auto* layout = new UIVerticalLayout(0, 0, 80, 60);
layout->addElement(button1);
layout->addElement(button2);

// Set layout as panel child
panel->setChild(layout);

UIElement* getChild() const

Gets the child element.

Returns: - UIElement*: Pointer to the child element, or nullptr if none set

void setBackgroundColor(Color color)

Sets the background color.

Parameters: - color (Color): Background color

Returns: - void

Example: 

panel->setBackgroundColor(Color::Blue);

Color getBackgroundColor() const

Gets the background color.

Returns: - Color: Background color

void setBorderColor(Color color)

Sets the border color.

Parameters: - color (Color): Border color

Returns: - void

Example: 

panel->setBorderColor(Color::White);

Color getBorderColor() const

Gets the border color.

Returns: - Color: Border color

void setBorderWidth(uint8_t width)

Sets the border width.

Parameters: - width (uint8_t): Border width in pixels

Returns: - void

Notes: - Default: 1 pixel - Higher values = thicker border

Example: 

panel->setBorderWidth(2);  // 2 pixel border

uint8_t getBorderWidth() const

Gets the border width.

Returns: - uint8_t: Border width in pixels

void setPosition(float newX, float newY)

Sets the position of the panel. Also updates the child element's position.

Parameters: - newX (float): New X coordinate - newY (float): New Y coordinate

Returns: - void

Notes: - Child element position is updated automatically

void update(unsigned long deltaTime) override

Updates the panel and child element.

Parameters: - deltaTime (unsigned long): Time elapsed in milliseconds

Returns: - void

Notes: - Updates child element if set - Called automatically by Scene

void draw(Renderer& renderer) override

Draws the panel (background, border) and child element.

Parameters: - renderer (pixelroot32::graphics::Renderer&): Reference to the renderer

Returns: - void

Notes: - Draws background rectangle - Draws border rectangle - Draws child element if set

Usage Example

#include "graphics/ui/UIPanel.h"
#include "graphics/ui/UIVerticalLayout.h"

class DialogScene : public pixelroot32::core::Scene {
private:
    pixelroot32::graphics::ui::UIPanel* dialog;

public:
    void init() override {
        // Create dialog panel
        dialog = new pixelroot32::graphics::ui::UIPanel(
            20.0f, 30.0f,  // position
            88.0f, 68.0f   // size
        );
        dialog->setBackgroundColor(Color::Navy);
        dialog->setBorderColor(Color::White);
        dialog->setBorderWidth(2);

        // Create layout for dialog content
        auto* layout = new pixelroot32::graphics::ui::UIVerticalLayout(
            4.0f, 4.0f,  // Position inside panel
            80.0f, 60.0f // Size inside panel
        );
        layout->setSpacing(8.0f);

        // Add buttons
        auto* okButton = new UIButton("OK", 0, 0, 0, 70.0f, 20.0f, 
                                     [this]() { closeDialog(); });
        auto* cancelButton = new UIButton("Cancel", 1, 0, 0, 70.0f, 20.0f,
                                         [this]() { closeDialog(); });

        layout->addElement(okButton);
        layout->addElement(cancelButton);

        // Set layout as panel child
        dialog->setChild(layout);

        addEntity(dialog);
    }
};

Performance Considerations

  • Rendering: Simple rectangles; very efficient
  • Child updates: Child element updates are fast
  • Memory: Small overhead (just colors and border width)

ESP32 Considerations

  • Memory: Panel is lightweight
  • Rendering: Two rectangles (background + border); minimal overhead

See Also