Widget Guide

This page explains what each widget does, what properties matter, and how to use them quickly.

Window

Window is the application host and render/event loop owner.

Constructor:

Window (float width, float height, std::string title);

Key Functions:

• setBackgroundColor(unsigned int color) - set background color of the window. Use an RGBA hex like 0xRRGGBBAA
• add(Widgets) - add Widgets/Layouts to the window
• bool isOpen() - returns if window is open
• close() - closes the window

Typical usage

Window window(800, 600, "Velvet");
window.setBackgroundColor(0xE6E6E6FFu);
window.add(Widget);
 
window.run();

---

Stack / HStack / VStack

Stack is Velvet's layout primitive.

• HStack: places children left-to-right
• VStack: places children top-to-bottom

‍Note from the developer:
Stack is similar to a CSS flexbox. One can relate a HStack to a CSS div display: flex with flex-direction: row, and VStack to flex-direction: column. Similarly, padding and gap, justify-content and align-items all work the similarly in Velvet.

Key APIs

• setWidth(float), setHeight(float), setSize(float, float) - set explicit layout size
• setJustifyContent("start"|"center"|"end") - main-axis placement
• setAlignItems("start"|"center"|"end") - cross-axis placement
• setBackgroundColor(sf::Color) - container background fill
• setGap(float) - set spacing between children

Setting padding:

• setPadding(float all) - all sides
• setPadding(float x, float y) - horizontal and vertical
• setPadding(float left, right, top, bottom) - individual directions

Default padding: 8px, can be configured with the above functions

Constructor:

gap: spacing between children (in px)

Stack stack(StackDirection::Horizontal, float gap);   // horizontal stack
Stack stack(StackDirection::Vertical, float gap);     // vertical stack

Or the more convenient HStack and VStack:

HStack stack(float gap);    // horizontal stack
VStack stack(float gap);    // vertical stack
VStack stack;               // default gap: 0px

Example

VStack panel(10); // gap
 
panel.setPadding(16);
panel.setWidth(320);
panel.setJustifyContent("start");
panel.setAlignItems("center");

NOTE: Stacks can be nested! You can do:

HStack parent, one, two;
Vstack three;
 
three.add(one, two);
parent.add(three);

---

Label

Label displays styled text. Supports a style map in the constructor.

Constructor

Label text("Hello, world!");    // default styling parameters
// or:
Label text("Hello, world!", {
  {"fontSize", 24.f},
  {"fillColor", 0x222222FFu},
  ...
});

Supported style keys

• fontPath (std::string) default: "src/assets/AdwaitaSans-Regular.ttf"
• fontSize (float)
• lineSpacing (float)
• letterSpacing (float)
• fillColor (unsigned int, RGBA hex like 0xRRGGBBAA)
• outlineColor (unsigned int)
• outlineThickness (float)
• fontStyle (std::string): regular, bold, italic, underlined, strikethrough
• backgroundColor (unsigned int)

Runtime updates

• setText(const std::string) - change the label text on runtime
• overrideStyling({...}) - Update styling keys on runtime

---

Button

Button implements, well, a button. Supports a style map in the constructor.

Constructor

Button btn("Click me!");    // default styling options
// or
Button btn("Click me!", {
  {"fontSize", 30.f},
  {"backgroundColor", 0x3e3e3eFFu}
  ...
});

Supported style keys:

• fontPath (std::string) default: "src/assets/AdwaitaSans-Regular.ttf"
• fontSize (float)
• letterSpacing (float)
• fontColor (unsigned int, RGBA hex like 0xRRGGBBAA)
• hoverFontColor (unsigned int) font color when button is hovered
• outlineColor (unsigned int) outline of the button
• outlineThickness (float) outline thickness
• backgroundColor (unsigned int) background color of the button
• hoverBackgroundColor (unsigned int) intended background color when button is hovered
• width (float) width of the button; default: 200.f
• height (float) height of the button; default: 50.f

Event callback

Fires onclick callback when left mouse is pressed while hovered.

btn.onclick = [&] {
  // your action
};

Runtime usage

• overrideStyling({...}) - Update styling keys on runtime.

---

Slider

Slider is horizontal and emits continuous values in range [from, to].

Constructor

Slider slider(float width, float from, float to);

Event callback + value access

Slider volume(240, 0.f, 100.f);
volume.onchange = [&](float v) {
  // react to value changes while dragging
};

Get current value of slider:

float current = volume.getValue();

---

InputField

InputField is a single-line text box that accepts keyboard input, and shows a placeholder when empty.

Constructor

InputField field("Placeholder here!");
 
InputField nameField("Enter your name", {
  {"width", 260.f},
  {"fontSize", 18.f},
  {"backgroundColor", 0xFFFFFFFFu},
  ...
});

Supported style keys

• fontPath (std::string) e.g. "src/assets/AdwaitaSans-Regular.ttf"
• fontSize (float)
• letterSpacing (float)
• fontColor (unsigned int) text color, RGBA hex like 0xRRGGBBAA
• outlineColor (unsigned int) inactive border color
• activeOutlineColor (unsigned int) intended active border color when focused
• backgroundColor (unsigned int) input background fill
• placeholderColor (unsigned int) color of the placeholder text
• width (float) width of the input box

Runtime usage

• overrideStyling({...}) - Update styling keys on runtime
• setPlaceholder(std::string placeholderString) - Update the placeholder text

Getter functions:

• std::string getContent() - Returns the current content
• std::string gePlaceholder() - Returns the current placeholder

---

Image

Image displays an image loaded from file.

Constructor

Image img(std::string filePath);

Example usage:

Image avatar("src/assets/evilcat.png");
avatar.setScale(0.5f, 0.5f);

Functions

• setImage(std::string filePath)- Set the image path on runtime.
• setScale(float x, float y)- Set the image scale relative to the image's actual dimensions.

---

Composition example

#include <velvet/core>
 
int main() {
    Window window(600, 400, "test");
 
    HStack root(200);
    
    VStack controls(12);
    
    Label heading("Controls", {{"fontSize", 24.f}});
    Slider amount(200, 0.f, 100.f);
    Button apply(200, 40, "Apply");
    
    VStack preview(12);
    
    Label status("Ready");
    Image cat("src/assets/funnycat.png");
    cat.setScale(0.35f, 0.35f);
    
    apply.onclick = [&] {
      status.setText("Applied: " + std::to_string((int)amount.getValue()));
      cat.setImage("src/assets/evilcat.png");
    };
    
    controls.add(heading, amount, apply);
    preview.add(status, cat);
    root.add(controls, preview);
    
    window.add(root);
    window.run();
}