diff --git a/Cargo.lock b/Cargo.lock index 767c8932..7d868720 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1904,6 +1904,7 @@ name = "hello_world" version = "0.1.0" dependencies = [ "eframe", + "egui_extras", "env_logger", ] diff --git a/README.md b/README.md index 03d39b94..dfc1916d 100644 --- a/README.md +++ b/README.md @@ -9,30 +9,24 @@ [![Apache](https://img.shields.io/badge/license-Apache-blue.svg)](https://github.com/emilk/egui/blob/master/LICENSE-APACHE) [![Discord](https://img.shields.io/discord/900275882684477440?label=egui%20discord)](https://discord.gg/JFcEma9bJq) + +
+ + +egui development is sponsored by [Rerun](https://www.rerun.io/), a startup doing
+visualizations for computer vision and robotics. +
+ +--- + 👉 [Click to run the web demo](https://www.egui.rs/#demo) 👈 -egui (pronounced "e-gooey") is a simple, fast, and highly portable immediate mode GUI library for Rust. egui runs on the web, natively, and [in your favorite game engine](#integrations) (or will soon). +egui (pronounced "e-gooey") is a simple, fast, and highly portable immediate mode GUI library for Rust. egui runs on the web, natively, and [in your favorite game engine](#integrations). egui aims to be the easiest-to-use Rust GUI library, and the simplest way to make a web app in Rust. egui can be used anywhere you can draw textured triangles, which means you can easily integrate it into your game engine of choice. -Sections: - -* [Example](#example) -* [Quick start](#quick-start) -* [Demo](#demo) -* [Goals](#goals) -* [Who is egui for?](#who-is-egui-for) -* [State / features](#state) -* [Integrations](#integrations) -* [Why immediate mode](#why-immediate-mode) -* [FAQ](#faq) -* [Other](#other) -* [Credits](#credits) - -([egui 的中文翻译文档 / chinese translation](https://github.com/Re-Ch-Love/egui-doc-cn/blob/main/README_zh-hans.md)) - ## Example ``` rust @@ -46,10 +40,29 @@ if ui.button("Click each year").clicked() { age += 1; } ui.label(format!("Hello '{name}', age {age}")); +ui.image(egui::include_image!("ferris.png")); ``` +## Sections: + +* [Example](#example) +* [Quick start](#quick-start) +* [Demo](#demo) +* [Goals](#goals) +* [State / features](#state) +* [Dependencies](#dependencies) +* [Who is egui for?](#who-is-egui-for) +* [Integrations](#integrations) +* [Why immediate mode](#why-immediate-mode) +* [FAQ](#faq) +* [Other](#other) +* [Credits](#credits) + +([egui 的中文翻译文档 / chinese translation](https://github.com/Re-Ch-Love/egui-doc-cn/blob/main/README_zh-hans.md)) + + ## Quick start There are simple examples in [the `examples/` folder](https://github.com/emilk/egui/blob/master/examples/). If you want to write a web app, then go to and follow the instructions. The official docs are at . For inspiration and more examples, check out the [the egui web demo](https://www.egui.rs/#demo) and follow the links in it to its source code. @@ -99,6 +112,32 @@ egui is *not* a framework. egui is a library you call into, not an environment y * Native looking interface * Advanced and flexible layouts (that's fundamentally incompatible with immediate mode) +## State + +egui is in active development. It works well for what it does, but it lacks many features and the interfaces are still in flux. New releases will have breaking changes. + +Still, egui can be used to create professional looking applications, like [the Rerun Viewer](https://app.rerun.io/). + +### Features + +* Widgets: label, text button, hyperlink, checkbox, radio button, slider, draggable value, text editing, combo box, color picker, spinner +* Images +* Layouts: horizontal, vertical, columns, automatic wrapping +* Text editing: multiline, copy/paste, undo, emoji supports +* Windows: move, resize, name, minimize and close. Automatically sized and positioned. +* Regions: resizing, vertical scrolling, collapsing headers (sections) +* Rendering: Anti-aliased rendering of lines, circles, text and convex polygons. +* Tooltips on hover +* Accessibility via [AccessKit](https://accesskit.dev/) +* More + + + +Light Theme: + + + + ## Dependencies `egui` has a minimal set of default dependencies: @@ -142,27 +181,6 @@ So in summary: * egui: pure Rust, new, exciting, work in progress * Dear ImGui: feature rich, well tested, cumbersome Rust integration -## State - -egui is in active development. It works well for what it does, but it lacks many features and the interfaces are still in flux. New releases will have breaking changes. - -### Features - -* Widgets: label, text button, hyperlink, checkbox, radio button, slider, draggable value, text editing, combo box, color picker -* Layouts: horizontal, vertical, columns, automatic wrapping -* Text editing: multiline, copy/paste, undo, emoji supports -* Windows: move, resize, name, minimize and close. Automatically sized and positioned. -* Regions: resizing, vertical scrolling, collapsing headers (sections) -* Rendering: Anti-aliased rendering of lines, circles, text and convex polygons. -* Tooltips on hover -* More - - - -Light Theme: - - - ## Integrations egui is built to be easy to integrate into any existing game engine or platform you are working on. @@ -255,7 +273,7 @@ For "atomic" widgets (e.g. a button) `egui` knows the size before showing it, so #### CPU usage Since an immediate mode GUI does a full layout each frame, the layout code needs to be quick. If you have a very complex GUI this can tax the CPU. In particular, having a very large UI in a scroll area (with very long scrollback) can be slow, as the content needs to be laid out each frame. -If you design the GUI with this in mind and refrain from huge scroll areas (or only lay out the part that is in view) then the performance hit is generally pretty small. For most cases you can expect `egui` to take up 1-2 ms per frame, but `egui` still has a lot of room for optimization (it's not something I've focused on yet). You can also set up `egui` to only repaint when there is interaction (e.g. mouse movement). +If you design the GUI with this in mind and refrain from huge scroll areas (or only lay out the part that is in view) then the performance hit is generally pretty small. For most cases you can expect `egui` to take up 1-2 ms per frame, but `egui` still has a lot of room for optimization (it's not something I've focused on yet). `egui` only repaints when there is interaction (e.g. mouse movement) or an animation, so if your app is idle, no CPU is wasted. If your GUI is highly interactive, then immediate mode may actually be more performant compared to retained mode. Go to any web page and resize the browser window, and you'll notice that the browser is very slow to do the layout and eats a lot of CPU doing it. Resize a window in `egui` by contrast, and you'll get smooth 60 FPS at no extra CPU cost. @@ -278,6 +296,8 @@ Yes! But you need to install your own font (`.ttf` or `.otf`) using `Context::se ### Can I customize the look of egui? Yes! You can customize the colors, spacing, fonts and sizes of everything using `Context::set_style`. +This is not yet as powerful as say CSS, [but this is going to improve soon](https://github.com/emilk/egui/issues/3284). + Here is an example (from https://github.com/AlexxxRu/TinyPomodoro): @@ -286,7 +306,7 @@ Here is an example (from https://github.com/AlexxxRu/TinyPomodoro): If you call `.await` in your GUI code, the UI will freeze, which is very bad UX. Instead, keep the GUI thread non-blocking and communicate with any concurrent tasks (`async` tasks or other threads) with something like: * Channels (e.g. [`std::sync::mpsc::channel`](https://doc.rust-lang.org/std/sync/mpsc/fn.channel.html)). Make sure to use [`try_recv`](https://doc.rust-lang.org/std/sync/mpsc/struct.Receiver.html#method.try_recv) so you don't block the gui thread! * `Arc>` (background thread sets a value; GUI thread reads it) -* [`poll_promise::Promise`](https://docs.rs/poll-promise) (example: [`examples/download_image/`](https://github.com/emilk/egui/blob/master/examples/download_image/)) +* [`poll_promise::Promise`](https://docs.rs/poll-promise) * [`eventuals::Eventual`](https://docs.rs/eventuals/latest/eventuals/struct.Eventual.html) * [`tokio::sync::watch::channel`](https://docs.rs/tokio/latest/tokio/sync/watch/fn.channel.html) @@ -385,7 +405,7 @@ Default fonts: ---
- + egui development is sponsored by [Rerun](https://www.rerun.io/), a startup doing
visualizations for computer vision and robotics. diff --git a/examples/hello_world/Cargo.toml b/examples/hello_world/Cargo.toml index b960dcfb..a3ae0ea7 100644 --- a/examples/hello_world/Cargo.toml +++ b/examples/hello_world/Cargo.toml @@ -12,4 +12,8 @@ publish = false eframe = { path = "../../crates/eframe", features = [ "__screenshot", # __screenshot is so we can dump a screenshot using EFRAME_SCREENSHOT_TO ] } + +# For image support: +egui_extras = { path = "../../crates/egui_extras", features = ["image"] } + env_logger = "0.10" diff --git a/examples/hello_world/src/main.rs b/examples/hello_world/src/main.rs index 47c045db..4a64a3be 100644 --- a/examples/hello_world/src/main.rs +++ b/examples/hello_world/src/main.rs @@ -11,7 +11,12 @@ fn main() -> Result<(), eframe::Error> { eframe::run_native( "My egui App", options, - Box::new(|_cc| Box::::default()), + Box::new(|cc| { + // This gives us image support: + egui_extras::install_image_loaders(&cc.egui_ctx); + + Box::::default() + }), ) } @@ -43,6 +48,10 @@ impl eframe::App for MyApp { self.age += 1; } ui.label(format!("Hello '{}', age {}", self.name, self.age)); + + ui.image(egui::include_image!( + "../../../crates/egui/assets/ferris.png" + )); }); } } diff --git a/examples/images/src/main.rs b/examples/images/src/main.rs index 87a680d1..5c1c6a4e 100644 --- a/examples/images/src/main.rs +++ b/examples/images/src/main.rs @@ -12,7 +12,7 @@ fn main() -> Result<(), eframe::Error> { "Image Viewer", options, Box::new(|cc| { - // The following call is needed to load images when using `ui.image` and `egui::Image`: + // This gives us image support: egui_extras::install_image_loaders(&cc.egui_ctx); Box::::default() }), diff --git a/media/demo.gif b/media/demo.gif index 2cff5878..385c8228 100644 Binary files a/media/demo.gif and b/media/demo.gif differ diff --git a/media/widget_gallery_0.23.gif b/media/widget_gallery_0.23.gif new file mode 100644 index 00000000..66663107 Binary files /dev/null and b/media/widget_gallery_0.23.gif differ diff --git a/media/widget_gallery_0.23_light.png b/media/widget_gallery_0.23_light.png new file mode 100644 index 00000000..a975f97c Binary files /dev/null and b/media/widget_gallery_0.23_light.png differ