QuickStart

Welcome to the Makepad QuickStart guide. This document is designed to help you set up a new Makepad project quickly and understand its basic structure and components. Makepad is a creative coding environment that leverages Rust and its ecosystem to build performant and beautiful UI applications.

Project Structure

A typical Makepad project has a structure similar to what you see below. Understanding this structure is crucial for navigating and managing your project effectively.

- hello                     # Your project directory
├── Cargo.toml              # Rust's package manifest file for managing dependencies
└── src                     # The main project directory containing Rust source files
    ├── app.rs              # The entry file for the Makepad application, defines UI and behavior
    ├── lib.rs              # The library file, used to expose modules to other parts of the application
    └── main.rs             # The standard Rust main entry point; here, it's used to launch the Makepad app

Initiate a Project

To start a new Makepad project, you'll first need to create a new Rust project and then add the necessary Makepad dependencies.

# Create a new Rust project named hello
cargo new hello

# Navigate into your project directory
cd hello

# Add Makepad dependencies to your project
cargo add makepad-widgets  # Adds Makepad's widget library for UI components
cargo add makepad          # Adds Makepad itself (note: this line is awaiting Makepad's update to be functional)

Add Library Module

To organize your code and make the Makepad widgets available throughout your project, you'll need to create a lib.rs file under the src directory.

Create a file named lib.rs in the src directory.
Add the following content to lib.rs:

#![allow(unused)]
fn main() {
pub use makepad_widgets;  // Expose makepad_widgets to other parts of your application
pub mod app;              // Declare the app module, which will contain your application's logic
}

Create the Application Module

Now, let's focus on building your application. This involves using Makepad widgets, designing the application's UI, and defining its behavior.

Use Widgets

In your app.rs or equivalent file, start by importing the Makepad widgets:

#![allow(unused)]
fn main() {
use makepad_widgets::*; // Import all components from makepad_widgets
}

Add Live Design

Makepad supports live design through its macro system. This allows you to define UI components and their properties in a readable and concise manner.

#![allow(unused)]
fn main() {
use makepad_widgets::*; // Ensure makepad_widgets are imported

live_design!{
    import makepad_widgets::base::*;                  // Import base widgets and components
    import makepad_widgets::theme_desktop_dark::*;    // Use the dark theme for desktop applications
    App = {{App}} {                                   // Define the main App struct
        ui: <Root>{}                                // Use a Root widget as the root UI element
    }
}
}

Build the Application Struct

The main application structure, App, should contain a reference to the root UI element. This is marked with the #[live] macro to integrate with Makepad's live design system.

This is necessary even if no event logic is written

#![allow(unused)]
fn main() {
#[derive(Live, LiveHook)] // Derive macros to enable live reloading and hooks
pub struct App {
    #[live] ui: WidgetRef, // The root UI element reference
}
}

Register the Application Struct

To ensure Makepad recognizes your application structure, implement the LiveRegister trait for App.

#![allow(unused)]
fn main() {
impl LiveRegister for App {
    fn live_register(cx: &mut Cx) {
        crate::makepad_widgets::live_design(cx); // Register the live design for makepad_widgets
    }
}
}

Implement `AppMain` for Application

To handle events and integrate with the Makepad system, implement the AppMain trait for your App struct.

#![allow(unused)]
fn main() {
impl AppMain for App {
    fn handle_event(&mut self, cx: &mut Cx, event: &Event) {
        self.ui.handle_event(cx, event, &mut Scope::empty()); // Delegate event handling to the UI root
    }
}

app_main!(App); // Macro to designate App as the main application entry
}

The Main Function

Finally, define the main function in main.rs, which will launch your Makepad application.

fn main(){
    hello::app::app_main(); // Call the app_main function generated by the app_main! macro in app.rs
}

Congratulations, you've set up a basic Makepad project! This setup outlines how to structure your project, add dependencies, and create a simple UI application. As you become more familiar with Makepad and Rust, you can start exploring more complex UI designs and application logic.

Gen-UI Book