Button¶

Inherits: Image
C++ type: Button

Description¶

An interactive UI button widget. Button extends Image with four visual states — normal, hovered, pressed, and disabled — each of which can have a distinct texture or tint colour. An optional text label can be embedded inside the button.

Use the onPress / onRelease callbacks to respond to user interaction.

Properties¶

Methods¶

Callback events¶

All pointer events from Image are also available.

Property details¶

label¶

• Setter: void setLabel(const std::string& text)
• Getter: std::string getLabel() const
• Setter: void setLabelColor(Vector4 color)
• Setter: void setLabelFont(const std::string& font)
• Setter: void setLabelFontSize(unsigned int fontSize)

The text displayed inside the button. Setting a non-empty label automatically creates a child Text entity. Font and colour apply to that label text.

stateColors¶

• Setter/Getter: void setColorNormal / getColorNormal
• Setter/Getter: void setColorHovered / getColorHovered
• Setter/Getter: void setColorPressed / getColorPressed
• Setter/Getter: void setColorDisabled / getColorDisabled

Per-state tint colours multiplied with the current state texture. Use these to create hover and press effects with a single texture.

Button btn(&scene);
btn.createImage();
btn.setTexture("ui/button.png");
btn.setPatchMargin(12);
btn.setSize(160, 48);
btn.setLabel("Play");
btn.setColorNormal(Vector4(1.0f, 1.0f, 1.0f, 1.0f));
btn.setColorHovered(Vector4(0.85f, 0.85f, 1.0f, 1.0f));
btn.setColorPressed(Vector4(0.7f, 0.7f, 1.0f, 1.0f));

local btn = Button(scene)
btn:createImage()
btn:setTexture("ui/button.png")
btn:setPatchMargin(12)
btn:setSize(160, 48)
btn:setLabel("Play")
btn:setColorNormal(Vector4(1.0, 1.0, 1.0, 1.0))
btn:setColorHovered(Vector4(0.85, 0.85, 1.0, 1.0))
btn:setColorPressed(Vector4(0.7, 0.7, 1.0, 1.0))

disabled¶

• Setter: void setDisabled(bool disabled)
• Getter: bool getDisabled() const

When true, the button ignores pointer events and displays with colorDisabled / textureDisabled. Use to grey out unavailable actions.

statetextures¶

• void setTextureNormal(const std::string& path)
• void setTextureHovered(const std::string& path)
• void setTexturePressed(const std::string& path)
• void setTextureDisabled(const std::string& path)

Assigns a unique texture for each interaction state. If not set, all states use the base texture from Image tinted by the state colour.

Method details¶

hasLabel¶

• bool hasLabel() const

Returns true if a label child entity has been created for this button.

getLabelObject¶

• Text getLabelObject() const

Returns a handle to the child Text entity. Useful for advanced label manipulation such as alignment or size.

Callback event details¶

onPress / onRelease¶

• Property: FunctionSubscribe<void()> onPress
• Property: FunctionSubscribe<void()> onRelease

onPress fires when the mouse button is pressed over the button element. onRelease fires when it is released.

btn.onPress.add([&](){
    Log::print("Button pressed!");
});

btn.onPress:add(function()
    Log.print("Button pressed!")
end)