Skip to content

UIAnchorLayout

Layout that positions elements at fixed anchor points on the screen.

Description

UIAnchorLayout positions UI elements at fixed anchor points (corners, center, edges) without reflow. Very efficient for HUDs, debug UI, and fixed-position elements. Positions are calculated once or when screen size changes.

This layout is ideal for HUD elements like score, lives, health bars, and other fixed-position UI.

Namespace

namespace pixelroot32::graphics::ui {
    class UIAnchorLayout : public UILayout {
        // ...
    };
}

Inheritance

  • Inherits from: UILayout
  • Inherited by: Your custom anchor layouts (if needed)

Anchor Enum

Defines anchor points for positioning UI elements.

Values: - Anchor::TOP_LEFT: Top-left corner - Anchor::TOP_RIGHT: Top-right corner - Anchor::BOTTOM_LEFT: Bottom-left corner - Anchor::BOTTOM_RIGHT: Bottom-right corner - Anchor::CENTER: Center of screen - Anchor::TOP_CENTER: Top center - Anchor::BOTTOM_CENTER: Bottom center - Anchor::LEFT_CENTER: Left center - Anchor::RIGHT_CENTER: Right center

Constructors

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

Constructs a new UIAnchorLayout.

Parameters: - x (float): X position of the layout container (usually 0) - y (float): Y position of the layout container (usually 0) - w (float): Width of the layout container (usually screen width) - h (float): Height of the layout container (usually screen height)

Example: 

#include "graphics/ui/UIAnchorLayout.h"

// Create full-screen anchor layout for HUD
auto& renderer = engine.getRenderer();
pixelroot32::graphics::ui::UIAnchorLayout* hud = 
    new pixelroot32::graphics::ui::UIAnchorLayout(
        0.0f, 0.0f,
        static_cast<float>(renderer.getWidth()),
        static_cast<float>(renderer.getHeight())
    );
hud->setScreenSize(
    static_cast<float>(renderer.getWidth()),
    static_cast<float>(renderer.getHeight())
);

Public Methods

void addElement(UIElement* element, Anchor anchor)

Adds a UI element with a specific anchor point.

Parameters: - element (UIElement*): Pointer to the element to add - anchor (Anchor): Anchor point for positioning

Returns: - void

Example: 

// Score label at top-right
hud->addElement(scoreLabel, pixelroot32::graphics::ui::Anchor::TOP_RIGHT);

// Lives label at top-left
hud->addElement(livesLabel, pixelroot32::graphics::ui::Anchor::TOP_LEFT);

void addElement(UIElement* element)

Adds a UI element to the layout (defaults to TOP_LEFT anchor).

Parameters: - element (UIElement*): Pointer to the element to add

Returns: - void

void removeElement(UIElement* element)

Removes a UI element from the layout.

Parameters: - element (UIElement*): Pointer to the element to remove

Returns: - void

void updateLayout()

Recalculates positions of all elements based on anchors.

Returns: - void

Notes: - Called automatically when screen size changes - Can be called manually if needed

void handleInput(const InputManager& input)

Handles input (no-op for anchor layout, elements handle their own input).

Parameters: - input (const pixelroot32::input::InputManager&): Reference to the InputManager

Returns: - void

Notes: - Anchor layout doesn't handle navigation - Elements handle their own input

void update(unsigned long deltaTime) override

Updates the layout and child elements.

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

Returns: - void

void draw(Renderer& renderer) override

Draws all elements.

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

Returns: - void

void setScreenSize(float screenWidth, float screenHeight)

Sets the screen size for anchor calculations.

Parameters: - screenWidth (float): Screen width in pixels - screenHeight (float): Screen height in pixels

Returns: - void

Notes: - Used to calculate anchor positions - Should match actual display size - Layout is automatically recalculated

Example: 

auto& renderer = engine.getRenderer();
hud->setScreenSize(
    static_cast<float>(renderer.getWidth()),
    static_cast<float>(renderer.getHeight())
);

float getScreenWidth() const

Gets the screen width.

Returns: - float: Screen width in pixels

float getScreenHeight() const

Gets the screen height.

Returns: - float: Screen height in pixels

Usage Example

#include "graphics/ui/UIAnchorLayout.h"

class GameScene : public pixelroot32::core::Scene {
private:
    pixelroot32::graphics::ui::UIAnchorLayout* hud;
    pixelroot32::graphics::ui::UILabel* scoreLabel;
    pixelroot32::graphics::ui::UILabel* livesLabel;

public:
    void init() override {
        auto& renderer = engine.getRenderer();

        // Create HUD layout
        hud = new pixelroot32::graphics::ui::UIAnchorLayout(
            0.0f, 0.0f,
            static_cast<float>(renderer.getWidth()),
            static_cast<float>(renderer.getHeight())
        );
        hud->setScreenSize(
            static_cast<float>(renderer.getWidth()),
            static_cast<float>(renderer.getHeight())
        );

        // Score label (top-right)
        scoreLabel = new pixelroot32::graphics::ui::UILabel(
            "Score: 0",
            0, 0,
            Color::White,
            1
        );
        hud->addElement(scoreLabel, 
                        pixelroot32::graphics::ui::Anchor::TOP_RIGHT);

        // Lives label (top-left)
        livesLabel = new pixelroot32::graphics::ui::UILabel(
            "Lives: 3",
            0, 0,
            Color::Yellow,
            1
        );
        hud->addElement(livesLabel, 
                        pixelroot32::graphics::ui::Anchor::TOP_LEFT);

        addEntity(hud);
    }

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

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

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

        // HUD is drawn automatically (on layer 2)
    }
};

Anchor Positioning

Elements are positioned based on their anchor:

  • TOP_LEFT: Element's top-left at screen top-left
  • TOP_RIGHT: Element's top-right at screen top-right
  • BOTTOM_LEFT: Element's bottom-left at screen bottom-left
  • BOTTOM_RIGHT: Element's bottom-right at screen bottom-right
  • CENTER: Element centered on screen
  • TOP_CENTER: Element centered horizontally, top-aligned
  • BOTTOM_CENTER: Element centered horizontally, bottom-aligned
  • LEFT_CENTER: Element centered vertically, left-aligned
  • RIGHT_CENTER: Element centered vertically, right-aligned

Performance Considerations

  • No reflow: Very efficient (positions calculated once)
  • Fixed positions: Ideal for HUD elements
  • Viewport independent: Elements stay in fixed screen positions

ESP32 Considerations

  • Memory: Very efficient (no complex calculations)
  • Update frequency: Positions only recalculate when screen size changes

See Also