Element

guikit::Element is the abstract base class of every widget (Box, Text, RootElement, ...). It manages children, layout properties (size, position, flex, margin, padding), event callbacks, and rendering.

It cannot be instantiated directly: render() is pure virtual, so subclass it or use one of the built-in widgets.

This doc assumes using namespace guikit is set and #include <guikit/element.hpp> is included. Otherwise, use guikit::Element instead of Element.

Enums

Layout is configured through the following enums:

enum class FlexDirection { Column, Row, ColumnReverse, RowReverse };

enum class Align {
    Auto, Start, Center, End, Stretch,
    Baseline, SpaceBetween, SpaceEvenly, SpaceAround
};

enum class Justify { Start, Center, End, SpaceBetween, SpaceEvenly, SpaceAround };

enum class Position { Static, Absolute, Relative };

enum class Side { Top, Right, Bottom, Left };

Adding children

`addChild<T>(args...)`

The template helper creates a widget of type T, reparents it, assigns the current renderer, inserts it into the layout tree, and returns a reference to it.

template <typename T, typename... Args>
T &addChild(Args &&...args);

Example:

Box &child = root.addChild<Box>().setWidth(100).setHeight(50);

`addChild(std::shared_ptr<Element> child)`

Adds an already-constructed element as a child.

Element &addChild(std::shared_ptr<Element> child);

Layout: size

`setWidth(float width)`

Sets the width in pixels.

Element &setWidth(float width);

`setHeight(float height)`

Sets the height in pixels.

Element &setHeight(float height);

`setWidthPercent(float width)`

Sets the width as a percentage of the parent's width.

Element &setWidthPercent(float width);

`setHeightPercent(float height)`

Sets the height as a percentage of the parent's height.

Element &setHeightPercent(float height);

`setMaxWidth(float width)`

Sets the maximum width in pixels.

Element &setMaxWidth(float width);

`setMaxHeight(float height)`

Sets the maximum height in pixels.

Element &setMaxHeight(float height);

`setMaxWidthPercent(float width)`

Sets the maximum width as a percentage.

Element &setMaxWidthPercent(float width);

`setMaxHeightPercent(float height)`

Sets the maximum height as a percentage.

Element &setMaxHeightPercent(float height);

`getWidth()`

Returns the computed width of the element after layout.

float getWidth();

`getHeight()`

Returns the computed height of the element after layout.

float getHeight();

`getX()`

Returns the absolute x position (including parent offsets).

float getX();

`getY()`

Returns the absolute y position (including parent offsets).

float getY();

Layout: position

`setPosition(Position position)`

Sets the positioning mode (Static, Absolute, Relative).

Element &setPosition(Position position);

`setTop(float top)`

Sets the offset from the top edge.

Element &setTop(float top);

`setBottom(float bottom)`

Sets the offset from the bottom edge.

Element &setBottom(float bottom);

`setLeft(float left)`

Sets the offset from the left edge.

Element &setLeft(float left);

`setRight(float right)`

Sets the offset from the right edge.

Element &setRight(float right);

`setZ(uint16_t z)`

Sets the stacking order (zIndex).

Element &setZ(uint16_t z);

Layout: flex

`setFlexDirection(FlexDirection direction)`

Sets the main axis (Column or Row).

Element &setFlexDirection(FlexDirection direction);

`setAlignItems(Align alignDirection)`

Aligns children along the cross axis.

Element &setAlignItems(Align alignDirection);

`setJustifyContent(Justify justifyDirection)`

Distributes children along the main axis.

Element &setJustifyContent(Justify justifyDirection);

`setFlexGrow(float grow)`

Sets how much the element grows to fill free space.

Element &setFlexGrow(float grow);

`setFlexShrink(float shrink)`

Sets how much the element shrinks when space runs out.

Element &setFlexShrink(float shrink);

Margin

`setMarginAll(float margin)`

Sets the same margin on all four sides.

Element &setMarginAll(float margin);

`setMarginTop(float marginTop)`

Sets the top margin.

Element &setMarginTop(float marginTop);

`setMarginRight(float marginRight)`

Sets the right margin.

Element &setMarginRight(float marginRight);

`setMarginBottom(float marginBottom)`

Sets the bottom margin.

Element &setMarginBottom(float marginBottom);

`setMarginLeft(float marginLeft)`

Sets the left margin.

Element &setMarginLeft(float marginLeft);

`setMarginPercent(Side side, float marginPercent)`

Sets a margin as a percentage of the parent's size.

Element &setMarginPercent(Side side, float marginPercent);

`setMarginAuto(Side side)`

Sets an automatic margin on the given side.

Element &setMarginAuto(Side side);

Padding

`setPaddingAll(float padding)`

Sets the same padding on all four sides.

Element &setPaddingAll(float padding);

`setPaddingTop(float paddingTop)`

Sets the top padding.

Element &setPaddingTop(float paddingTop);

`setPaddingRight(float paddingRight)`

Sets the right padding.

Element &setPaddingRight(float paddingRight);

`setPaddingBottom(float paddingBottom)`

Sets the bottom padding.

Element &setPaddingBottom(float paddingBottom);

`setPaddingLeft(float paddingLeft)`

Sets the left padding.

Element &setPaddingLeft(float paddingLeft);

`setPaddingPercent(Side side, float paddingPercent)`

Sets padding as a percentage of the parent's size.

Element &setPaddingPercent(Side side, float paddingPercent);

Events

`onClick(std::function<void(MouseEvent &)> handler)`

Registers a callback invoked when the element is clicked.

Element &onClick(std::function<void(MouseEvent &)> handler);

`onMouseMove(std::function<void(MouseEvent &)> handler)`

Registers a callback invoked on every pointer motion over the element. Bubbles.

Element &onMouseMove(std::function<void(MouseEvent &)> handler);

`onMouseEnter(std::function<void(MouseEvent &)> handler)`

Registers a callback invoked once when the pointer enters the element.

Element &onMouseEnter(std::function<void(MouseEvent &)> handler);

`onMouseLeave(std::function<void(MouseEvent &)> handler)`

Registers a callback invoked once when the pointer leaves the element.

Element &onMouseLeave(std::function<void(MouseEvent &)> handler);

`onKeyDown(std::function<void(KeyboardEvent &)> handler)`

Registers a callback invoked on a key press while the element is hovered.

Element &onKeyDown(std::function<void(KeyboardEvent &)> handler);

`onKeyUp(std::function<void(KeyboardEvent &)> handler)`

Registers a callback invoked on a key release while the element is hovered.

Element &onKeyUp(std::function<void(KeyboardEvent &)> handler);

`interSect(int x, int y)`

Returns true if the point falls within the element's bounds.

bool interSect(int x, int y);

Events are hit-tested against the whole widget tree and bubble up through ancestors. Callbacks receive the event by reference so they can call event.preventDefault() or event.stopPropagation(). See the Events reference for details.

Identifiers

`setDirty()`

Marks the element for re-rendering on the next frame.

Element &setDirty();

`setId(std::string id)`

Assigns a unique identifier to the element.

Element &setId(std::string id);

`getElementById(std::string id)`

Looks up an element by its id.

Element *getElementById(std::string id);

Rendering

`render()`

Draws the element. Pure virtual - subclasses must implement it.

virtual void render() = 0;

`renderChildren()`

Renders all children in order.

void renderChildren();

Example

#include <guikit/window.hpp>
#include <guikit/box.hpp>
#include <guikit/colors.hpp>

using namespace guikit;

int main() {
    Window window("Layout Demo", 800, 600);

    Box &row = window.rootElement->addChild<Box>()
                   .setWidthPercent(100)
                   .setHeight(100)
                   .setFlexDirection(FlexDirection::Row)
                   .setAlignItems(Align::Center);

    row.addChild<Box>().setWidth(50).setHeight(50).setBackgroundColor(Colors::Red500());
    row.addChild<Box>().setWidth(50).setHeight(50).setBackgroundColor(Colors::Blue500());

    window.show();
    return 0;
}

Element

On this page