Skip to content

UILabel

A simple text label UI element.

Description

UILabel displays a string of text on the screen. It auto-calculates its bounds based on text length and font size, making it easy to create dynamic text displays.

Labels are useful for displaying scores, status messages, menu text, and other UI information.

Namespace

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

Inheritance

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

Constructors

UILabel(string t, float x, float y, Color col, uint8_t sz)

Constructs a new UILabel.

Parameters: - t (std::string): Initial text - x (float): X position - y (float): Y position - col (Color): Text color - sz (uint8_t): Text size multiplier

Example: 

#include "graphics/ui/UILabel.h"

// Create label
pixelroot32::graphics::ui::UILabel* scoreLabel = new pixelroot32::graphics::ui::UILabel(
    "Score: 0",
    10.0f, 10.0f,  // position
    pixelroot32::graphics::Color::White,
    1  // size
);

// Add to scene
scene->addEntity(scoreLabel);

Public Methods

void setText(const string& t)

Updates the label's text. Recalculates dimensions immediately using the active font metrics to ensure precise layout.

Parameters: - t (const std::string&): New text

Returns: - void

Notes: - Automatically recalculates width and height using FontManager::textWidth - Use for dynamic text (scores, timers, etc.) - Text is stored as std::string (consider memory on ESP32)

Example: 

// Update score label
char scoreText[32];
snprintf(scoreText, sizeof(scoreText), "Score: %d", score);
scoreLabel->setText(scoreText);

void setVisible(bool v)

Sets visibility.

Parameters: - v (bool): true to show, false to hide

Returns: - void

Notes: - Inherited from Entity - Hides label without removing from scene

Example: 

label->setVisible(false);  // Hide
label->setVisible(true);   // Show

void centerX(int screenWidth)

Centers the label horizontally within a given width (typically the screen width). Recalculates dimensions before positioning to ensure perfect centering.

Parameters: - screenWidth (int): The width to center within (e.g., engine.getRenderer().getWidth())

Returns: - void

Example: 

label->centerX(128); // Center on a 128px screen

void update(unsigned long deltaTime) override

Updates the label state.

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

Returns: - void

Notes: - Called automatically by Scene if isEnabled is true - Default implementation does nothing - Override to add custom update logic (animations, etc.)

Example: 

void update(unsigned long deltaTime) override {
    UILabel::update(deltaTime);

    // Custom logic (e.g., update text based on game state)
    if (scoreChanged) {
        updateScoreText();
    }
}

void draw(Renderer& renderer) override

Renders the label.

Parameters: - renderer (pixelroot32::graphics::Renderer&): The renderer to use

Returns: - void

Notes: - Called automatically by Scene if isVisible is true - Draws text at label position - Uses default font

Example: 

// Drawing is handled automatically
// Override only for custom rendering

Auto-Sizing

Labels automatically calculate their size based on text:

  • Width: text.length() * (6 * size) pixels
  • Height: 8 * size pixels

Example: 

// Label with text "Hello" (5 characters), size 1
// Width: 5 * 6 * 1 = 30 pixels
// Height: 8 * 1 = 8 pixels

UILabel label("Hello", 10, 10, Color::White, 1);
// label.width = 30, label.height = 8

Usage Example

#include "graphics/ui/UILabel.h"

class GameScene : public pixelroot32::core::Scene {
private:
    pixelroot32::graphics::ui::UILabel* scoreLabel;
    pixelroot32::graphics::ui::UILabel* livesLabel;
    int score = 0;
    int lives = 3;

public:
    void init() override {
        // Score label
        scoreLabel = new pixelroot32::graphics::ui::UILabel(
            "Score: 0",
            10.0f, 10.0f,
            pixelroot32::graphics::Color::White,
            1
        );
        addEntity(scoreLabel);

        // Lives label
        livesLabel = new pixelroot32::graphics::ui::UILabel(
            "Lives: 3",
            10.0f, 25.0f,
            pixelroot32::graphics::Color::Yellow,
            1
        );
        addEntity(livesLabel);
    }

    void update(unsigned long deltaTime) override {
        Scene::update(deltaTime);

        // Update labels
        char text[32];
        snprintf(text, sizeof(text), "Score: %d", score);
        scoreLabel->setText(text);

        snprintf(text, sizeof(text), "Lives: %d", lives);
        livesLabel->setText(text);
    }

    void draw(pixelroot32::graphics::Renderer& renderer) override {
        // Draw game
        Scene::draw(renderer);

        // Labels are drawn automatically by Scene::draw()
    }
};

Centered Labels

// Create centered title
pixelroot32::graphics::ui::UILabel* title = new pixelroot32::graphics::ui::UILabel(
    "Game Title",
    0, 20.0f,  // X will be adjusted
    pixelroot32::graphics::Color::Yellow,
    2  // Large text
);
title->centerX(128);  // Center on screen
addEntity(title);

Performance Considerations

  • Text updates: setText() recalculates size; avoid calling every frame if text doesn't change
  • String storage: Uses std::string; consider memory on ESP32
  • Rendering: Simple text drawing; very efficient
  • Static text: For static text, create once and don't update

ESP32 Considerations

  • Memory: std::string uses heap memory; use static buffers when possible
  • Text updates: Limit frequency of text updates
  • String length: Keep text short to save memory

See Also