6f2f006885
* Closes https://github.com/emilk/egui/issues/1918 * Closes https://github.com/emilk/egui/issues/4437 * Closes https://github.com/emilk/egui/issues/4709 * [x] I have followed the instructions in the PR template Hiya, I need new winit for a specific fix for a android_native_actvity. There are already two PRs, but both don't seem to have a lot of movement, or are entirely complete: https://github.com/emilk/egui/pull/4466 Seems to have gone stale & is missing some bits. https://github.com/emilk/egui/pull/4702 Also seems stale (if less so), and is missing a refactor to run_on_demand. I also *think* the accesskit integration has a mistake and can't be enabled. I've marked them as a co-author on this as I started from this branch. (I think! Haven't done that on git before...). Sorry for the wall of text but just dumping some details / thoughts here: - There's an issue with creating child windows in winit 0.30.1 and up on macOS. The multiple_viewports, "create immediate viewport" example crashes on anything later 0.30.1, with a stack overflow in unsafe code. I've create [a winit issue](https://github.com/rust-windowing/winit/issues/3800), it *might* already be fixed in 0.31.0 but I can't test as 0.31 will likely require another refactoring. For now I have just pinned things to 0.30.0 exatly. - Winit has deprecated run_on_demand, instead requiring the ApplicationHandler interface. In 0.31.0 run_on_demand is removed. I've refactored both the integration and the WinitApp trait to follow this pattern. I've left user_events a bit more opaque, as it seems 0.31.0 is doing a rework of UserEvents too. - I've used the new lazy init approach for access kit from this branch https://github.com/mwcampbell/egui/tree/accesskit-new-lazy-init and marked Matt as co-author, thanks Matt! - There was very similair but not quite the same code for run_and_return and run_and_exit. I've merged them, but looking at the github issues graveyard it seems vey finnicky. I *hope* this is more robust than before but it's a bit scary. - when receiving new_events this also used to check the redraw timing dictionary. That doesn't seem necesarry so left this out, but that is a slight behaviour change? - I have reeneabled serial_windows on macOS. I wondered whether it was fixed after this PR and does seem to be! However, even before this PR it seems to work, so maybe winit has sorted things out before that... Windows also works fine now without the extra hack. - I've done a very basic test of AccessKit on Windows and screen reader seems ok but I'm really not knowleadgable enough to say whether it's all good or not. - I've tested cargo tests & all examples on Windows & macOS, and ran a basic Android app. Still, testing native platforms is wel... hard so if anyone can test linux / iOs / older mac versions / windows 10 would probably be a good idea! - For consistencys sake I've made all event like functions in WinitApp return a `Result<EventResult>`. There's quite a bit of Ok-wrapping now, maybe too annoying? Not sure. Thank you for having a look! # Tested on * [x] macOS * [x] Windows * [x] Wayland (thanks [SiebenCorgie](https://github.com/SiebenCorgie)) * [x] X11 (thanks [crumblingstatue](https://github.com/crumblingstatue)!, [SiebenCorgie](https://github.com/SiebenCorgie)) # TODO * [x] Fix "follow system theme" not working on initial startup (winit issue, pinning to 0.30.2 for now). * [x] Fix `request_repaint_after` --------- Co-authored-by: mwcampbell <mattcampbell@pobox.com> Co-authored-by: j-axa <josef.axa@gmail.com> Co-authored-by: DataTriny <datatriny@gmail.com> Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com> |
||
|---|---|---|
| .. | ||
| data | ||
| src | ||
| CHANGELOG.md | ||
| Cargo.toml | ||
| README.md | ||
README.md
eframe: the egui framework
eframe is the official framework library for writing apps using egui. The app can be compiled both to run natively (for Linux, Mac, Windows, and Android) or as a web app (using Wasm).
To get started, see the examples.
To learn how to set up eframe for web and native, go to https://github.com/emilk/eframe_template/ and follow the instructions there!
There is also a tutorial video at https://www.youtube.com/watch?v=NtUkr_z7l84.
For how to use egui, see the egui docs.
eframe uses egui_glow for rendering, and on native it uses egui-winit.
To use on Linux, first run:
sudo apt-get install libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev libssl-dev
You need to either use edition = "2021", or set resolver = "2" in the [workspace] section of your to-level Cargo.toml. See this link for more info.
You can opt-in to the using egui_wgpu for rendering by enabling the wgpu feature and setting NativeOptions::renderer to Renderer::Wgpu.
To get copy-paste working on web, you need to compile with export RUSTFLAGS=--cfg=web_sys_unstable_apis.
Alternatives
eframe is not the only way to write an app using egui! You can also try egui-miniquad, bevy_egui, egui_sdl2_gl, and others.
You can also use egui_glow and winit to build your own app as demonstrated in https://github.com/emilk/egui/blob/master/crates/egui_glow/examples/pure_glow.rs.
Limitations when running egui on the web
eframe uses WebGL (via glow) and Wasm, and almost nothing else from the web tech stack. This has some benefits, but also produces some challenges and serious downsides.
- Rendering: Getting pixel-perfect rendering right on the web is very difficult.
- Search: you cannot search an egui web page like you would a normal web page.
- Bringing up an on-screen keyboard on mobile: there is no JS function to do this, so
eframefakes it by adding some invisible DOM elements. It doesn't always work. - Mobile text editing is not as good as for a normal web app.
- No integration with browser settings for colors and fonts.
- Accessibility: There is an experimental screen reader for
eframe, but it has to be enabled explicitly. There is no JS function to ask "Does the user want a screen reader?" (and there should probably not be such a function, due to user tracking/integrity concerns).eguisupports AccessKit, but as of early 2024, AccessKit lacks a Web backend.
In many ways, eframe is trying to make the browser do something it wasn't designed to do (though there are many things browser vendors could do to improve how well libraries like egui work).
The suggested use for eframe are for web apps where performance and responsiveness are more important than accessibility and mobile text editing.
Companion crates
Not all rust crates work when compiled to Wasm, but here are some useful crates have been designed to work well both natively and as Wasm:
Name
The frame in eframe stands both for the frame in which your egui app resides and also for "framework" (eframe is a framework, egui is a library).