* Part of https://github.com/emilk/egui/issues/3556
This PR replaces a bunch of options in `eframe::NativeOptions` with
`egui::ViewportBuilder`. For instance:
``` diff
let options = eframe::NativeOptions {
- initial_window_size: Some(egui::vec2(320.0, 240.0)),
- drag_and_drop_support: true,
+ viewport: egui::ViewportBuilder::default()
+ .with_inner_size([320.0, 240.0])
+ .with_drag_and_drop(true),
centered: true,
..Default::default()
};
```
* Part of https://github.com/emilk/egui/issues/3556
## In short
You now almost never need to use `eframe::Frame` - instead use
`ui.input(|i| i.viewport())` for information about the current viewport
(native window), and use `ctx.send_viewport_cmd` to modify it.
## In detail
This PR removes most commands from `eframe::Frame`, and replaces them
with `ViewportCommand`.
So `frame.close()` becomes
`ctx.send_viewport_cmd(ViewportCommand::Close)`, etc.
`frame.info().window_info` is now also gone, replaced with `ui.input(|i|
i.viewport())`.
`frame.info().native_pixels_per_point` is replaced with `ui.input(|i|
i.raw.native_pixels_per_point)`.
`RawInput` now contains one `ViewportInfo` for each viewport.
Screenshots are taken with
`ctx.send_viewport_cmd(ViewportCommand::Screenshots)` and are returned
in `egui::Event` which you can check with:
``` ust
ui.input(|i| {
for event in &i.raw.events {
if let egui::Event::Screenshot { viewport_id, image } = event {
// handle it here
}
}
});
```
### Motivation
You no longer need to pass around the `&eframe::Frame` everywhere.
This also opens the door for other integrations to use the same API of
`ViewportCommand`s.
* Closes#1044
---
(new PR description written by @emilk)
## Overview
This PR introduces the concept of `Viewports`, which on the native
eframe backend corresponds to native OS windows.
You can spawn a new viewport using `Context::show_viewport` and
`Cotext::show_viewport_immediate`.
These needs to be called every frame the viewport should be visible.
This is implemented by the native `eframe` backend, but not the web one.
## Viewport classes
The viewports form a tree of parent-child relationships.
There are different classes of viewports.
### Root vieport
The root viewport is the original viewport, and cannot be closed without
closing the application.
### Deferred viewports
These are created with `Context::show_viewport`.
Deferred viewports take a closure that is called by the integration at a
later time, perhaps multiple times.
Deferred viewports are repainted independenantly of the parent viewport.
This means communication with them need to done via channels, or
`Arc/Mutex`.
This is the most performant type of child viewport, though a bit more
cumbersome to work with compared to immediate viewports.
### Immediate viewports
These are created with `Context::show_viewport_immediate`.
Immediate viewports take a `FnOnce` closure, similar to other egui
functions, and is called immediately. This makes communication with them
much simpler than with deferred viewports, but this simplicity comes at
a cost: whenever tha parent viewports needs to be repainted, so will the
child viewport, and vice versa. This means that if you have `N`
viewports you are poentially doing `N` times as much CPU work. However,
if all your viewports are showing animations, and thus are repainting
constantly anyway, this doesn't matter.
In short: immediate viewports are simpler to use, but can waste a lot of
CPU time.
### Embedded viewports
These are not real, independenant viewports, but is a fallback mode for
when the integration does not support real viewports. In your callback
is called with `ViewportClass::Embedded` it means you need to create an
`egui::Window` to wrap your ui in, which will then be embedded in the
parent viewport, unable to escape it.
## Using the viewports
Only one viewport is active at any one time, identified wth
`Context::viewport_id`.
You can send commands to other viewports using
`Context::send_viewport_command_to`.
There is an example in
<https://github.com/emilk/egui/tree/master/examples/multiple_viewports/src/main.rs>.
## For integrations
There are several changes relevant to integrations.
* There is a [`crate::RawInput::viewport`] with information about the
current viewport.
* The repaint callback set by `Context::set_request_repaint_callback`
now points to which viewport should be repainted.
* `Context::run` now returns a list of viewports in `FullOutput` which
should result in their own independant windows
* There is a new `Context::set_immediate_viewport_renderer` for setting
up the immediate viewport integration
* If you support viewports, you need to call
`Context::set_embed_viewports(false)`, or all new viewports will be
embedded (the default behavior).
## Future work
* Make it easy to wrap child viewports in the same chrome as
`egui::Window`
* Automatically show embedded viewports using `egui::Window`
* Use the new `ViewportBuilder` in `eframe::NativeOptions`
* Automatically position new viewport windows (they currently cover each
other)
* Add a `Context` method for listing all existing viewports
Find more at https://github.com/emilk/egui/issues/3556
---
<details>
<summary>
Outdated PR description by @konkitoman
</summary>
## Inspiration
- Godot because the app always work desktop or single_window because of
embedding
- Dear ImGui viewport system
## What is a Viewport
A Viewport is a egui isolated component!
Can be used by the egui integration to create native windows!
When you create a Viewport is possible that the backend do not supports
that!
So you need to check if the Viewport was created or you are in the
normal egui context!
This is how you can do that:
```rust
if ctx.viewport_id() != ctx.parent_viewport_id() {
// In here you add the code for the viewport context, like
egui::CentralPanel::default().show(ctx, |ui|{
ui.label("This is in a native window!");
});
}else{
// In here you add the code for when viewport cannot be created!
// You cannot use CentralPanel in here because you will override the app CentralPanel
egui::Window::new("Virtual Viewport").show(ctx, |ui|{
ui.label("This is without a native window!\nThis is in a embedded viewport");
});
}
```
This PR do not support for drag and drop between Viewports!
After this PR is accepted i will begin work to intregrate the Viewport
system in `egui::Window`!
The `egui::Window` i want to behave the same on desktop and web
The `egui::Window` will be like Godot Window
## Changes and new
These are only public structs and functions!
<details>
<summary>
## New
</summary>
- `egui::ViewportId`
- `egui::ViewportBuilder`
This is like winit WindowBuilder
- `egui::ViewportCommand`
With this you can set any winit property on a viewport, when is a native
window!
- `egui::Context::new`
- `egui::Context::create_viewport`
- `egui::Context::create_viewport_sync`
- `egui::Context::viewport_id`
- `egui::Context::parent_viewport_id`
- `egui::Context::viewport_id_pair`
- `egui::Context::set_render_sync_callback`
- `egui::Context::is_desktop`
- `egui::Context::force_embedding`
- `egui::Context::set_force_embedding`
- `egui::Context::viewport_command`
- `egui::Context::send_viewport_command_to`
- `egui::Context::input_for`
- `egui::Context::input_mut_for`
- `egui::Context::frame_nr_for`
- `egui::Context::request_repaint_for`
- `egui::Context::request_repaint_after_for`
- `egui::Context::requested_repaint_last_frame`
- `egui::Context::requested_repaint_last_frame_for`
- `egui::Context::requested_repaint`
- `egui::Context::requested_repaint_for`
- `egui::Context::inner_rect`
- `egui::Context::outer_rect`
- `egui::InputState::inner_rect`
- `egui::InputState::outer_rect`
- `egui::WindowEvent`
</details>
<details>
<summary>
## Changes
</summary>
- `egui::Context::run`
Now needs the viewport that we want to render!
- `egui::Context::begin_frame`
Now needs the viewport that we want to render!
- `egui::Context::tessellate`
Now needs the viewport that we want to render!
- `egui::FullOutput`
```diff
- repaint_after
+ viewports
+ viewport_commands
```
- `egui::RawInput`
```diff
+ inner_rect
+ outer_rect
```
- `egui::Event`
```diff
+ WindowEvent
```
</details>
### Async Viewport
Async means that is independent from other viewports!
Is created by `egui::Context::create_viewport`
To be used you will need to wrap your state in `Arc<RwLock<T>>`
Look at viewports example to understand how to use it!
### Sync Viewport
Sync means that is dependent on his parent!
Is created by `egui::Context::create_viewport_sync`
This will pause the parent then render itself the resumes his parent!
#### ⚠️ This currently will make the fps/2 for every sync
viewport
### Common
#### ⚠️ Attention
You will need to do this when you render your content
```rust
ctx.create_viewport(ViewportBuilder::new("Simple Viewport"), | ctx | {
let content = |ui: &mut egui::Ui|{
ui.label("Content");
};
// This will make the content a popup if cannot create a native window
if ctx.viewport_id() != ctx.parent_viewport_id() {
egui::CentralPanel::default().show(ctx, content);
} else {
egui::Area::new("Simple Viewport").show(ctx, |ui| {
egui::Frame::popup(ui.style()).show(ui, content);
});
};
});
````
## What you need to know as egui user
### If you are using eframe
You don't need to change anything!
### If you have a manual implementation
Now `egui::run` or `egui::begin` and `egui::tessellate` will need the
current viewport id!
You cannot create a `ViewportId` only `ViewportId::MAIN`
If you make a single window app you will set the viewport id to be
`egui::ViewportId::MAIN` or see the `examples/pure_glow`
If you want to have multiples window support look at `crates/eframe`
glow or wgpu implementations!
## If you want to try this
- cargo run -p viewports
## This before was wanted to change
This will probably be in feature PR's
### egui::Window
To create a native window when embedded was set to false
You can try that in viewports example before:
[78a0ae8](78a0ae879e)
### egui popups, context_menu, tooltip
To be a native window
</details>
---------
Co-authored-by: Konkitoman <konkitoman@users.noreply.github.com>
Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
Co-authored-by: Pablo Sichert <mail@pablosichert.com>
* eframe README: explain how to enable copy/paste
* Implement Debug for a couple of structs
* Code cleanup
* Better docs
* profile ron serialization
* CI: Allow "exclude from changelog" as the only label
* Give credit to recent big-time contributors in the main README.md
* Better named profiling scopes
* Document everything in memory.rs
* Better doc-strings
* Add a section about dependencies to the main README.md
* Improve egui_extras docs
* fix typos
* Remove calls to `set_ime_allowed`
* Allow IME if `text_cursor_pos` is `Some`
* Only call `Window::set_ime_allowed` when necessary
* allow_ime doesn't need to be atomic
* Remove unused imports
* Fix assignment
When exiting my application, it would freeze for around a minute waiting to finish writing ca. 40MB to file storage.
Some quick profiling revealed that it was spending all that time in `File::write`,
presumably making a large number of system calls writing tiny amounts of data at a time.
We can avoid this by buffering writes using a `BufWriter`, just like we already do with `BufReader`.
With this change, my application takes around 1-2 seconds to exit, with the majority of that time spent serializing `ron`.
I'm sure there are further potential performance improvements there, but this is already an order of magnitude or two better.
I also fixed the call to `log::warn!`, which was using incorrect formatting syntax and not including the error message.
* Add puffin profile scopes to the startup and running of eframe
* puffin_profiler example: start puffin right away
* cargo format let-else statements
* More profile scopes
* Add some `#[inline]`
* Standardize puffin profile scope definitions
* standardize again
* Silence warning when puffin is disabled
* Silence a few clippy warnings
* Use named threads
* Remove some deprecated functions
* Document Context and Ui fully
* Use `parking_lot::Mutex` in `eframe`
* Expand clippy.toml files
* build fix
* Get a reference to `IntegrationInfo`
* Add doc comment
* Change `info` to return a reference
* Clone integration info
* Remove `&`
* Clone integration info in another place
* Fix the app only taking up half the screen size on iPad
* Fix request_repaint not working on iOS
* Always use run_and_exit on iOS since run_and_return is not supported by winit on iOS right now.
* Fix typo
* Fix eframe glow on ios
* Handle more cases
We had a bunch of `cfg!(windows)` and `cfg!(macos)` which should
have been `cfg!(target_os = "windows")`.
I wonder what the effects of this PR will be fore Windows 😬
A window may not always be available and may have already been closed by the time an eframe app is closing. An example of this is Android, where the main activity window may have been stopped or discarded because the app is no longer in the foreground, and then the user decides to close your app without resuming it using the multitasking view.
In this case, skip the window persistence step if it does not exist anymore by the time we are saving the persistence data. Currently eframe will panic with `winit window doesn't exist` instead.
* Expose raw window and display handles in eframe
* Ensure that no one implements `Clone` in the future
* Cleanup
---------
Co-authored-by: Matti Virkkunen <mvirkkunen@gmail.com>
The approach of #1889 may remove observers in a view
twice, which produces the Obj-C Exception:
Cannot remove an observer <...> for the key path
"nextResponder" from <WinitView ...> because
it is not registered as an observer.
The above message can only be seen when attaching the
application to debugger. Users normally see:
[1] *** trace trap cargo run
This commit fixes it by only running `event_loop.run_return()`
twice on Windows. Besides:
* We have set `ControlFlow::Exit` on `Event::LoopDestroyed`,
`EventResult::Exit` and on error; therefore, it is safe
to not calling `set_exit()`.
* This commit also fix the persistence function in macOS.
It can't store the content in Memory due to this exception.
Fixed: #2768 (eframe: "App quit unexpectedly" on macOS)
Signed-off-by: pan93412 <pan93412@gmail.com>
* Add an optional app_id field to eframe's NativeOptions (#1600).
This is used in the window builder to set the application ID, which is e.g. important for a proper configuration in `.desktop` files under Wayland.
When no application ID is explicitly set, it defaults to the title of the window.
* Only enable NativeOptions::app_id under Linux.
The wayland feature is not sufficent as constraint and it won't compile e.g. under Windows.
While Wayland could also be used on other Unix-Systems like FreeBSD, this would probably need some specific testing. Winit uses the following definition as "wayland_platform" and on which the required packages are available:
> wayland_platform: { all(feature = "wayland", free_unix, not(wasm), not(redox)) },
* Do not use title as default application ID under Wayland.
The title might be used to also communicate state (opened file, ...) to the user and this might have unforeseen consequences for the application ID. It seems to be better to use the old behavior of not setting an application ID in this case. Also add an example on how to set the application ID in the documentation.
* Avoid as_deref(), which was a left-over of a previous version
Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
---------
Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
* Add Pointer::is_decidedly_dragging and could_any_button_be_click
This allows users to distinguish between click and drags
while they are not yet done.
* Fix warning in eframe
* fix typo
* eframe: Set app icon on Mac and Windows
Also: correctly set window title on Mac when launching from
another process, e.g. python.
Co-authored-by: Wumpf <andreas@rerun.io>
* lint fixes
* Fix web build
* fix typo
* Try fix windows build
---------
Co-authored-by: Wumpf <andreas@rerun.io>
* Refactor repaint logic
* request_repaint_after also fires the request_repaint callback
* Bug fixes
* Add test to egui_demo_app
* build_demo_web: build debug unless --release is specified
* Fix the web backend too
* Run special clippy for wasm, forbidding some types/methods
* Remove wasm_bindgen_check.sh
* Fix typos
* Revert "Remove wasm_bindgen_check.sh"
This reverts commit 92dde253446a6930f34f2fcf67f76bc11669ec3b.
* Only run cranky/clippy once
* add method for requesting attention to the main window
* use another enum member for user attention type instead of nested `Option`s
(also, document the enum members now that they don't mirror `winit`)
* update the docstring
Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
* add an example app for testing window attention requests
* Apply suggestions from code review
Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
* remove `chrono` dependency and improve the attention example's readability
---------
Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
* Remove dark-light dependency
Since https://github.com/emilk/egui/pull/2750 we now get what we need
straight from `winit`.
* fix warning
* Docstring formatting
* fix typo in check.sh
* Replace tracing crate with log
It's just so much simpler to use
* Add `bacon wasm` job
* eframe: add a WebLogger for piping log events to the web console
`EventResult::Exit` is hit before `Event::LoopDestroyed` is, and due to
possibly some order of operations or drops the window is never destroyed
on Linux. Adding a call to `winit_app.save_and_destroy();` where
`EventResult::Exit` is checked solves this.
Closes#2892
Signed-off-by: Luke D. Jones <luke@ljones.dev>
* Add ability to read the native window's focus state
* Add `eframe::Frame::focus()` for requesting the native window's focus
* rename the output field `active` → `focused` for consistency
* React to ThemeChanged event from winit
* React to theme change using media query change event in WASM
* Share conversion from bool -> Theme
* Suppress too_many_arguments warning
* Document limitations of automatically following the dark vs light mode preference
* Simplify expression
* Conditionally compile code to prevent unused item warnings
* Remove needless borrow
* Remove another needless borrow
* Make associated functions to standalone
* Request repaint after theme has changed
* Only install event listener when `follow_system_theme` is enabled
* Remove dark-light feature gate
* Detect system theme using winit
* Update documentation
* Fix typos
* fix warning about unused argument
---------
Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
* use glutin-winit for glow context creation
* added some tracing for easier debugging of glutin problems
* fmt
* add more debug logs
* more tracing
* fallback egl instead of prefer egl
* update pure glow example to use glutin_winit
* add more logging. ignore vsync option if not supported
* cranky lint
* add some logging for easier debugging
* drop window after glutin surface
* small changes based on pr review
* build fix
---------
Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
* Support for transparent backbuffer in wgpu winit binding
Choose best fitting composite alpha mode on the fly.
* Compilation fix
* Add line to eframe CHANGELOG
* Attempt to mollify CI: try different way to install apt packages
---------
Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
Emil Ernerfeldt
Konkitoman
Simon
Barugon
Sebastian Reinhard
lucasmerlin
jacekpoz
Stephen M. Coakley
Matt Fellenz
icedrocket
bilabila
τ
pan93412
Thomas Krause
Andreas Reich
TicClick
Dixeran
Jozef Číž
Luke Jones
amfaber
谢克
Red Artist