Module egui::viewport

source ·
Expand description

egui supports multiple viewports, corresponding to multiple native windows.

Not all egui backends support multiple viewports, but eframe native does (but not on web).

You can spawn a new viewport using Context::show_viewport_deferred and Context::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 viewport

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. 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 needs to be 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 the parent viewports needs to be repainted, so will the child viewport, and vice versa. This means that if you have N viewports you are potentially 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, independent 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 a crate::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 with Context::viewport_id. You can modify the current (change the title, resize the window, etc) by sending a ViewportCommand to it using Context::send_viewport_cmd. You can interact with other viewports using Context::send_viewport_cmd_to.

There is an example in https://github.com/emilk/egui/tree/master/examples/multiple_viewports/src/main.rs.

You can find all available viewports in crate::RawInput::viewports and the active viewport in crate::InputState::viewport:

ctx.input(|i| {
    dbg!(&i.viewport()); // Current viewport
    dbg!(&i.raw.viewports); // All viewports
});

For integrations

Future work

There are several more things related to viewports that we want to add. Read more at https://github.com/emilk/egui/issues/3556.

Structs

Enums

Type Aliases