Expand description
egui
: an easy-to-use GUI in pure Rust!
Try the live web demo: https://www.egui.rs/#demo. Read more about egui at https://github.com/emilk/egui.
egui
is in heavy development, with each new version having breaking changes.
You need to have rust 1.62.0 or later to use egui
.
To quickly get started with egui, you can take a look at eframe_template
which uses eframe
.
To create a GUI using egui you first need a Context
(by convention referred to by ctx
).
Then you add a Window
or a SidePanel
to get a Ui
, which is what you’ll be using to add all the buttons and labels that you need.
Feature flags
-
accesskit
— Exposes detailed accessibility implementation required by platform accessibility APIs. Also requires support in the egui integration. -
bytemuck
—bytemuck
enables you to castepaint::Vertex
,emath::Vec2
etc to&[u8]
. -
callstack
— Show a debug-ui on hover including the stacktrace to the hovered item. This is very useful in finding the code that creates a part of the UI. Does not work on web. -
cint
—cint
enables interoperability with other color libraries. -
color-hex
— Enable thehex_color
macro. -
deadlock_detection
— This will automatically detect deadlocks due to double-locking on the same thread. If your app freezes, you may want to enable this! Only affectsepaint::mutex::RwLock
(which egui uses a lot). -
default_fonts
(enabled by default) — If set, egui will useinclude_bytes!
to bundle some fonts. If you plan on specifying your own fonts you may disable this feature. -
extra_debug_asserts
— Enable additional checks if debug assertions are enabled (debug builds). -
extra_asserts
— Always enable additional checks. -
log
— Turn on thelog
feature, that makes egui log some errors using thelog
crate. -
mint
—mint
enables interoperability with other math libraries such asglam
andnalgebra
. -
persistence
— Enable persistence of memory (window positions etc). -
puffin
— Enable profiling with thepuffin
crate.Only enabled on native, because of the low resolution (1ms) of clocks in browsers.
-
serde
— Allow serialization usingserde
. -
unity
— Change Vertex layout to be compatible with unity
Optional dependencies
document-features
— Enable this when generating docs.
Using egui
To see what is possible to build with egui you can check out the online demo at https://www.egui.rs/#demo.
If you like the “learning by doing” approach, clone https://github.com/emilk/eframe_template and get started using egui right away.
A simple example
Here is a simple counter that can be incremented and decremented using two buttons:
fn ui_counter(ui: &mut egui::Ui, counter: &mut i32) {
// Put the buttons and label on the same row:
ui.horizontal(|ui| {
if ui.button("−").clicked() {
*counter -= 1;
}
ui.label(counter.to_string());
if ui.button("+").clicked() {
*counter += 1;
}
});
}
In some GUI frameworks this would require defining multiple types and functions with callbacks or message handlers,
but thanks to egui
being immediate mode everything is one self-contained function!
Getting a Ui
Use one of SidePanel
, TopBottomPanel
, CentralPanel
, Window
or Area
to
get access to an Ui
where you can put widgets. For example:
egui::CentralPanel::default().show(&ctx, |ui| {
ui.add(egui::Label::new("Hello World!"));
ui.label("A shorter and more convenient way to add a label.");
if ui.button("Click me").clicked() {
// take some action here
}
});
Quick start
ui.label("This is a label");
ui.hyperlink("https://github.com/emilk/egui");
ui.text_edit_singleline(&mut my_string);
if ui.button("Click me").clicked() { }
ui.add(egui::Slider::new(&mut my_f32, 0.0..=100.0));
ui.add(egui::DragValue::new(&mut my_f32));
ui.checkbox(&mut my_boolean, "Checkbox");
#[derive(PartialEq)]
enum Enum { First, Second, Third }
ui.horizontal(|ui| {
ui.radio_value(&mut my_enum, Enum::First, "First");
ui.radio_value(&mut my_enum, Enum::Second, "Second");
ui.radio_value(&mut my_enum, Enum::Third, "Third");
});
ui.separator();
ui.image((my_image, egui::Vec2::new(640.0, 480.0)));
ui.collapsing("Click to see what is hidden!", |ui| {
ui.label("Not much, as it turns out");
});
Coordinate system
The left-top corner of the screen is (0.0, 0.0)
,
with X increasing to the right and Y increasing downwards.
egui
uses logical points as its coordinate system.
Those related to physical pixels by the pixels_per_point
scale factor.
For example, a high-dpi screeen can have pixels_per_point = 2.0
,
meaning there are two physical screen pixels for each logical point.
Angles are in radians, and are measured clockwise from the X-axis, which has angle=0.
Integrating with egui
Most likely you are using an existing egui
backend/integration such as eframe
, bevy_egui
,
or egui-miniquad
,
but if you want to integrate egui
into a new game engine or graphics backend, this is the section for you.
You need to collect RawInput
and handle FullOutput
. The basic structure is this:
let mut ctx = egui::Context::default();
// Game loop:
loop {
let raw_input: egui::RawInput = gather_input();
let full_output = ctx.run(raw_input, |ctx| {
egui::CentralPanel::default().show(&ctx, |ui| {
ui.label("Hello world!");
if ui.button("Click me").clicked() {
// take some action here
}
});
});
handle_platform_output(full_output.platform_output);
let clipped_primitives = ctx.tessellate(full_output.shapes); // create triangles to paint
paint(full_output.textures_delta, clipped_primitives);
}
For a reference OpenGL renderer, see the egui_glow
painter.
Debugging your renderer
Things look jagged
- Turn off backface culling.
My text is blurry
- Make sure you set the proper
pixels_per_point
in the input to egui. - Make sure the texture sampler is not off by half a pixel. Try nearest-neighbor sampler to check.
My windows are too transparent or too dark
- egui uses premultiplied alpha, so make sure your blending function is
(ONE, ONE_MINUS_SRC_ALPHA)
. - Make sure your texture sampler is clamped (
GL_CLAMP_TO_EDGE
). - egui prefers linear color spaces for all blending so:
- Use an sRGBA-aware texture if available (e.g.
GL_SRGB8_ALPHA8
).- Otherwise: remember to decode gamma in the fragment shader.
- Decode the gamma of the incoming vertex colors in your vertex shader.
- Turn on sRGBA/linear framebuffer if available (
GL_FRAMEBUFFER_SRGB
).- Otherwise: gamma-encode the colors before you write them again.
- Use an sRGBA-aware texture if available (e.g.
Understanding immediate mode
egui
is an immediate mode GUI library.
Immediate mode has its roots in gaming, where everything on the screen is painted at the display refresh rate, i.e. at 60+ frames per second. In immediate mode GUIs, the entire interface is laid out and painted at the same high rate. This makes immediate mode GUIs especially well suited for highly interactive applications.
It is useful to fully grok what “immediate mode” implies.
Here is an example to illustrate it:
if ui.button("click me").clicked() {
take_action()
}
This code is being executed each frame at maybe 60 frames per second. Each frame egui does these things:
- lays out the letters
click me
in order to figure out the size of the button - decides where on screen to place the button
- check if the mouse is hovering or clicking that location
- chose button colors based on if it is being hovered or clicked
- add a
Shape::Rect
andShape::Text
to the list of shapes to be painted later this frame - return a
Response
with theclicked
member so the user can check for interactions
There is no button being created and stored somewhere.
The only output of this call is some colored shapes, and a Response
.
Similarly, consider this code:
ui.add(egui::Slider::new(&mut value, 0.0..=100.0).text("My value"));
Here egui will read value
(an f32
) to display the slider, then look if the mouse is dragging the slider and if so change the value
.
Note that egui
does not store the slider value for you - it only displays the current value, and changes it
by how much the slider has been dragged in the previous few milliseconds.
This means it is responsibility of the egui user to store the state (value
) so that it persists between frames.
It can be useful to read the code for the toggle switch example widget to get a better understanding of how egui works: https://github.com/emilk/egui/blob/master/crates/egui_demo_lib/src/demo/toggle_switch.rs.
Read more about the pros and cons of immediate mode at https://github.com/emilk/egui#why-immediate-mode.
Misc
How widgets works
if ui.button("click me").clicked() { take_action() }
is short for
let button = egui::Button::new("click me");
if ui.add(button).clicked() { take_action() }
which is short for
let button = egui::Button::new("click me");
let response = button.ui(ui);
if response.clicked() { take_action() }
Button
uses the builder pattern to create the data required to show it. The Button
is then discarded.
Button
implements trait
Widget
, which looks like this:
pub trait Widget {
/// Allocate space, interact, paint, and return a [`Response`].
fn ui(self, ui: &mut Ui) -> Response;
}
Auto-sizing panels and windows
In egui, all panels and windows auto-shrink to fit the content. If the window or panel is also resizable, this can lead to a weird behavior where you can drag the edge of the panel/window to make it larger, and when you release the panel/window shrinks again. This is an artifact of immediate mode, and here are some alternatives on how to avoid it:
- Turn off resizing with
Window::resizable
,SidePanel::resizable
,TopBottomPanel::resizable
. - Wrap your panel contents in a
ScrollArea
, or useWindow::vscroll
andWindow::hscroll
. - Use a justified layout:
ui.with_layout(egui::Layout::top_down_justified(egui::Align::Center), |ui| {
ui.button("I am becoming wider as needed");
});
- Fill in extra space with emptiness:
ui.allocate_space(ui.available_size()); // put this LAST in your panel/window code
Sizes
You can control the size of widgets using Ui::add_sized
.
ui.add_sized([40.0, 20.0], egui::DragValue::new(&mut my_value));
Code snippets
// Miscellaneous tips and tricks
ui.horizontal_wrapped(|ui| {
ui.spacing_mut().item_spacing.x = 0.0; // remove spacing between widgets
// `radio_value` also works for enums, integers, and more.
ui.radio_value(&mut some_bool, false, "Off");
ui.radio_value(&mut some_bool, true, "On");
});
ui.group(|ui| {
ui.label("Within a frame");
ui.set_min_height(200.0);
});
// A `scope` creates a temporary [`Ui`] in which you can change settings:
ui.scope(|ui| {
ui.visuals_mut().override_text_color = Some(egui::Color32::RED);
ui.style_mut().override_text_style = Some(egui::TextStyle::Monospace);
ui.style_mut().wrap = Some(false);
ui.label("This text will be red, monospace, and won't wrap to a new line");
}); // the temporary settings are reverted here
Re-exports
pub use layers::LayerId;
pub use layers::Order;
pub use load::SizeHint;
pub use style::FontSelection;
pub use style::Margin;
pub use style::Style;
pub use style::TextStyle;
pub use style::Visuals;
pub use widget_text::RichText;
pub use widget_text::WidgetText;
pub use accesskit;
pub use ahash;
pub use epaint;
pub use epaint::ecolor;
pub use epaint::emath;
pub use containers::*;
pub use widgets::*;
Modules
- Containers are pieces of the UI which wraps other pieces of UI. Examples:
Window
,ScrollArea
,Resize
,SidePanel
, etc. - Helpers for zooming the whole GUI of an app (changing
Context::pixels_per_point
. - Showing UI:s for egui/epaint types.
- Handles paint layers, i.e. how things are sometimes painted behind or in front of other things.
- Image loading
- Menu bar functionality (very basic so far).
- Helper module that adds extra checks when the
deadlock_detection
feature is turned on. - All the data egui returns to the backend at the end of each frame.
- The default egui fonts supports around 1216 emojis in total. Here are some of the most useful: ∞⊗⎗⎘⎙⏏⏴⏵⏶⏷ ⏩⏪⏭⏮⏸⏹⏺■▶📾🔀🔁🔃 ☀☁★☆☐☑☜☝☞☟⛃⛶✔ ↺↻⟲⟳⬅➡⬆⬇⬈⬉⬊⬋⬌⬍⮨⮩⮪⮫ ♡ 📅📆 📈📉📊 📋📌📎📤📥🔆 🔈🔉🔊🔍🔎🔗🔘 🕓🖧🖩🖮🖱🖴🖵🖼🗀🗁🗋🗐🗑🗙🚫❓
- egui theme (spacing, colors, etc).
- Miscellaneous tools used by the rest of egui.
Macros
- An assert that is only active when
egui
is compiled with theextra_asserts
feature or with theextra_debug_asserts
feature in debug builds. - Used to get a unique ID when implementing one of the loader traits:
BytesLoader::id
,ImageLoader::id
, andTextureLoader::id
. - Construct a
crate::Color32
from a hex RGB or RGBA string. - Include an image in the binary.
Structs
- Two-dimension alignment, e.g.
Align2::LEFT_TOP
. - A
Mesh
orPaintCallback
within a clip rectangle. - This format is used for space-efficient color representation (32 bits).
- A 2D RGBA color image in RAM.
- Your handle to egui.
- A file dropped into egui.
- Controls which events that a focused widget will have exclusive access to.
- A
.ttf
or.otf
file and a font face index. - Describes the font data and the sizes to use.
- How to select a sized font.
- A single-channel image designed for the font texture.
- Extra scale and vertical tweak to apply to all text of a certain font.
- What egui emits each frame from
crate::Context::run
. - Text that has been laid out, ready for painting.
- A simple grid layout.
- A file about to be dropped into egui.
- egui tracks widgets frame-to-frame using
Id
s. - Returned when we wrap some ui-code and want to return both the results of the inner function and the ui as a whole, e.g.:
- Input state that egui updates each frame.
- A keyboard shortcut, e.g.
Ctrl+Alt+W
. - The layout of a
Ui
, e.g. “vertical & centered”. - The data that egui persists between frames.
- Textured triangles in two dimensions.
- Names of different modifier keys.
- State of the modifier keys. These must be fed to egui.
- All you probably need to know about a multi-touch gesture.
- What URL to open, and how.
- Some global options that you can read and write.
- If you want to paint some 3D shapes inside an egui region, you can use this.
- Information passed along with
PaintCallback
(Shape::Callback
). - Helper to paint shapes and text to a specific region on a specific layer.
- The non-rendering part of what egui emits each frame.
- Mouse or touch state.
- A position on screen.
- Includive range of floats, i.e.
min..=max
, but more ergonomic thanRangeInclusive
. - What the integrations provides to egui at the start of each frame.
- A rectangular region of space.
- Information given to the backend about when it is time to repaint the ui.
- The result of adding a widget to a
Ui
. - 0-1 linear space
RGBA
color with premultiplied alpha. - How rounded the corners of things should be
- What sort of interaction is a widget sensitive to?
- Describes the width and color of a line.
- Formatting option for a section of text.
- Used to paint images.
- How the texture texels are filtered.
- What has been allocated and freed during the last period.
- this is a
u64
as values of this kind can always be obtained by hashing - Unique identification of a touch occurrence (finger or pen or …). A Touch ID is valid until the finger is lifted. A new ID is used for the next touch.
- This is what you use to place widgets.
- A vector has a direction and length. A
Vec2
is often used to represent a size. - Describes a widget such as a
crate::Button
or acrate::TextEdit
.
Enums
- left/center/right or top/center/bottom alignment for e.g. anchors and layouts.
- A mouse cursor icon.
- An input event generated by the integration.
- Font of unknown size.
- An image stored in RAM.
- Keyboard keys.
- The unit associated with the numeric value of a mouse wheel event
- Mouse button (or similar for touch input)
- A paint primitive such as a circle or a piece of text. Coordinates are all screen space points (not physical pixels).
- How the texture texels are filtered.
- What texture to use in a
Mesh
mesh. - In what phase a touch event is in.
- Types of attention to request from a user when a native window is not in focus.
- The different types of built-in widgets in egui
Constants
- Number of pointer buttons supported by egui, i.e. the number of possible states of
PointerButton
.
Traits
Functions
- For use in tests; especially doctests.
- For use in tests; especially doctests.
- Linear interpolation.
pos2(x, y) == Pos2::new(x, y)
- Linearly remap a value from one range to another, so that when
x == from.start()
returnsto.start()
and whenx == from.end()
returnsto.end()
. - Like
remap
, but also clamps the value so that the returned value is always in theto
range. vec2(x, y) == Vec2::new(x, y)
- Helper function that adds a label when compiling with debug assertions enabled.
Type Aliases
IdMap<V>
is aHashMap<Id, V>
optimized by knowing thatId
has good entropy, and doesn’t need more hashing.