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:setTexture("ui/button.png")
btn:setPatchMargin(12)
btn:setSize(160, 48)
btn.label = "Play"
btn.colorNormal = Vector4(1.0, 1.0, 1.0, 1.0)
btn.colorHovered = Vector4(0.85, 0.85, 1.0, 1.0)
btn.colorPressed = Vector4(0.7, 0.7, 1.0, 1.0)

transitions¶

• Setter/Getter: void setScaleHovered / float getScaleHovered
• Setter/Getter: void setScalePressed / float getScalePressed
• Setter/Getter: void setTransitionTime / float getTransitionTime

A hovered or pressed button grows by scaleHovered or scalePressed (1.1 is 10% bigger), around its pivot, so set the pivot to (0.5, 0.5) to grow it from the middle. With a transitionTime in seconds, the state colour and scale change over that time when the pointer enters, leaves, presses or releases the button, instead of at once. Textures still swap at once.

btn.setScaleHovered(1.08f);
btn.setScalePressed(0.95f);
btn.setTransitionTime(0.12f);

btn.scaleHovered = 1.08
btn.scalePressed = 0.95
btn.transitionTime = 0.12

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.getComponent<ButtonComponent>().onPress.add("pressed", [&](){
    Log::print("Button pressed!");
});

local btnComp = btn:getButtonComponent()
btnComp.onPress = function()
    Log.print("Button pressed!")
end