--- # System prepended metadata title: 'Rust egui: A Step-by-Step Tutorial (Easy Reading Format)' --- # Rust egui: A Step-by-Step Tutorial (Easy Reading Format) Hello there! Welcome to GUI (Graphical User Interface) development with Rust and the `egui` library. I'm Gemini, your guide. Think of me as a friendly teacher who's helped many beginners like you get started with Rust. We'll take it slow and steady. Don't worry if things seem new – we'll break them down. Let's begin! ## I. Introduction to egui: Your Friendly GUI Toolkit **What's a GUI?** It's the visual part of an app – buttons, text boxes, sliders – things you click and interact with. **What's `egui`?** `egui` is a Rust library specifically made for building these GUIs. **Why use `egui`?** * **Simple & Fast:** It's designed to be easy to learn and quick to run [1, 2]. * **Portable:** Write your code once, run it on desktops (Windows, Mac, Linux) *and* in web browsers! [1, 3] This uses a technology called WebAssembly (WASM). * **Immediate Mode:** This is `egui`'s special way of working. Let's explore it. ### Immediate Mode vs. Retained Mode (The `egui` Way) Think of **Retained Mode** (common in other GUI toolkits) like building with LEGOs. You create objects (button, text box), and the library *remembers* them [1]. `egui` uses **Immediate Mode**. Imagine a whiteboard: 1. Every fraction of a second (a "frame"), `egui` asks your code: "What should the UI look like *right now*?" 2. Your code describes the *entire* UI based on the current situation (your app's data). 3. `egui` draws it. 4. `egui` then *forgets* the drawing, ready for the next frame [1, 2]. **Key Differences:** | Feature | Immediate Mode (`egui`) | Retained Mode (Other GUIs) | | :------------------ | :-------------------------------------- | :-------------------------------------- | | **UI Definition** | Redrawn fresh **every frame** [1]. | UI objects **created & kept** in memory. | | **State** | **Your app code** holds UI data [1, 2]. | GUI library often holds UI data. | | **Interactions** | Logic is **in your drawing code** [1]. | Separate "event handlers" attached. | | **Simplicity** | Often **simpler** to start with [1, 2]. | Can handle complex layouts easily. | **Why Immediate Mode is often simpler:** Your code directly controls what's shown based on your application's data *right now*. There's less complexity in syncing separate UI state [2]. ## II. Essential Rust Fundamentals for egui You don't need to be a Rust expert, but knowing these basic concepts will help you understand `egui` code [3]. * **Functions (`fn`):** Blocks of code that do specific tasks. You'll put your UI logic in functions. * **Mutability (`mut`):** Allows variables to be changed. GUIs change constantly, so you'll see `mut` a lot, especially with `&mut` (mutable borrow) [3]. * **Structs (`struct`):** Let you create your own data types by grouping related variables. You'll use a struct to hold your application's state (data) [1]. * **Enums (`enum`):** Define a type that can have one of a few specific values (variants). Great for multiple-choice options [3]. * **Closures (`|args| { ... }`):** Mini, unnamed functions defined on the spot. `egui` uses them heavily for layout and defining UI sections [3]. * **Ownership & Borrowing (`&`, `&mut`):** Rust's safety feature! `&mut` lets `egui` safely *modify* your app's state without taking ownership [3]. * **Traits:** Define shared behaviour (like interfaces). You'll implement the `eframe::App` trait for your main app struct [3]. * **Modules & Crates (`use`, `::`):** How Rust organizes code and uses external libraries (`egui`, `eframe`). `use` brings items into scope; `::` separates parts of a path (like `eframe::egui`). Don't worry if these seem abstract now. You'll see them in action soon! ## III. Setting Up a New Rust Project with eframe Let's create our first project! We'll use `eframe`, which helps `egui` run as a standalone app [1]. **Steps:** 1. **Open Terminal:** Go to your command prompt or terminal. 2. **Navigate:** Go to the directory where you keep your code projects. 3. **Create Project:** Run `cargo new egui_demo` ```bash cargo new egui_demo ``` 4. **Enter Directory:** Run `cd egui_demo` ```bash cd egui_demo ``` 5. **Add `eframe` Dependency:** * Open the `Cargo.toml` file in the `egui_demo` folder. * Find the `[dependencies]` section. * Add this line: ```toml [dependencies] eframe = "0.25" # Using version from example [1]. Check crates.io for latest! ``` 6. **Write Basic Code:** * Open the file `src/main.rs`. * **Delete everything** inside it. * Paste this starting code [1]: ```Rust // Import necessary stuff from the eframe crate use eframe::egui; // Main entry point of the program fn main() -> Result<(), eframe::Error> { // Default window settings let options = eframe::NativeOptions::default(); // Start the egui application! eframe::run_native( "egui Demo", // Window title options, // Window settings // This creates our app state. Don't worry too much about Box::new for now. Box::new(|_cc| Box::new(MyApp::default())), ) } // This struct holds our application's data (state) // `#[derive(Default)]` makes it easy to create a starting instance #[derive(Default)] struct MyApp { label: String, // For a text input field value: f32, // For a slider // We will add more fields here later! } // Implement the eframe::App trait for MyApp, telling eframe how to run it impl eframe::App for MyApp { // The `update` method is called every frame to draw the UI // `&mut self` allows this method to modify MyApp's fields fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) { // Show a central panel where we'll put our UI egui::CentralPanel::default().show(ctx, |ui| { // `ui` is our tool to add widgets // Add a heading ui.heading("My egui Application"); // Arrange items horizontally ui.horizontal(|ui| { ui.label("Write something: "); // Text input linked to `self.label` // `&mut self.label` lets the widget change the `label` field ui.text_edit_singleline(&mut self.label); }); // Add a slider linked to `self.value` ui.add(egui::Slider::new(&mut self.value, 0.0..=10.0).text("value")); // Add a button if ui.button("Increment").clicked() { // If clicked, increase `self.value` self.value += 1.0; } // Display the current state in a label ui.label(format!("Hello '{}', value: {}", self.label, self.value)); }); } } ``` 7. **Run the App:** * Go back to your terminal (still in the `egui_demo` folder). * Run `cargo run` ```bash cargo run ``` * Cargo will build and run your code. A window should appear! [1] You did it! You ran your first `egui` app. ## IV. Basic Structure of an egui Application (Enhanced Explanation) Let's break down that starting code: 1. **`main` Function:** * Starts the program. * Sets up `eframe` options. * Calls `eframe::run_native(...)`. * Tells `eframe` how to create your application's initial state (`Box::new(|_cc| Box::new(MyApp::default()))`). * **Syntax Note:** `Box::new()` puts data on the "heap" (a memory area). `eframe` uses it here for flexibility. You don't need to fully grasp `Box` yet. Just know this line creates your `MyApp` struct. * **Syntax Note:** `MyApp::default()` uses the `Default` trait (often auto-generated by `#[derive(Default)]`) to create a `MyApp` with starting values (empty `String`, `0.0` `f32`). 2. **The State Struct (`struct MyApp`)** * Holds *all* the data your UI needs. * `label: String` holds text for the input box. * `value: f32` holds the number for the slider. 3. **The `eframe::App` Trait Implementation (`impl eframe::App for MyApp`)** * This block tells `eframe` that `MyApp` knows how to be an application. * It requires the `update` method. 4. **The `update` Method (`fn update(&mut self, ...)`):** * **The heart of `egui`!** Called every frame (many times per second). * **`&mut self`:** Gets *mutable access* to your `MyApp` instance. This is crucial! It means `update` can *change* the data (like `self.value += 1.0`). * **`ctx: &egui::Context`:** Provides access to `egui`'s context (input, style, etc.). * **`|ui| { ... }`:** A closure! An inline function where you define the UI for *this frame*. `egui` gives you the `ui` object to use inside it. * **`ui.heading(...)`, `ui.horizontal(...)`, etc.:** Methods called on the `ui` object add widgets (visual elements) to the screen. * **`&mut self.label`, `&mut self.value`:** Passing mutable borrows (`&mut`) links the widget directly to your state field. When the user interacts, the widget modifies your `MyApp` field. **Key Idea:** The `update` function runs, reads the current state from `self`, draws the UI based on that state, checks for interactions, potentially modifies `self` based on interactions, and then finishes until the next frame. ## V. Adding Basic UI Widgets (Enhanced Explanation) Widgets are the building blocks (buttons, labels, etc.). You add them using the `ui` object inside closures. Let's enhance `MyApp` to hold more state for new widgets: ```Rust // --- Add Enums (Specific choice types) --- #[derive(Debug, PartialEq, Clone, Copy)] // Allow printing, comparing, copying enum ColorChoice { Red, Green, Blue } #[derive(PartialEq, Debug, Clone, Copy)] // Allow comparing, printing, copying enum AppMode { View, Edit, Settings } // --- Update MyApp Struct (holds ALL application state) --- struct MyApp { label: String, value: f32, show_extra_info: bool, // For a checkbox (true/false) selected_color: ColorChoice, // For radio buttons counter: i32, // Another piece of state current_mode: AppMode, // To control which view is shown } // --- Manually Implement `Default` (starting values) --- // We do this manually because ColorChoice/AppMode don't have automatic defaults. impl Default for MyApp { fn default() -> Self { // `Self` means `MyApp` here Self { label: "Initial Text".to_string(), // Create a String value: 5.0, show_extra_info: false, // Checkbox starts unchecked selected_color: ColorChoice::Red, // Default radio choice counter: 0, current_mode: AppMode::View, // Start in View mode } } } ``` **Syntax Explained:** * **`enum`:** Defines a type with specific variants (e.g., `ColorChoice` can *only* be `Red`, `Green`, or `Blue`). * **`#[derive(...)]`:** Asks Rust to auto-generate common trait implementations (`Debug` for printing, `PartialEq` for `==`, `Clone`/`Copy` for duplicating). * **`impl Default for MyApp`:** Provides a standard way (`MyApp::default()`) to create a starting instance. * **`Self { ... }`:** Syntax to create an instance of the struct (`MyApp`) within its own `impl` block. * **`.to_string()`:** Converts a basic string literal (`"..."`) into an owned `String`. Now, let's see how to add Checkboxes and Radio Buttons in the `update` method (we'll integrate this into a fuller example later): ```Rust // Inside the `update` method, within a panel's `.show(ctx, |ui| { ... })` block: // --- Checkbox --- // Links directly to the `show_extra_info` boolean field in `MyApp`. // Clicking the box toggles `self.show_extra_info`. ui.checkbox(&mut self.show_extra_info, "Show Advanced Options"); // You can then use this state to show/hide other things: if self.show_extra_info { ui.label("Showing advanced info because the box is checked!"); // ... add more widgets here ... } // --- Radio Buttons --- ui.label("Choose a Color:"); // Arrange them horizontally ui.horizontal(|ui| { // Each button represents one variant of the `ColorChoice` enum. // They are linked to the SAME state field: `self.selected_color`. // Clicking a button updates `self.selected_color` to *that button's* value. ui.radio_value(&mut self.selected_color, ColorChoice::Red, "Red"); ui.radio_value(&mut self.selected_color, ColorChoice::Green, "Green"); ui.radio_value(&mut self.selected_color, ColorChoice::Blue, "Blue"); }); // Display the currently selected choice ui.label(format!("Selected: {:?}", self.selected_color)); // `{:?}` uses Debug format ``` **Key Idea:** Widgets like `checkbox` and `radio_value` use `&mut self.field_name` to directly read *and write* to your application's state struct (`MyApp`). ## VI. Handling User Interactions (Enhanced Explanation) How does your app *react*? You check widget states during the `update` call [1, 4]. Most interactive widgets (like `button`, `slider`, `checkbox`) return a `Response` struct. This `Response` tells you what happened *in that specific frame*. * **Button Clicks (`.clicked()`):** ```Rust // Store the response in a variable let save_button_response = ui.button("Save"); // Check if it was clicked THIS frame if save_button_response.clicked() { println!("Save clicked!"); // Update state or call a function here... self.label = "Saved!".to_string(); } ``` * **Mouse Hover (`.hovered()`):** ```Rust if save_button_response.hovered() { // Show a helpful tooltip when the mouse is over the button save_button_response.on_hover_text("Click here to save your data"); } ``` * **Right-Clicks (`.secondary_clicked()`):** ```Rust if save_button_response.secondary_clicked() { println!("Right-click detected!"); // Maybe show a context menu here... } ``` * **Value Changes (`.changed()`):** Useful for sliders, text edits, etc. ```Rust let slider_response = ui.add(egui::Slider::new(&mut self.value, 0.0..=10.0)); // `changed()` is true in the frame the value *finished* changing (e.g., mouse release) if slider_response.changed() { println!("Slider value is now: {}", self.value); // Trigger saving the new value, perhaps? } ``` * **Dragging (`.dragged()`):** ```Rust if slider_response.dragged() { // Maybe show temporary feedback while dragging // ui.label("Dragging slider..."); } ``` **Key Idea:** You don't wait for events. In each `update`, you *ask* the widgets (via their `Response`) if an interaction just happened, and react immediately by changing state or drawing something different. ## VII. Organizing UI Layout (Enhanced Explanation) Arranging widgets makes your UI usable. `egui` offers simple tools [3]: * **Basic Layouts (`horizontal`, `vertical`):** * `ui.horizontal(|ui| { ... });` - Widgets side-by-side [5]. * `ui.vertical(|ui| { ... });` - Widgets top-to-bottom [5]. * You can **nest** these (e.g., vertical list of horizontal rows). * **Panels (`TopBottomPanel`, `SidePanel`, `CentralPanel`):** * Divide your window into fixed areas (top/bottom/left/right) or the main central area [1]. * Define panels *before* `CentralPanel` in `update`. * **Grouping (`ui.group`, `ui.collapsing`):** * `ui.group(|ui| { ... });` - Draws a box around items [5]. * `ui.collapsing("Header", |ui| { ... });` - Clickable header to show/hide content [3]. * **Alignment (`ui.vertical_centered`, `Layout::right_to_left`):** * Helpers to center items or change layout direction. * **Grids (`egui::Grid`):** * Perfect for forms! Aligns items in columns. * Use `ui.end_row()` after adding widgets for each row. * **Menus (`egui::menu::bar`, `ui.menu_button`):** * Helpers for creating menu bars, usually in a `TopBottomPanel`. Let's see a combined layout (using the full `MyApp` struct from Section V): ```Rust // This replaces the `impl eframe::App for MyApp` block entirely impl eframe::App for MyApp { fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) { // --- Top Panel: Menu Bar --- egui::TopBottomPanel::top("menu_bar").show(ctx, |ui| { egui::menu::bar(ui, |ui| { // Use the menu bar layout helper // File Menu ui.menu_button("File", |ui| { // Creates "File" button with dropdown if ui.button("Reset Counter").clicked() { self.counter = 0; } if ui.button("Quit").clicked() { // Send command to close the window ctx.send_viewport_cmd(egui::ViewportCommand::Close); } }); // End File Menu dropdown // Mode Menu ui.menu_button("Mode", |ui| { // Creates "Mode" button with dropdown // Use radio buttons to change mode, close menu on click if ui.radio_value(&mut self.current_mode, AppMode::View, "View").clicked() { ui.close_menu(); } if ui.radio_value(&mut self.current_mode, AppMode::Edit, "Edit").clicked() { ui.close_menu(); } if ui.radio_value(&mut self.current_mode, AppMode::Settings, "Settings").clicked() { ui.close_menu(); } }); // End Mode Menu dropdown // Display state on the right side of the menu bar ui.with_layout(egui::Layout::right_to_left(egui::Align::Center), |ui| { ui.label(format!("Counter: {}", self.counter)); // Show counter value }); // End right-aligned section }); // End menu bar }); // End Top Panel // --- Left Panel: Info / Tools --- egui::SidePanel::left("info_panel") .default_width(150.0) // Set a default width .show(ctx, |ui| { ui.heading("Info Panel"); ui.separator(); // Visual dividing line ui.label(format!("Selected: {:?}", self.selected_color)); ui.separator(); if ui.button("Reset Label Text").clicked() { self.label = String::default(); // Reset to empty string } ui.separator(); // Add some spacing at the bottom ui.allocate_space(ui.available_size()); }); // End Side Panel // --- Central Panel: Main Content (Changes based on Mode) --- egui::CentralPanel::default().show(ctx, |ui| { ui.heading(format!("Current Mode: {:?}", self.current_mode)); ui.separator(); // Use `match` to show different UI based on `self.current_mode` match self.current_mode { // --- VIEW MODE UI --- AppMode::View => { ui.heading("VIEW DATA"); // Use a group to visually contain the data ui.group(|ui|{ ui.label(format!("Label: {}", self.label)); ui.label(format!("Value: {:.1}", self.value)); // Format float to 1 decimal place }); // End group // Show more details only if the checkbox in settings is ticked if self.show_extra_info { // Use a collapsing header for optional info ui.collapsing("Show More Details", |ui| { ui.label(format!("Counter: {}", self.counter)); ui.label(format!("Color Choice: {:?}", self.selected_color)); }); } else { ui.label("(Enable 'Show Advanced Info' in Settings)"); } } // End View Mode Arm // --- EDIT MODE UI --- AppMode::Edit => { ui.heading("EDIT DATA"); // Use a Grid for aligned form elements egui::Grid::new("edit_grid") .num_columns(2) // Define 2 columns .spacing([20.0, 8.0]) // Horizonal & vertical spacing .striped(true) // Alternating row backgrounds .show(ui, |ui| { // Add content row by row ui.label("Edit Label:"); // Column 1, Row 1 ui.text_edit_singleline(&mut self.label); // Column 2, Row 1 ui.end_row(); // MUST call end_row() to finish the row ui.label("Adjust Value:"); // Column 1, Row 2 ui.add(egui::Slider::new(&mut self.value, 0.0..=10.0)); // Column 2, Row 2 ui.end_row(); ui.label("Counter:"); // Column 1, Row 3 ui.horizontal(|ui|{ // Nested horizontal layout in Col 2, Row 3 if ui.button("+").clicked() { self.counter += 1; } ui.label(format!("{}", self.counter)).highlight(); // Highlight the number if ui.button("-").clicked() { self.counter -= 1; } }); ui.end_row(); }); // End Grid } // End Edit Mode Arm // --- SETTINGS MODE UI --- AppMode::Settings => { ui.heading("SETTINGS"); // Use a Group for visual structure ui.group(|ui|{ ui.checkbox(&mut self.show_extra_info, "Show Advanced Info in View"); ui.separator(); // Line separator within the group ui.label("Color Scheme:"); ui.horizontal(|ui| { // Radio buttons side-by-side ui.radio_value(&mut self.selected_color, ColorChoice::Red, "Red"); ui.radio_value(&mut self.selected_color, ColorChoice::Green, "Green"); ui.radio_value(&mut self.selected_color, ColorChoice::Blue, "Blue"); }); // End horizontal layout }); // End group ui.separator(); // Separator between group and button // Add a button to reset ALL state back to defaults if ui.button("Reset All State").clicked() { *self = MyApp::default(); // Replace current state with default values // Optional: Stay in settings mode after reset // self.current_mode = AppMode::Settings; } } // End Settings Mode Arm } // End match self.current_mode }); // End CentralPanel } // End update fn } // End impl eframe::App ``` **Key Layout Ideas:** * Use Panels for overall structure (Menu, Side, Central). * Use `horizontal`/`vertical` for basic flow inside panels/groups. * Use `Grid` for forms needing aligned columns. * Use `group`/`collapsing` to organize related items visually. * Nest layouts as needed! ## VIII. State Management (Enhanced Explanation) This is super important for `egui`! * **Your `struct MyApp` is King:** It holds all the data (`label`, `value`, `counter`, `current_mode`, etc.) [1, 2]. This is the **single source of truth**. * **`update` Reads State:** Each frame, `ui.label(format!("{}", self.counter))` reads the *current* `self.counter` value to display it [1, 4]. * **Interactions Write State:** `if ui.button("+").clicked() { self.counter += 1; }` *directly changes* `self.counter` when the button is clicked [4]. `ui.text_edit_singleline(&mut self.label)` *directly changes* `self.label` as you type. * **UI Updates Automatically:** Because `update` runs every frame and always reads the *latest* state from `self`, the UI instantly reflects any changes made in the previous frame [4]. **Example: Changing Modes** 1. `self.current_mode` holds the state (`View`, `Edit`, or `Settings`). 2. The `match self.current_mode { ... }` block reads this state. 3. Based on the state, *different UI code runs*, showing the View, Edit, or Settings widgets. 4. Clicking a mode radio button (`ui.radio_value(&mut self.current_mode, ...`) *directly changes* the `self.current_mode` field. 5. On the *very next frame*, the `match` expression reads the *new* mode and instantly shows the corresponding UI. **Resetting State:** The `*self = MyApp::default();` line is a simple way to reset everything. * `MyApp::default()` creates a *brand new* struct instance with default values. * `*self = ...` assigns this new instance over the memory of the old `self`, effectively replacing it. **Slow Tasks (Reminder):** Don't do slow things (like file downloads) directly in `update`! Use threads and communicate back using channels or shared state, checking for results without blocking `update` [2]. ## IX. Advanced Features Once you master the basics, `egui` offers more [3]: * **Custom Panels:** Design your own panel types [1, 3]. * **Game Engine Integration:** Use `egui` inside games (e.g., with `bevy_egui`) [1, 3]. * **Dynamic UI:** Use `if`, `match`, and loops (`for item in &self.items { ... }`) to build UI based on data. * **More Widgets:** Explore `egui_extras` (tables, images) and other community crates [1]. * **Custom Widgets:** Build your own reusable UI elements. * **Context Menus:** Add right-click menus easily (`response.context_menu(...)`). * **Drag and Drop:** Handle file drops or item dragging. * **Debugging Tools:** * `ctx.set_debug_on_hover(true);` - Hover to see widget bounds/IDs [1]. * `egui::Window::new("Debug").show(ctx, |ui| { ctx.inspection_ui(ui); });` - Show detailed debug info window. ## X. Best Practices Tips for good `egui` code [1]: 1. **Keep Logic Out of `update`:** Put complex calculations in separate functions. Let `update` *call* those functions based on interactions, but keep `update` itself focused on drawing and simple state changes [1]. 2. **Organize State:** Keep your `MyApp` struct tidy. For very complex apps, group related state into smaller structs within `MyApp`. 3. **Use Debug Tools:** They save *a lot* of time when layouts or interactions misbehave [1]. 4. **Think Readability:** Structure your `update` function clearly. Use comments. Break down very complex UI sections into helper functions if needed. 5. **Accessibility:** Use clear labels. Check if `eframe` or your integration supports accessibility features like AccessKit [2]. ## XI. Further Learning & Resources Ready for more? Check these out [2, 5, 1, 3]: * **Official Docs:** [docs.rs/egui](https://docs.rs/egui) [5] * **Web Demo & Examples:** [www.egui.rs](https://www.egui.rs/) [2] * **GitHub Repo:** [github.com/emilk/egui](https://github.com/emilk/egui) (Source code, discussions, more examples!) [2] * **`eframe` Template:** [github.com/emilk/eframe_template](https://github.com/emilk/eframe_template) (Quick start project) [5] * **Game Dev:** `bevy_egui` [github.com/mvlabat/bevy_egui](https://github.com/mvlabat/bevy_egui) [3] * **Community:** GitHub Discussions, Discord servers. * **Extra Widgets:** `egui_extras` [crates.io/crates/egui_extras](https://crates.io/crates/egui_extras) [1] * **"Awesome egui" Lists:** Search for curated lists of helpful `egui` crates. ## XII. Conclusion `egui` makes GUI development in Rust surprisingly simple and fun! Its immediate mode approach often leads to cleaner code by keeping state management straightforward [1, 2]. Plus, it runs everywhere (desktop and web) [1, 3]. You've learned the essentials: setup, the `update` loop, state handling (`MyApp`), adding widgets, responding to clicks/hovers, organizing layouts, and even switching UI views based on state. The best way forward? **Build things!** Start simple, modify the examples, try adding features. `egui` gives fast feedback, making experimentation easy. Enjoy creating interactive Rust applications! Happy coding! ---