UILayout¶

Inherits: Object
C++ type: UILayout

Description¶

Base class for all UI elements. UILayout extends Object with a pixel-based sizing and anchor system that lets widgets automatically resize and reposition relative to their parent container or the screen edges.

The anchor system works in two modes:

• Fixed size — the widget has an explicit width/height. The anchor points define which corner(s) of the parent the widget is attached to; anchor offsets define the pixel distance from those corners.
• Stretch mode — by setting anchor points on all four edges (e.g. FULL_LAYOUT), the widget automatically fills the available space, optionally with pixel margins.

A UI element's position is its top-left corner, and by default it scales and rotates around that corner too. Set a pivot to grow it from its center instead.

Properties¶

Methods¶

Enumerations¶

AnchorPreset¶

Convenience presets for common anchor configurations:

• NONE — No anchor preset applied.
• TOP_LEFT / TOP_RIGHT / BOTTOM_LEFT / BOTTOM_RIGHT — Fixed-size widget anchored to a corner.
• CENTER_LEFT / CENTER_TOP / CENTER_RIGHT / CENTER_BOTTOM — Fixed-size widget centred on an edge.
• CENTER — Fixed-size widget centred in the parent.
• LEFT_WIDE / TOP_WIDE / RIGHT_WIDE / BOTTOM_WIDE — Stretches along one axis, fixed on the other.
• VERTICAL_CENTER_WIDE — Stretches vertically, centred horizontally.
• HORIZONTAL_CENTER_WIDE — Stretches horizontally, centred vertically.
• FULL_LAYOUT — Stretches to fill the entire parent.

Property details¶

width / height¶

• Setter: void setWidth(unsigned int width) / setHeight(unsigned int height)
• Setter: void setSize(unsigned int width, unsigned int height)
• Getter: unsigned int getWidth() / getHeight() const

Pixel dimensions of the UI element. Only used when the anchor configuration does not stretch the element.

anchorPoints¶

• Setter: void setAnchorPoints(float left, float top, float right, float bottom)
• Individual setters/getters: setAnchorPointLeft, setAnchorPointTop, setAnchorPointRight, setAnchorPointBottom

Normalised values in [0, 1] defining where each edge of this element is attached within the parent. For example, (0, 0, 0, 0) pins the top-left corner; (0, 0, 1, 1) stretches to fill the parent.

anchorOffsets¶

• Setter: void setAnchorOffsets(int left, int top, int right, int bottom)
• Individual setters/getters: setAnchorOffsetLeft, setAnchorOffsetTop, setAnchorOffsetRight, setAnchorOffsetBottom

Pixel margins from the anchor points. For a FULL_LAYOUT preset with a 10-pixel margin, set all offsets to 10.

anchorPreset¶

• Setter: void setAnchorPreset(AnchorPreset anchorPreset)
• Getter: AnchorPreset getAnchorPreset() const

Applies a AnchorPreset that sets anchorPoints automatically.

Image overlay(&scene);
overlay.createImage();
overlay.setAnchorPreset(AnchorPreset::FULL_LAYOUT);

local overlay = Image(scene)
overlay.anchorPreset = AnchorPreset.FULL_LAYOUT

positionOffset¶

• Setter: void setPositionOffset(Vector2 positionOffset)
• Individual: setPositionXOffset, setPositionYOffset
• Getter: Vector2 getPositionOffset() const

An additional pixel offset applied to the final computed position. Useful for fine-tuning placement without modifying the anchor configuration.

pivot¶

• Setter: void setPivot(Vector2 pivot)
• Setter: void setPivot(float x, float y)
• Getter: Vector2 getPivot() const

The point the element scales and rotates around, as a share of its size: (0, 0) is the top-left corner (the default), (0.5, 0.5) the center and (1, 1) the bottom-right corner. It does not move the element: the position stays the top-left corner of the unscaled element, so anchors and layouts are unaffected. getWorldPosition() returns where the top-left corner is after scaling and rotation.

A Text with its own Center or Baseline option moves its glyphs away from the layout rectangle, so a pivot is measured from that rectangle, not from the glyphs.

// a button that grows from its center on hover
Button play(&scene);
play.setPivot(0.5f, 0.5f);
play.getComponent<UIComponent>().onPointerEnter.add("grow", [&](float x, float y){
    play.setScale(1.05f);
});
play.getComponent<UIComponent>().onPointerLeave.add("shrink", [&](float x, float y){
    play.setScale(1.0f);
});

play:setPivot(0.5, 0.5)
local ui = play:getUIComponent()
ui.onPointerEnter = function(x, y) play:setScale(1.05) end
ui.onPointerLeave = function(x, y) play:setScale(1.0) end

usingAnchors¶

• Setter: void setUsingAnchors(bool usingAnchors)
• Getter: bool isUsingAnchors() const

When false, the element is positioned using the standard 3D transform from Object rather than the anchor system.

ignoreScissor¶

• Setter: void setIgnoreScissor(bool ignoreScissor)
• Getter: bool isIgnoreScissor() const

When true, this element is not clipped to the parent's scissor rectangle. Use for tooltips or overlays that must extend beyond a scrollable container.