//! Backend-agnostic interface for writing apps using Egui. //! //! Egui is a GUI library, which can be plugged in to e.g. a game engine. //! //! This crate provides a common interface for programming an app, using Egui, //! so you can then easily plug it in to a backend such as `egui_web` or `egui_glium`. //! //! This crate is primarily used by the `egui_web` and `egui_glium` crates. #![cfg_attr(not(debug_assertions), deny(warnings))] // Forbid warnings in release builds #![forbid(unsafe_code)] #![warn( clippy::all, clippy::await_holding_lock, clippy::dbg_macro, clippy::doc_markdown, clippy::empty_enum, clippy::enum_glob_use, clippy::exit, clippy::filter_map_next, clippy::fn_params_excessive_bools, clippy::if_let_mutex, clippy::imprecise_flops, clippy::inefficient_to_string, clippy::linkedlist, clippy::lossy_float_literal, clippy::macro_use_imports, clippy::match_on_vec_items, clippy::match_wildcard_for_single_variants, clippy::mem_forget, clippy::mismatched_target_os, clippy::missing_errors_doc, clippy::missing_safety_doc, clippy::needless_borrow, clippy::needless_continue, clippy::needless_pass_by_value, clippy::option_option, clippy::pub_enum_variant_names, clippy::rest_pat_in_fully_bound_structs, clippy::todo, clippy::unimplemented, clippy::unnested_or_patterns, clippy::verbose_file_reads, future_incompatible, missing_crate_level_docs, missing_doc_code_examples, // missing_docs, nonstandard_style, rust_2018_idioms, unused_doc_comments, )] pub use egui; // Re-export for user convenience // ---------------------------------------------------------------------------- /// Implement this trait to write apps that can be compiled both natively using the [`egui_glium`](https://crates.io/crates/egui_glium) crate, /// and deployed as a web site using the [`egui_web`](https://crates.io/crates/egui_web) crate. pub trait App { /// The name of your App. fn name(&self) -> &str; /// Background color for the app, e.g. what is sent to `gl.clearColor`. /// This is the background of your windows if you don't set a central panel. fn clear_color(&self) -> egui::Rgba { // NOTE: a bright gray makes the shadows of the windows look weird. egui::Srgba::from_rgb(12, 12, 12).into() } /// Called once on start. Allows you to restore state. fn load(&mut self, _storage: &dyn Storage) {} /// Called on shutdown, and perhaps at regular intervals. Allows you to save state. fn save(&mut self, _storage: &mut dyn Storage) {} /// Time between automatic calls to `save()` fn auto_save_interval(&self) -> std::time::Duration { std::time::Duration::from_secs(30) } /// Called once on shutdown (before or after `save()`) fn on_exit(&mut self) {} /// Called once before the first frame. /// Allows you to do setup code and to call `ctx.set_fonts()`. /// Optional. fn setup(&mut self, _ctx: &egui::CtxRef) {} /// Returns true if this app window should be resizable. fn is_resizable(&self) -> bool { true } /// Called each time the UI needs repainting, which may be many times per second. /// Put your widgets into a `SidePanel`, `TopPanel`, `CentralPanel`, `Window` or `Area`. fn ui(&mut self, ctx: &egui::CtxRef, integration_context: &mut IntegrationContext<'_>); } pub struct IntegrationContext<'a> { /// Information about the integration. pub info: IntegrationInfo, /// A way to allocate textures (on integrations that support it). pub tex_allocator: Option<&'a mut dyn TextureAllocator>, /// Where the app can issue commands back to the integration. pub output: AppOutput, /// If you need to request a repaint from another thread, clone this and send it to that other thread. pub repaint_signal: std::sync::Arc, } #[derive(Clone, Debug)] pub struct WebInfo { /// e.g. "#fragment" part of "www.example.com/index.html#fragment" pub web_location_hash: String, } /// Information about the integration passed to the use app each frame. #[derive(Clone, Debug)] pub struct IntegrationInfo { /// If the app is running in a Web context, this returns information about the environment. pub web_info: Option, /// Seconds of cpu usage (in seconds) of UI code on the previous frame. /// `None` if this is the first frame. pub cpu_usage: Option, /// Local time. Used for the clock in the demo app. /// Set to `None` if you don't know. pub seconds_since_midnight: Option, /// The OS native pixels-per-point pub native_pixels_per_point: Option, } /// Action that can be taken by the user app. #[derive(Clone, Copy, Debug, Default, PartialEq)] pub struct AppOutput { /// Set to `true` to stop the app. /// This does nothing for web apps. pub quit: bool, /// Set to some size to resize the outer window (e.g. glium window) to this size. pub window_size: Option, /// If the app sets this, change the `pixels_per_point` of Egui to this next frame. pub pixels_per_point: Option, } pub trait TextureAllocator { /// A.locate a new user texture. fn alloc(&mut self) -> egui::TextureId; /// Set or change the pixels of a user texture. fn set_srgba_premultiplied( &mut self, id: egui::TextureId, size: (usize, usize), srgba_pixels: &[egui::Srgba], ); /// Free the given texture. fn free(&mut self, id: egui::TextureId); } pub trait RepaintSignal: Send + Sync { /// This signals the Egui integration that a repaint is required. /// This is meant to be called when a background process finishes in an async context and/or background thread. fn request_repaint(&self); } // ---------------------------------------------------------------------------- /// A place where you can store custom data in a way that persists when you restart the app. /// /// On the web this is backed by [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage). /// On desktop this is backed by the file system. pub trait Storage { fn get_string(&self, key: &str) -> Option; fn set_string(&mut self, key: &str, value: String); /// write-to-disk or similar fn flush(&mut self); } /// Stores nothing. #[derive(Clone, Default)] pub struct DummyStorage {} impl Storage for DummyStorage { fn get_string(&self, _key: &str) -> Option { None } fn set_string(&mut self, _key: &str, _value: String) {} fn flush(&mut self) {} } #[cfg(feature = "serde_json")] pub fn get_value(storage: &dyn Storage, key: &str) -> Option { storage .get_string(key) .and_then(|value| serde_json::from_str(&value).ok()) } #[cfg(feature = "serde_json")] pub fn set_value(storage: &mut dyn Storage, key: &str, value: &T) { storage.set_string(key, serde_json::to_string(value).unwrap()); } /// storage key used for app pub const APP_KEY: &str = "app";