Image¶

Inherits: UILayout
C++ type: Image

Description¶

The foundational 2D UI visual element. Image renders a textured or colour-filled rectangle with optional 9-patch scaling. It is the base class for Button, Panel, Progressbar, Scrollbar, and TextEdit.

9-patch scaling (also called scale-9 or nine-slice) divides the image into a 3×3 grid. The four corner pieces are never stretched, while the edges and centre fill the available space. This allows buttons and panel backgrounds to scale to any size without distorting the corners.

All UI elements also expose a rich set of pointer/focus callback events (inherited via UIComponent). See the Callback events section.

Properties¶

Methods¶

Callback events¶

Property details¶

color¶

• Setter: void setColor(Vector4 color)
• Setter: void setColor(float red, float green, float blue, float alpha)
• Setter: void setColor(float red, float green, float blue)
• Setter: void setAlpha(float alpha)
• Getter: Vector4 getColor() const
• Getter: float getAlpha() const

The tint colour multiplied with the texture. (1,1,1,1) renders the texture as-is. Changing the colour is a cheap way to create hover/pressed states without separate textures.

flipY¶

• Setter: void setFlipY(bool flipY)
• Getter: bool isFlipY() const

Flips the texture vertically. Useful when a texture is loaded upside-down or for certain rendering passes.

patchMargin¶

• Setter: void setPatchMargin(unsigned int margin)
• Setter: void setPatchMargin(unsigned int left, unsigned int right, unsigned int top, unsigned int bottom)
• Individual getters: getPatchMarginLeft, getPatchMarginRight, getPatchMarginTop, getPatchMarginBottom

Sets the 9-patch insets. When all four margins are zero (the default), the image is scaled uniformly. Setting the margins enables 9-patch mode where the corners are preserved.

Image panel(&scene);
panel.createImage();
panel.setTexture("ui/panel_bg.png");
panel.setPatchMargin(20);  // 20px on all sides
panel.setSize(300, 200);

local panel = Image(scene)
panel:createImage()
panel:setTexture("ui/panel_bg.png")
panel:setPatchMargin(20)
panel:setSize(300, 200)

Method details¶

createImage¶

• bool createImage()

Initialises GPU buffers for the image. Must be called once before the image is rendered or any visual properties are set.

setTexture¶

• void setTexture(const std::string& path)
• void setTexture(const std::string& id, TextureData data)
• void setTexture(Framebuffer* framebuffer)

Assigns the texture to display. Pass a file path, in-memory pixel data with a cache id, or a framebuffer for render-to-texture UI.

getAABB / getWorldAABB¶

• AABB getAABB() const
• AABB getWorldAABB() const

Returns the axis-aligned bounding box in local or world space. Useful for hit-testing or layout calculations.

Callback event details¶

onGetFocus / onLostFocus¶

• Property: FunctionSubscribe<void()> onGetFocus
• Property: FunctionSubscribe<void()> onLostFocus

Called when this element gains or loses keyboard focus.

onPointerEnter / onPointerLeave¶

• Property: FunctionSubscribe<void(float,float)> onPointerEnter
• Property: FunctionSubscribe<void(float,float)> onPointerLeave
• Callback: void(float x, float y)

Called when the mouse pointer enters or leaves the element boundary.

Image btn(&scene);
btn.createImage();
btn.onPointerEnter.add([&](float x, float y){
    btn.setColor(Vector4(0.8f, 0.8f, 1.0f, 1.0f));  // highlight
});
btn.onPointerLeave.add([&](float x, float y){
    btn.setColor(Vector4(1.0f, 1.0f, 1.0f, 1.0f));  // reset
});

btn.onPointerEnter:add(function(x, y)
    btn:setColor(Vector4(0.8, 0.8, 1.0, 1.0))
end)
btn.onPointerLeave:add(function(x, y)
    btn:setColor(Vector4(1.0, 1.0, 1.0, 1.0))
end)

onPointerMove¶

• Property: FunctionSubscribe<void(float,float)> onPointerMove
• Callback: void(float x, float y)

Called each frame the pointer moves while over this element.

onPointerDown / onPointerUp¶

• Property: FunctionSubscribe<void(float,float)> onPointerDown
• Property: FunctionSubscribe<void(float,float)> onPointerUp
• Callback: void(float x, float y)

Called on mouse/touch press and release.

onClick / onDoubleClick¶

• Property: FunctionSubscribe<void(float,float)> onClick
• Property: FunctionSubscribe<void(float,float)> onDoubleClick
• Callback: void(float x, float y)

Called on a complete click (press + release inside the element) or double click.

onDragStart / onDrag / onDragEnd¶

• Property: FunctionSubscribe<void(float,float)> onDragStart
• Property: FunctionSubscribe<void(float,float)> onDrag
• Property: FunctionSubscribe<void(float,float)> onDragEnd
• Callback: void(float x, float y)

Fired when the user begins dragging, continues dragging, or releases while dragging this element.