Struct nannou_egui::FrameCtx

pub struct FrameCtx<'a> { /* private fields */ }

A wrapper around a CtxRef on which begin_frame was called.

Automatically calls end_frame on drop in the case that it wasn’t already called by the usef.

Implementations

impl<'a> FrameCtx<'a>

pub fn context(&self) -> Context

Produces a CtxRef ready for describing the UI for this frame.

pub fn end(self)

End the current frame,

Methods from Deref<Target = Context>

pub fn run( &self, new_input: RawInput, run_ui: impl FnOnce(&Context) ) -> FullOutput

Run the ui code for one frame.

Put your widgets into a SidePanel, TopBottomPanel, CentralPanel, Window or Area.

This will modify the internal reference to point to a new generation of Context. Any old clones of this Context will refer to the old Context, which will not get new input.

You can alternatively run Self::begin_frame and Context::end_frame.

// One egui context that you keep reusing:
let mut ctx = egui::Context::default();

// Each frame:
let input = egui::RawInput::default();
let full_output = ctx.run(input, |ctx| {
    egui::CentralPanel::default().show(&ctx, |ui| {
        ui.label("Hello egui!");
    });
});
// handle full_output

pub fn begin_frame(&self, new_input: RawInput)

An alternative to calling Self::run.

// One egui context that you keep reusing:
let mut ctx = egui::Context::default();

// Each frame:
let input = egui::RawInput::default();
ctx.begin_frame(input);

egui::CentralPanel::default().show(&ctx, |ui| {
    ui.label("Hello egui!");
});

let full_output = ctx.end_frame();
// handle full_output

pub fn input<R>(&self, reader: impl FnOnce(&InputState) -> R) -> R

Read-only access to InputState.

Note that this locks the Context.

ctx.input(|i| {
    // ⚠️ Using `ctx` (even from other `Arc` reference) again here will lead to a dead-lock!
});

if let Some(pos) = ctx.input(|i| i.pointer.hover_pos()) {
    // This is fine!
}

pub fn input_mut<R>(&self, writer: impl FnOnce(&mut InputState) -> R) -> R

Read-write access to InputState.

pub fn memory<R>(&self, reader: impl FnOnce(&Memory) -> R) -> R

Read-only access to Memory.

pub fn memory_mut<R>(&self, writer: impl FnOnce(&mut Memory) -> R) -> R

Read-write access to Memory.

pub fn data<R>(&self, reader: impl FnOnce(&IdTypeMap) -> R) -> R

Read-only access to IdTypeMap, which stores superficial widget state.

pub fn data_mut<R>(&self, writer: impl FnOnce(&mut IdTypeMap) -> R) -> R

Read-write access to IdTypeMap, which stores superficial widget state.

pub fn output<R>(&self, reader: impl FnOnce(&PlatformOutput) -> R) -> R

Read-only access to PlatformOutput.

This is what egui outputs each frame.

ctx.output_mut(|o| o.cursor_icon = egui::CursorIcon::Progress);

pub fn output_mut<R>(&self, writer: impl FnOnce(&mut PlatformOutput) -> R) -> R

Read-write access to PlatformOutput.

pub fn fonts<R>(&self, reader: impl FnOnce(&Fonts) -> R) -> R

Read-only access to [Fonts].

Not valid until first call to Context::run(). That’s because since we don’t know the proper pixels_per_point until then.

pub fn fonts_mut<R>(&self, writer: impl FnOnce(&mut Option<Fonts>) -> R) -> R

Read-write access to [Fonts].

pub fn options<R>(&self, reader: impl FnOnce(&Options) -> R) -> R

Read-only access to Options.

pub fn options_mut<R>(&self, writer: impl FnOnce(&mut Options) -> R) -> R

Read-write access to Options.

pub fn tessellation_options<R>( &self, reader: impl FnOnce(&TessellationOptions) -> R ) -> R

Read-only access to [TessellationOptions].

pub fn tessellation_options_mut<R>( &self, writer: impl FnOnce(&mut TessellationOptions) -> R ) -> R

Read-write access to [TessellationOptions].

pub fn check_for_id_clash(&self, id: Id, new_rect: Rect, what: &str)

If the given Id has been used previously the same frame at at different position, then an error will be printed on screen.

This function is already called for all widgets that do any interaction, but you can call this from widgets that store state but that does not interact.

The given [Rect] should be approximately where the widget will be. The most important thing is that [Rect::min] is approximately correct, because that’s where the warning will be painted. If you don’t know what size to pick, just pick [Vec2::ZERO].

pub fn layer_painter(&self, layer_id: LayerId) -> Painter

Get a full-screen painter for a new or existing layer

pub fn debug_painter(&self) -> Painter

Paint on top of everything else

pub fn os(&self) -> OperatingSystem

What operating system are we running on?

When compiling natively, this is figured out from the target_os.

For web, this can be figured out from the user-agent, and is done so by eframe.

pub fn set_os(&self, os: OperatingSystem)

Set the operating system we are running on.

If you are writing wasm-based integration for egui you may want to set this based on e.g. the user-agent.

pub fn set_cursor_icon(&self, cursor_icon: CursorIcon)

Set the cursor icon.

Equivalent to:

ctx.output_mut(|o| o.cursor_icon = egui::CursorIcon::PointingHand);

pub fn open_url(&self, open_url: OpenUrl)

Open an URL in a browser.

Equivalent to:

ctx.output_mut(|o| o.open_url = Some(open_url));

pub fn copy_text(&self, text: String)

Copy the given text to the system clipboard.

Empty strings are ignored.

Equivalent to:

ctx.output_mut(|o| o.copied_text = "Copy this".to_owned());

pub fn format_shortcut(&self, shortcut: &KeyboardShortcut) -> String

Format the given shortcut in a human-readable way (e.g. Ctrl+Shift+X).

Can be used to get the text for Button::shortcut_text.

pub fn frame_nr(&self) -> u64

The current frame number.

Starts at zero, and is incremented at the end of Self::run or by Self::end_frame.

Between calls to Self::run, this is the frame number of the coming frame.

pub fn request_repaint(&self)

Call this if there is need to repaint the UI, i.e. if you are showing an animation.

If this is called at least once in a frame, then there will be another frame right after this. Call as many times as you wish, only one repaint will be issued.

If called from outside the UI thread, the UI thread will wake up and run, provided the egui integration has set that up via Self::set_request_repaint_callback (this will work on eframe).

pub fn request_repaint_after(&self, duration: Duration)

Request repaint after at most the specified duration elapses.

The backend can chose to repaint sooner, for instance if some other code called this method with a lower duration, or if new events arrived.

The function can be multiple times, but only the smallest duration will be considered. So, if the function is called two times with 1 second and 2 seconds, egui will repaint after 1 second

This is primarily useful for applications who would like to save battery by avoiding wasted redraws when the app is not in focus. But sometimes the GUI of the app might become stale and outdated if it is not updated for too long.

Lets say, something like a stop watch widget that displays the time in seconds. You would waste resources repainting multiple times within the same second (when you have no input), just calculate the difference of duration between current time and next second change, and call this function, to make sure that you are displaying the latest updated time, but not wasting resources on needless repaints within the same second.

NOTE: only works if called before Context::end_frame(). to force egui to update, use Context::request_repaint() instead.

Quirk:

Duration begins at the next frame. lets say for example that its a very inefficient app and takes 500 milliseconds per frame at 2 fps. The widget / user might want a repaint in next 500 milliseconds. Now, app takes 1000 ms per frame (1 fps) because the backend event timeout takes 500 milliseconds AFTER the vsync swap buffer. So, its not that we are requesting repaint within X duration. We are rather timing out during app idle time where we are not receiving any new input events.

pub fn set_request_repaint_callback( &self, callback: impl Fn(RequestRepaintInfo) + Send + Sync + 'static )

For integrations: this callback will be called when an egui user calls Self::request_repaint.

This lets you wake up a sleeping UI thread.

Note that only one callback can be set. Any new call overrides the previous callback.

pub fn set_fonts(&self, font_definitions: FontDefinitions)

Tell egui which fonts to use.

The default egui fonts only support latin and cyrillic alphabets, but you can call this to install additional fonts that support e.g. korean characters.

The new fonts will become active at the start of the next frame.

pub fn style(&self) -> Arc<Style>

The Style used by all subsequent windows, panels etc.

pub fn style_mut(&self, mutate_style: impl FnOnce(&mut Style))

Mutate the Style used by all subsequent windows, panels etc.

Example:

ctx.style_mut(|style| {
    style.spacing.item_spacing = egui::vec2(10.0, 20.0);
});

pub fn set_style(&self, style: impl Into<Arc<Style>>)

The Style used by all new windows, panels etc.

You can also change this using [Self::style_mut]

You can use Ui::style_mut to change the style of a single Ui.

pub fn set_visuals(&self, visuals: Visuals)

The Visuals used by all subsequent windows, panels etc.

You can also use Ui::visuals_mut to change the visuals of a single Ui.

Example:

ctx.set_visuals(egui::Visuals::light()); // Switch to light mode

pub fn pixels_per_point(&self) -> f32

The number of physical pixels for each logical point.

pub fn set_pixels_per_point(&self, pixels_per_point: f32)

Set the number of physical pixels for each logical point. Will become active at the start of the next frame.

Note that this may be overwritten by input from the integration via RawInput::pixels_per_point. For instance, when using eframe on web, the browsers native zoom level will always be used.

pub fn load_texture( &self, name: impl Into<String>, image: impl Into<ImageData>, options: TextureOptions ) -> TextureHandle

Allocate a texture.

This is for advanced users. Most users should use crate::Ui::image or Self::try_load_texture instead.

In order to display an image you must convert it to a texture using this function. The function will hand over the image data to the egui backend, which will upload it to the GPU.

⚠️ Make sure to only call this ONCE for each image, i.e. NOT in your main GUI code. The call is NOT immediate safe.

The given name can be useful for later debugging, and will be visible if you call Self::texture_ui.

For how to load an image, see [ImageData] and [ColorImage::from_rgba_unmultiplied].

struct MyImage {
    texture: Option<egui::TextureHandle>,
}

impl MyImage {
    fn ui(&mut self, ui: &mut egui::Ui) {
        let texture: &egui::TextureHandle = self.texture.get_or_insert_with(|| {
            // Load the texture only once.
            ui.ctx().load_texture(
                "my-image",
                egui::ColorImage::example(),
                Default::default()
            )
        });

        // Show the image:
        ui.image((texture.id(), texture.size_vec2()));
    }
}

See also [crate::ImageData], crate::Ui::image and crate::Image.

pub fn tex_manager(&self) -> Arc<RwLock<TextureManager>>

Low-level texture manager.

In general it is easier to use Self::load_texture and [TextureHandle].

You can show stats about the allocated textures using Self::texture_ui.

pub fn end_frame(&self) -> FullOutput

Call at the end of each frame.

pub fn tessellate(&self, shapes: Vec<ClippedShape>) -> Vec<ClippedPrimitive>

Tessellate the given shapes into triangle meshes.

pub fn screen_rect(&self) -> Rect

Position and size of the egui area.

pub fn available_rect(&self) -> Rect

How much space is still available after panels has been added.

This is the “background” area, what egui doesn’t cover with panels (but may cover with windows). This is also the area to which windows are constrained.

pub fn used_rect(&self) -> Rect

How much space is used by panels and windows.

pub fn used_size(&self) -> Vec2

How much space is used by panels and windows.

You can shrink your egui area to this size and still fit all egui components.

pub fn is_pointer_over_area(&self) -> bool

Is the pointer (mouse/touch) over any egui area?

pub fn wants_pointer_input(&self) -> bool

True if egui is currently interested in the pointer (mouse or touch).

Could be the pointer is hovering over a Window or the user is dragging a widget. If false, the pointer is outside of any egui area and so you may be interested in what it is doing (e.g. controlling your game). Returns false if a drag started outside of egui and then moved over an egui area.

pub fn is_using_pointer(&self) -> bool

Is egui currently using the pointer position (e.g. dragging a slider)?

NOTE: this will return false if the pointer is just hovering over an egui area.

pub fn wants_keyboard_input(&self) -> bool

If true, egui is currently listening on text input (e.g. typing text in a TextEdit).

pub fn highlight_widget(&self, id: Id)

Highlight this widget, to make it look like it is hovered, even if it isn’t.

The highlight takes on frame to take effect if you call this after the widget has been fully rendered.

See also Response::highlight.

pub fn is_context_menu_open(&self) -> bool

Is an egui context menu open?

pub fn pointer_latest_pos(&self) -> Option<Pos2>

Latest reported pointer position.

When tapping a touch screen, this will be None.

pub fn pointer_hover_pos(&self) -> Option<Pos2>

If it is a good idea to show a tooltip, where is pointer?

pub fn pointer_interact_pos(&self) -> Option<Pos2>

If you detect a click or drag and wants to know where it happened, use this.

Latest position of the mouse, but ignoring any Event::PointerGone if there were interactions this frame. When tapping a touch screen, this will be the location of the touch.

pub fn multi_touch(&self) -> Option<MultiTouchInfo>

Calls InputState::multi_touch.

pub fn translate_layer(&self, layer_id: LayerId, delta: Vec2)

Move all the graphics at the given layer.

Can be used to implement drag-and-drop (see relevant demo).

pub fn layer_id_at(&self, pos: Pos2) -> Option<LayerId>

Top-most layer at the given position.

pub fn move_to_top(&self, layer_id: LayerId)

Moves the given area to the top in its Order.

Area:s and Window:s also do this automatically when being clicked on or interacted with.

pub fn debug_on_hover(&self) -> bool

Whether or not to debug widget layout on hover.

pub fn set_debug_on_hover(&self, debug_on_hover: bool)

Turn on/off whether or not to debug widget layout on hover.

pub fn animate_bool(&self, id: Id, value: bool) -> f32

Returns a value in the range [0, 1], to indicate “how on” this thing is.

The first time called it will return if value { 1.0 } else { 0.0 } Calling this with value = true will always yield a number larger than zero, quickly going towards one. Calling this with value = false will always yield a number less than one, quickly going towards zero.

The function will call Self::request_repaint() when appropriate.

The animation time is taken from Style::animation_time.

pub fn animate_bool_with_time( &self, id: Id, target_value: bool, animation_time: f32 ) -> f32

Like Self::animate_bool but allows you to control the animation time.

pub fn animate_value_with_time( &self, id: Id, target_value: f32, animation_time: f32 ) -> f32

Smoothly animate an f32 value.

At the first call the value is written to memory. When it is called with a new value, it linearly interpolates to it in the given time.

pub fn clear_animations(&self)

Clear memory of any animations.

pub fn settings_ui(&self, ui: &mut Ui)

Show a ui for settings (style and tessellation options).

pub fn inspection_ui(&self, ui: &mut Ui)

Show the state of egui, including its input and output.

pub fn texture_ui(&self, ui: &mut Ui)

Show stats about the allocated textures.

pub fn memory_ui(&self, ui: &mut Ui)

Shows the contents of Self::memory.

pub fn style_ui(&self, ui: &mut Ui)

Edit the active Style.

pub fn with_accessibility_parent(&self, _id: Id, f: impl FnOnce())

Call the provided function with the given ID pushed on the stack of parent IDs for accessibility purposes. If the accesskit feature is disabled or if AccessKit support is not active for this frame, the function is still called, but with no other effect.

No locks are held while the given closure is called.

pub fn include_bytes( &self, uri: impl Into<Cow<'static, str>>, bytes: impl Into<Bytes> )

Associate some static bytes with a uri.

The same uri may be passed to Ui::image later to load the bytes as an image.

By convention, the uri should start with bytes://. Following that convention will lead to better error messages.

pub fn is_loader_installed(&self, id: &str) -> bool

Returns true if the chain of bytes, image, or texture loaders contains a loader with the given id.

pub fn add_bytes_loader(&self, loader: Arc<dyn BytesLoader + Send + Sync>)

Add a new bytes loader.

It will be tried first, before any already installed loaders.

See load for more information.

pub fn add_image_loader(&self, loader: Arc<dyn ImageLoader + Send + Sync>)

Add a new image loader.

It will be tried first, before any already installed loaders.

See load for more information.

pub fn add_texture_loader(&self, loader: Arc<dyn TextureLoader + Send + Sync>)

Add a new texture loader.

It will be tried first, before any already installed loaders.

See load for more information.

pub fn forget_image(&self, uri: &str)

Release all memory and textures related to the given image URI.

If you attempt to load the image again, it will be reloaded from scratch.

pub fn forget_all_images(&self)

Release all memory and textures related to images used in Ui::image or Image.

If you attempt to load any images again, they will be reloaded from scratch.

pub fn try_load_bytes(&self, uri: &str) -> Result<BytesPoll, LoadError>

Try loading the bytes from the given uri using any available bytes loaders.

Loaders are expected to cache results, so that this call is immediate-mode safe.

This calls the loaders one by one in the order in which they were registered. If a loader returns LoadError::NotSupported, then the next loader is called. This process repeats until all loaders have been exhausted, at which point this returns LoadError::NotSupported.

Errors

This may fail with:

• LoadError::NotSupported if none of the registered loaders support loading the given uri.
• LoadError::Loading if one of the loaders does support loading the uri, but the loading process failed.

⚠ May deadlock if called from within a BytesLoader!

pub fn try_load_image( &self, uri: &str, size_hint: SizeHint ) -> Result<ImagePoll, LoadError>

Try loading the image from the given uri using any available image loaders.

Loaders are expected to cache results, so that this call is immediate-mode safe.

This calls the loaders one by one in the order in which they were registered. If a loader returns LoadError::NotSupported, then the next loader is called. This process repeats until all loaders have been exhausted, at which point this returns LoadError::NotSupported.

Errors

This may fail with:

• LoadError::NoImageLoaders if tbere are no registered image loaders.
• LoadError::NotSupported if none of the registered loaders support loading the given uri.
• LoadError::Loading if one of the loaders does support loading the uri, but the loading process failed.

⚠ May deadlock if called from within an ImageLoader!

pub fn try_load_texture( &self, uri: &str, texture_options: TextureOptions, size_hint: SizeHint ) -> Result<TexturePoll, LoadError>

Try loading the texture from the given uri using any available texture loaders.

Loaders are expected to cache results, so that this call is immediate-mode safe.

This calls the loaders one by one in the order in which they were registered. If a loader returns LoadError::NotSupported, then the next loader is called. This process repeats until all loaders have been exhausted, at which point this returns LoadError::NotSupported.

Errors

This may fail with:

• LoadError::NotSupported if none of the registered loaders support loading the given uri.
• LoadError::Loading if one of the loaders does support loading the uri, but the loading process failed.

⚠ May deadlock if called from within a TextureLoader!

pub fn loaders(&self) -> Arc<Loaders>

The loaders of bytes, images, and textures.

Trait Implementations

impl<'a> Deref for FrameCtx<'a>

type Target = Context

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'a> Drop for FrameCtx<'a>

fn drop(&mut self)

Executes the destructor for this type.