Skip to content

UIGridLayout

Grid layout container for organizing elements in a matrix.

Description

UIGridLayout organizes UI elements in a fixed grid of rows and columns. It supports navigation in 4 directions (UP/DOWN/LEFT/RIGHT) and automatic positioning based on grid coordinates.

This layout is ideal for inventories, level selection screens, galleries, and any grid-based UI arrangement.

Namespace

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

Inheritance

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

Constructors

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

Constructs a new UIGridLayout.

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

Example: 

#include "graphics/ui/UIGridLayout.h"

// Create 4x4 grid for inventory
pixelroot32::graphics::ui::UIGridLayout* inventory = 
    new pixelroot32::graphics::ui::UIGridLayout(
        10.0f, 10.0f,  // position
        108.0f, 108.0f // size
    );
inventory->setColumns(4);

Public Methods

void addElement(UIElement* element)

Adds a UI element to the layout.

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

Returns: - void

Notes: - Elements are arranged in grid order (left to right, top to bottom) - Layout is automatically recalculated - Cell size is calculated based on columns and layout size

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.

Returns: - void

Notes: - Recalculates cell dimensions - Recalculates row count - Repositions all elements

void handleInput(const InputManager& input)

Handles input for navigation and selection.

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

Returns: - void

Notes: - Handles UP/DOWN/LEFT/RIGHT navigation - Manages selection state - Wraps around grid edges (if configured)

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 the layout and its visible elements.

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

Returns: - void

void setColumns(uint8_t cols)

Sets the number of columns in the grid.

Parameters: - cols (uint8_t): Number of columns (must be > 0)

Returns: - void

Notes: - Layout is automatically recalculated - Row count is calculated based on element count and columns

Example: 

inventory->setColumns(4);  // 4 columns

uint8_t getColumns() const

Gets the number of columns.

Returns: - uint8_t: Number of columns

uint8_t getRows() const

Gets the number of rows (calculated).

Returns: - uint8_t: Number of rows

Notes: - Calculated as ceil(elementCount / columns)

int getSelectedIndex() const

Gets the currently selected element index.

Returns: - int: Selected index, or -1 if none selected

void setSelectedIndex(int index)

Sets the selected element index.

Parameters: - index (int): Index to select (-1 to deselect)

Returns: - void

UIElement* getSelectedElement() const

Gets the selected element.

Returns: - UIElement*: Pointer to selected element, or nullptr if none selected

void setNavigationButtons(uint8_t upButton, uint8_t downButton, uint8_t leftButton, uint8_t rightButton)

Sets the navigation button indices.

Parameters: - upButton (uint8_t): Button index for UP navigation - downButton (uint8_t): Button index for DOWN navigation - leftButton (uint8_t): Button index for LEFT navigation - rightButton (uint8_t): Button index for RIGHT navigation

Returns: - void

Notes: - Default: UP=0, DOWN=1, LEFT=2, RIGHT=3 - Change if your input mapping differs

void setButtonStyle(Color selectedTextCol, Color selectedBgCol, Color unselectedTextCol, Color unselectedBgCol)

Sets the style colors for selected and unselected buttons.

Parameters: - selectedTextCol (Color): Text color when selected - selectedBgCol (Color): Background color when selected - unselectedTextCol (Color): Text color when not selected - unselectedBgCol (Color): Background color when not selected

Returns: - void

Usage Example

#include "graphics/ui/UIGridLayout.h"

class InventoryScene : public pixelroot32::core::Scene {
private:
    pixelroot32::graphics::ui::UIGridLayout* inventory;

public:
    void init() override {
        // Create 4x4 inventory grid
        inventory = new pixelroot32::graphics::ui::UIGridLayout(
            10.0f, 10.0f,
            108.0f, 108.0f
        );
        inventory->setColumns(4);
        inventory->setSpacing(2.0f);
        inventory->setPadding(4.0f);

        // Add inventory slots
        for (int i = 0; i < 16; i++) {
            auto* slot = createInventorySlot(i);
            inventory->addElement(slot);
        }

        addEntity(inventory);
    }
};

See Also