Expand description
eframe - the egui
framework crate
If you are planning to write an app for web or native,
and want to use egui
for everything, then eframe
is for you!
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!
In short, you implement App
(especially App::update
) and then
call crate::run_native
from your main.rs
, and/or call eframe::start_web
from your lib.rs
.
Usage, native:
use eframe::egui;
fn main() {
let native_options = eframe::NativeOptions::default();
eframe::run_native("My egui App", native_options, Box::new(|cc| Box::new(MyEguiApp::new(cc))));
}
#[derive(Default)]
struct MyEguiApp {}
impl MyEguiApp {
fn new(cc: &eframe::CreationContext<'_>) -> Self {
// Customize egui here with cc.egui_ctx.set_fonts and cc.egui_ctx.set_visuals.
// Restore app state using cc.storage (requires the "persistence" feature).
// Use the cc.gl (a glow::Context) to create graphics shaders and buffers that you can use
// for e.g. egui::PaintCallback.
Self::default()
}
}
impl eframe::App for MyEguiApp {
fn update(&mut self, ctx: &egui::Context, frame: &mut eframe::Frame) {
egui::CentralPanel::default().show(ctx, |ui| {
ui.heading("Hello World!");
});
}
}
Usage, web:
use wasm_bindgen::prelude::*;
/// Your handle to the web app from JavaScript.
#[derive(Clone)]
#[wasm_bindgen]
pub struct WebHandle {
runner: WebRunner,
}
#[wasm_bindgen]
impl WebHandle {
/// Installs a panic hook, then returns.
#[allow(clippy::new_without_default)]
#[wasm_bindgen(constructor)]
pub fn new() -> Self {
// Redirect [`log`] message to `console.log` and friends:
eframe::WebLogger::init(log::LevelFilter::Debug).ok();
Self {
runner: WebRunner::new(),
}
}
/// Call this once from JavaScript to start your app.
#[wasm_bindgen]
pub async fn start(&self, canvas_id: &str) -> Result<(), wasm_bindgen::JsValue> {
self.runner
.start(
canvas_id,
eframe::WebOptions::default(),
Box::new(|cc| Box::new(MyEguiApp::new(cc))),
)
.await
}
// The following are optional:
#[wasm_bindgen]
pub fn destroy(&self) {
self.runner.destroy();
}
/// Example on how to call into your app from JavaScript.
#[wasm_bindgen]
pub fn example(&self) {
if let Some(app) = self.runner.app_mut::<MyEguiApp>() {
app.example();
}
}
/// The JavaScript can check whether or not your app has crashed:
#[wasm_bindgen]
pub fn has_panicked(&self) -> bool {
self.runner.has_panicked()
}
#[wasm_bindgen]
pub fn panic_message(&self) -> Option<String> {
self.runner.panic_summary().map(|s| s.message())
}
#[wasm_bindgen]
pub fn panic_callstack(&self) -> Option<String> {
self.runner.panic_summary().map(|s| s.callstack())
}
}
Simplified usage
If your app is only for native, and you don’t need advanced features like state persistence,
then you can use the simpler function run_simple_native
.
Feature flags
-
accesskit
(enabled by default) — Enable platform accessibility API implementations through AccessKit. -
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. -
glow
(enabled by default) — Useglow
for painting, viaegui_glow
. -
wayland
— Enables wayland support and fixes clipboard issue. -
persistence
— Enable saving app state to disk. -
puffin
— Enable profiling with thepuffin
crate.Only enabled on native, because of the low resolution (1ms) of time keeping in browsers.
eframe
will callpuffin::GlobalProfiler::lock().new_frame()
for you -
web_screen_reader
— Enable screen reader support (requiresctx.options_mut(|o| o.screen_reader = true);
) on web.For other platforms, use the “accesskit” feature instead.
-
__screenshot
— If set, eframe will look for the env-varEFRAME_SCREENSHOT_TO
and write a screenshot to that location, and then quit. This is used to generate images for the examples. -
wgpu
— Usewgpu
for painting (viaegui-wgpu
). This overrides theglow
feature. -
android-native-activity
— Enable thenative-activity
backend viaegui-winit
on Android -
android-game-activity
— Enable thegame-activity
backend viaegui-winit
on Android
Optional dependencies
document-features
— Enable this when generating docs.
Re-exports
pub use egui;
pub use egui::emath;
pub use egui::epaint;
pub use egui_glow;
pub use glow;
pub use egui_wgpu;
pub use wgpu;
Structs
- Data that is passed to
AppCreator
that can be used to setup and initialize your app. - Object that allows building the event loop.
- Represents the surroundings of your app.
- Image data for an application icon.
- Information about the integration passed to the use app each frame.
- Options controlling the behavior of a native window.
- Information about the application’s main window, if available.
Enums
- The different problems that can occur when trying to run
eframe
. - Selects the level of hardware graphics acceleration.
- What rendering backend to use.
- Dark or Light theme.
- WebGL Context options
Constants
Storage
key used for app
Traits
- Implement this trait to write apps that can be compiled for both web/wasm and desktop/native using
eframe
. - A place where you can store custom data in a way that persists when you restart the app.
Functions
- Get and deserialize the RON stored at the given key.
- This is how you start a native (desktop) app.
- The simplest way to get started when writing a native app.
- Serialize the given value as RON and store with the given key.
Type Definitions
- This is how your app is created.
- Hook into the building of an event loop before it is run