Skip to content

GUI Development Introduction

CacaoLang includes powerful GUI capabilities through GTK4 bindings, allowing you to create native desktop applications with ease.

Overview

The CacaoLang GUI library (Amour Lib v0.22) provides:

  • Native widgets - Buttons, labels, text entries, and more
  • Layout containers - Flexible box layouts and frames
  • Event handling - Callbacks for user interactions
  • Cross-platform - Works on Linux, macOS, and Windows

Requirements

To build GUI applications, you need:

  • GTK4 development libraries installed
  • CacaoLang compiled with GUI support (default)

See the Installation Guide for setup instructions.

Hello GUI Example

Here's a simple GUI application:

// Initialize the GUI system
gui_init("com.chocolang.hello");

// Create a window
let window = gui_window("My First GUI", 400, 300);

// Create a label
let label = gui_label("Hello, GUI World!");

// Add label to window
gui_add(window, label);

// Show and run
gui_run();

Basic GUI Structure

Every CacaoLang GUI application follows this pattern:

// 1. Initialize GUI
gui_init("your.app.id");

// 2. Create window
let window = gui_window("Title", width, height);

// 3. Create widgets
let button = gui_button("Click Me");
let label = gui_label("Status");

// 4. Create layout container (optional)
let box = gui_box("vertical", 10);

// 5. Add widgets to container
gui_add(box, label);
gui_add(box, button);

// 6. Add container to window
gui_add(window, box);

// 7. Set up event handlers (optional)
fn on_click() {
    gui_set_text(label, "Clicked!");
}
gui_on(button, "clicked", "on_click");

// 8. Run the application
gui_run();

Available Widgets

CacaoLang provides these widget types:

Widget Function Description
Window gui_window() Main application window
Button gui_button() Clickable button
Label gui_label() Text display
Entry gui_entry() Single-line text input
TextView gui_textview() Multi-line text input
Checkbox gui_checkbox() Toggle checkbox
Box gui_box() Layout container
Frame gui_frame() Decorative frame
Separator gui_separator() Visual separator

Events

Widgets can respond to user actions:

// Button clicked
gui_on(button, "clicked", "my_callback");

// Text changed
gui_on(entry, "changed", "text_changed");

// Window closed
gui_on(window, "close", "cleanup");

Complete Example

gui_init("com.chocolang.counter");

let window = gui_window("Counter App", 300, 200);
let box = gui_box("vertical", 10);

let label = gui_label("Count: 0");
let button = gui_button("Increment");

let count = 0;

fn increment() {
    count = count + 1;
    let text = "Count: #{count}";
    gui_set_text(label, text);
}

gui_on(button, "clicked", "increment");

gui_add(box, label);
gui_add(box, button);
gui_add(window, box);

gui_run();

Widget IDs

Most GUI functions return a widget ID (string) that you use to reference the widget:

let btn1 = gui_button("Button 1");
let btn2 = gui_button("Button 2");

// Reference by ID
gui_set_text(btn1, "Updated Text");

You can also specify custom IDs:

let button = gui_button("Click Me", "my_button");
gui_on("my_button", "clicked", "handle_click");

Next Steps