Struct rerun::external::eframe::egui::Context

pub struct Context(Arc<RwLock<ContextImpl>>);

Your handle to egui.

This is the first thing you need when working with egui. Contains the InputState, Memory, PlatformOutput, and more.

Context is cheap to clone, and any clones refers to the same mutable data (Context uses refcounting internally).

Locking

All methods are marked &self; Context has interior mutability protected by an RwLock.

To access parts of a Context you need to use some of the helper functions that take closures:

if ctx.input(|i| i.key_pressed(egui::Key::A)) {
    ctx.output_mut(|o| o.copied_text = "Hello!".to_string());
}

Within such a closure you may NOT recursively lock the same Context, as that can lead to a deadlock. Therefore it is important that any lock of Context is short-lived.

These are effectively transactional accesses.

Ui has many of the same accessor functions, and the same applies there.

Example:

let mut ctx = egui::Context::default();

// Game loop:
loop {
    let raw_input = egui::RawInput::default();
    let full_output = ctx.run(raw_input, |ctx| {
        egui::CentralPanel::default().show(&ctx, |ui| {
            ui.label("Hello world!");
            if ui.button("Click me").clicked() {
                // take some action here
            }
        });
    });
    handle_platform_output(full_output.platform_output);
    let clipped_primitives = ctx.tessellate(full_output.shapes, full_output.pixels_per_point);
    paint(full_output.textures_delta, clipped_primitives);
}

Tuple Fields

0: Arc<RwLock<ContextImpl>>

Implementations

impl Context

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

Run the ui code for one 1.

At most Options::max_passes calls will be issued to run_ui, and only on the rare occasion that Context::request_discard is called. Usually, it run_ui will only be called once.

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

Instead of calling run, you can alternatively use Self::begin_pass and Context::end_pass.

// 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_pass(&self, new_input: RawInput)

An alternative to calling Self::run.

It is usually better to use Self::run, because run supports multi-pass layout using Self::request_discard.

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

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

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

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

pub fn begin_frame(&self, new_input: RawInput)

👎Deprecated: Renamed begin_pass

See Self::begin_pass.

impl Context

Borrows parts of Context

These functions all lock the Context. Please see the documentation of Context for how locking works!

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 deadlock!
});

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

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

This will create a InputState::default() if there is no input state for that viewport

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

Read-write access to InputState.

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

This will create a InputState::default() if there is no input state for that viewport

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 graphics_mut<R>(&self, writer: impl FnOnce(&mut GraphicLayers) -> R) -> R

Read-write access to GraphicLayers, where painted crate::Shapes are written to.

pub fn graphics<R>(&self, reader: impl FnOnce(&GraphicLayers) -> R) -> R

Read-only access to GraphicLayers, where painted crate::Shapes are written to.

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

Read-only access to PlatformOutput.

This is what egui outputs each pass and 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 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 pass 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 read_response(&self, id: Id) -> Option<Response>

Read the response of some widget, which may be called before creating the widget (!).

This is because widget interaction happens at the start of the pass, using the widget rects from the previous pass.

If the widget was not visible the previous pass (or this pass), this will return None.

pub fn widget_contains_pointer(&self, id: Id) -> bool

👎Deprecated: Use Response.contains_pointer or Context::read_response instead

Returns true if the widget with the given Id contains the pointer.

pub fn register_widget_info(&self, id: Id, make_info: impl Fn() -> WidgetInfo)

This is called by Response::widget_info, but can also be called directly.

With some debug flags it will store the widget info in crate::WidgetRects for later display.

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 debug_text(&self, text: impl Into<WidgetText>)

Print this text next to the cursor at the end of the pass.

If you call this multiple times, the text will be appended.

This only works if compiled with debug_assertions.

ctx.debug_text(format!("State: {state:?}"));

This is just a convenience for calling crate::debug_text::print.

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 crate::Button::shortcut_text.

pub fn cumulative_pass_nr(&self) -> u64

The total number of completed passes (usually there is one pass per rendered frame).

Starts at zero, and is incremented for each completed pass inside of Self::run (usually once).

pub fn cumulative_pass_nr_for(&self, id: ViewportId) -> u64

The total number of completed passes (usually there is one pass per rendered frame).

Starts at zero, and is incremented for each completed pass inside of Self::run (usually once).

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.

To request repaint with a delay, use Self::request_repaint_after.

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).

This will repaint the current viewport.

pub fn request_repaint_of(&self, id: ViewportId)

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.

To request repaint with a delay, use Self::request_repaint_after_for.

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).

This will repaint the specified viewport.

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.

Let’s say, something like a stopwatch 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.

Quirk:

Duration begins at the next frame. Let’s say for example that it’s 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, it’s 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.

This repaints the current viewport.

pub fn request_repaint_after_secs(&self, seconds: f32)

Repaint after this many seconds.

See Self::request_repaint_after for details.

pub fn request_repaint_after_for(&self, duration: Duration, id: ViewportId)

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.

Let’s say, something like a stopwatch 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.

Quirk:

Duration begins at the next frame. Let’s say for example that it’s 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, it’s 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.

This repaints the specified viewport.

pub fn requested_repaint_last_pass(&self) -> bool

Was a repaint requested last pass for the current viewport?

pub fn requested_repaint_last_pass_for(&self, viewport_id: &ViewportId) -> bool

Was a repaint requested last pass for the given viewport?

pub fn has_requested_repaint(&self) -> bool

Has a repaint been requested for the current viewport?

pub fn has_requested_repaint_for(&self, viewport_id: &ViewportId) -> bool

Has a repaint been requested for the given viewport?

pub fn repaint_causes(&self) -> Vec<RepaintCause>

Why are we repainting?

This can be helpful in debugging why egui is constantly repainting.

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 or Self::request_repaint_after.

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 request_discard(&self, reason: impl Into<Cow<'static, str>>)

Request to discard the visual output of this pass, and to immediately do another one.

This can be called to cover up visual glitches during a “sizing pass”. For instance, when a crate::Grid is first shown we don’t yet know the width and heights of its columns and rows. egui will do a best guess, but it will likely be wrong. Next pass it can read the sizes from the previous pass, and from there on the widths will be stable. This means the first pass will look glitchy, and ideally should not be shown to the user. So crate::Grid calls Self::request_discard to cover up this glitches.

There is a limit to how many passes egui will perform, set by Options::max_passes. Therefore, the request might be declined.

You can check if the current pass will be discarded with Self::will_discard.

You should be very conservative with when you call Self::request_discard, as it will cause an extra ui pass, potentially leading to extra CPU use and frame judder.

The given reason should be a human-readable string that explains why request_discard was called. This will be shown in certain debug situations, to help you figure out why a pass was discarded.

pub fn will_discard(&self) -> bool

Will the visual output of this pass be discarded?

If true, you can early-out from expensive graphics operations.

See Self::request_discard for more.

impl Context

Callbacks

pub fn on_begin_pass( &self, debug_name: &'static str, cb: Arc<dyn Fn(&Context) + Sync + Send> )

Call the given callback at the start of each pass of each viewport.

This can be used for egui plugins. See crate::debug_text for an example.

pub fn on_end_pass( &self, debug_name: &'static str, cb: Arc<dyn Fn(&Context) + Sync + Send> )

Call the given callback at the end of each pass of each viewport.

This can be used for egui plugins. See crate::debug_text for an example.

impl Context

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 pass.

pub fn system_theme(&self) -> Option<Theme>

Does the OS use dark or light mode? This is used when the theme preference is set to crate::ThemePreference::System.

pub fn theme(&self) -> Theme

The Theme used to select the appropriate Style (dark or light) used by all subsequent windows, panels etc.

pub fn set_theme(&self, theme_preference: impl Into<ThemePreference>)

The Theme used to select between dark and light Self::style as the active style used by all subsequent windows, panels etc.

Example:

ctx.set_theme(egui::Theme::Light); // Switch to light mode

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

The currently active Style used by all subsequent windows, panels etc.

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

Mutate the currently active Style used by all subsequent windows, panels etc. Use Self::all_styles_mut to mutate both dark and light mode styles.

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 currently active Style used by all new windows, panels etc.

Use Self::all_styles_mut to mutate both dark and light mode styles.

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 all_styles_mut(&self, mutate_style: impl FnMut(&mut Style))

Mutate the Styles used by all subsequent windows, panels etc. in both dark and light mode.

Example:

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

pub fn style_of(&self, theme: Theme) -> Arc<Style>

The Style used by all subsequent windows, panels etc.

pub fn style_mut_of(&self, theme: Theme, mutate_style: impl FnOnce(&mut Style))

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

Example:

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

pub fn set_style_of(&self, theme: Theme, style: impl Into<Arc<Style>>)

The Style used by all new windows, panels etc. Use Self::set_theme to choose between dark and light mode.

You can also change this using Self::style_mut_of.

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

pub fn set_visuals_of(&self, theme: Theme, visuals: Visuals)

The crate::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_of(egui::Theme::Dark, egui::Visuals { panel_fill: egui::Color32::RED, ..Default::default() });

pub fn set_visuals(&self, visuals: Visuals)

The crate::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 { panel_fill: egui::Color32::RED, ..Default::default() });

pub fn pixels_per_point(&self) -> f32

The number of physical pixels for each logical point.

This is calculated as Self::zoom_factor * Self::native_pixels_per_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 pass.

This will actually translate to a call to Self::set_zoom_factor.

pub fn native_pixels_per_point(&self) -> Option<f32>

The number of physical pixels for each logical point on this monitor.

This is given as input to egui via crate::ViewportInfo::native_pixels_per_point and cannot be changed.

pub fn zoom_factor(&self) -> f32

Global zoom factor of the UI.

This is used to calculate the pixels_per_point for the UI as pixels_per_point = zoom_factor * native_pixels_per_point.

The default is 1.0. Make larger to make everything larger.

pub fn set_zoom_factor(&self, zoom_factor: f32)

Sets zoom factor of the UI. Will become active at the start of the next pass.

Note that calling this will not update Self::zoom_factor until the end of the pass.

This is used to calculate the pixels_per_point for the UI as pixels_per_point = zoom_fator * native_pixels_per_point.

The default is 1.0. Make larger to make everything larger.

It is better to call this than modifying Options::zoom_factor.

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 crate::ImageData and crate::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.

impl Context

pub fn end_pass(&self) -> FullOutput

Call at the end of each frame if you called Context::begin_pass.

pub fn end_frame(&self) -> FullOutput

👎Deprecated: Renamed end_pass

Call at the end of each frame if you called Context::begin_pass.

impl Context

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

Tessellate the given shapes into triangle meshes.

pixels_per_point is used for feathering (anti-aliasing). For this you can use FullOutput::pixels_per_point, Self::pixels_per_point, or whatever is appropriate for your viewport.

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 crate::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 crate::TextEdit).

pub fn highlight_widget(&self, id: Id)

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

If you call this after the widget has been fully rendered, then it won’t be highlighted until the next ui pass.

See also Response::highlight.

pub fn is_context_menu_open(&self) -> bool

Is an egui context menu open?

impl Context

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 crate::Event::PointerGone if there were interactions this pass. When tapping a touch screen, this will be the location of the touch.

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

Calls InputState::multi_touch.

impl Context

pub fn set_transform_layer(&self, layer_id: LayerId, transform: TSTransform)

Transform the graphics of the given layer.

This will also affect input.

This is a sticky setting, remembered from one frame to the next.

Can be used to implement pan and zoom (see relevant demo).

For a temporary transform, use Self::transform_layer_shapes instead.

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

👎Deprecated: Use transform_layer_shapes instead

Move all the graphics at the given layer.

Is used to implement drag-and-drop preview.

This only applied to the existing graphics at the layer, not to new graphics added later.

For a persistent transform, use Self::set_transform_layer instead.

pub fn transform_layer_shapes(&self, layer_id: LayerId, transform: TSTransform)

Transform all the graphics at the given layer.

Is used to implement drag-and-drop preview.

This only applied to the existing graphics at the layer, not to new graphics added later.

For a persistent transform, use Self::set_transform_layer instead.

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.

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

pub fn set_sublayer(&self, parent: LayerId, child: LayerId)

Mark the child layer as a sublayer of parent.

Sublayers are moved directly above the parent layer at the end of the frame. This is mainly intended for adding a new crate::Area inside a crate::Window.

This currently only supports one level of nesting. If parent is a sublayer of another layer, the behavior is unspecified.

pub fn top_layer_id(&self) -> Option<LayerId>

Retrieve the LayerId of the top level windows.

pub fn rect_contains_pointer(&self, layer_id: LayerId, rect: Rect) -> bool

Does the given rectangle contain the mouse pointer?

Will return false if some other area is covering the given layer.

The given rectangle is assumed to have been clipped by its parent clip rect.

See also Response::contains_pointer.

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.

impl Context

Animation

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_responsive(&self, id: Id, value: bool) -> f32

Like Self::animate_bool, but uses an easing function that makes the value move quickly in the beginning and slow down towards the end.

The exact easing function may come to change in future versions of egui.

pub fn animate_bool_with_easing( &self, id: Id, value: bool, easing: fn(_: f32) -> f32 ) -> f32

Like Self::animate_bool but allows you to control the easing function.

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_bool_with_time_and_easing( &self, id: Id, target_value: bool, animation_time: f32, easing: fn(_: f32) -> f32 ) -> f32

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

Use e.g. emath::easing::quadratic_out for a responsive start and a slow end.

The easing function flips when target_value is false, so that when going back towards 0.0, we get

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.

impl Context

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.

impl Context

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

Edit the Style.

impl Context

Accessibility

pub fn with_accessibility_parent<R>(&self, _id: Id, f: impl FnOnce() -> R) -> R

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 accesskit_node_builder<R>( &self, id: Id, writer: impl FnOnce(&mut NodeBuilder) -> R ) -> Option<R>

If AccessKit support is active for the current frame, get or create a node builder with the specified ID and return a mutable reference to it. For newly created nodes, the parent is the node with the ID at the top of the stack managed by Context::with_accessibility_parent.

The Context lock is held while the given closure is called!

Returns None if acesskit is off.

pub fn enable_accesskit(&self)

Enable generation of AccessKit tree updates in all future frames.

pub fn disable_accesskit(&self)

Disable generation of AccessKit tree updates in all future frames.

impl Context

Image loading

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 + Sync + Send>)

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 + Sync + Send>)

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 + Sync + Send>)

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 crate::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.

impl Context

Viewports

pub fn viewport_id(&self) -> ViewportId

Return the ViewportId of the current viewport.

If this is the root viewport, this will return ViewportId::ROOT.

Don’t use this outside of Self::run, or after Self::end_pass.

pub fn parent_viewport_id(&self) -> ViewportId

Return the ViewportId of his parent.

If this is the root viewport, this will return ViewportId::ROOT.

Don’t use this outside of Self::run, or after Self::end_pass.

pub fn viewport<R>(&self, reader: impl FnOnce(&ViewportState) -> R) -> R

Read the state of the current viewport.

pub fn viewport_for<R>( &self, viewport_id: ViewportId, reader: impl FnOnce(&ViewportState) -> R ) -> R

Read the state of a specific current viewport.

pub fn set_immediate_viewport_renderer( callback: impl for<'a> Fn(&Context, ImmediateViewport<'a>) + 'static )

For integrations: Set this to render a sync viewport.

This will only set the callback for the current thread, which most likely should be the main thread.

When an immediate viewport is created with Self::show_viewport_immediate it will be rendered by this function.

When called, the integration needs to:

• Check if there already is a window for this viewport id, and if not open one
• Set the window attributes (position, size, …) based on ImmediateViewport::builder.
• Call Context::run with ImmediateViewport::viewport_ui_cb.
• Handle the output from Context::run, including rendering

pub fn embed_viewports(&self) -> bool

If true, Self::show_viewport_deferred and Self::show_viewport_immediate will embed the new viewports inside the existing one, instead of spawning a new native window.

eframe sets this to false on supported platforms, but the default value is true.

pub fn set_embed_viewports(&self, value: bool)

If true, Self::show_viewport_deferred and Self::show_viewport_immediate will embed the new viewports inside the existing one, instead of spawning a new native window.

eframe sets this to false on supported platforms, but the default value is true.

pub fn send_viewport_cmd(&self, command: ViewportCommand)

Send a command to the current viewport.

This lets you affect the current viewport, e.g. resizing the window.

pub fn send_viewport_cmd_to(&self, id: ViewportId, command: ViewportCommand)

Send a command to a specific viewport.

This lets you affect another viewport, e.g. resizing its window.

pub fn show_viewport_deferred( &self, new_viewport_id: ViewportId, viewport_builder: ViewportBuilder, viewport_ui_cb: impl Fn(&Context, ViewportClass) + Send + Sync + 'static )

Show a deferred viewport, creating a new native window, if possible.

The given id must be unique for each viewport.

You need to call this each pass when the child viewport should exist.

You can check if the user wants to close the viewport by checking the crate::ViewportInfo::close_requested flags found in crate::InputState::viewport.

The given callback will be called whenever the child viewport needs repainting, e.g. on an event or when Self::request_repaint is called. This means it may be called multiple times, for instance while the parent viewport (the caller) is sleeping but the child viewport is animating.

You will need to wrap your viewport state in an Arc<RwLock<T>> or Arc<Mutex<T>>. When this is called again with the same id in ViewportBuilder the render function for that viewport will be updated.

You can also use Self::show_viewport_immediate, which uses a simpler FnOnce with no need for Send or Sync. The downside is that it will require the parent viewport (the caller) to repaint anytime the child is repainted, and vice versa.

If Context::embed_viewports is true (e.g. if the current egui backend does not support multiple viewports), the given callback will be called immediately, embedding the new viewport in the current one. You can check this with the ViewportClass given in the callback. If you find ViewportClass::Embedded, you need to create a new crate::Window for you content.

See crate::viewport for more information about viewports.

pub fn show_viewport_immediate<T>( &self, new_viewport_id: ViewportId, builder: ViewportBuilder, viewport_ui_cb: impl FnMut(&Context, ViewportClass) -> T ) -> T

Show an immediate viewport, creating a new native window, if possible.

This is the easier type of viewport to use, but it is less performant at it requires both parent and child to repaint if any one of them needs repainting, which efficvely produce double work for two viewports, and triple work for three viewports, etc. To avoid this, use Self::show_viewport_deferred instead.

The given id must be unique for each viewport.

You need to call this each pass when the child viewport should exist.

You can check if the user wants to close the viewport by checking the crate::ViewportInfo::close_requested flags found in crate::InputState::viewport.

The given ui function will be called immediately. This may only be called on the main thread. This call will pause the current viewport and render the child viewport in its own window. This means that the child viewport will not be repainted when the parent viewport is repainted, and vice versa.

If Context::embed_viewports is true (e.g. if the current egui backend does not support multiple viewports), the given callback will be called immediately, embedding the new viewport in the current one. You can check this with the ViewportClass given in the callback. If you find ViewportClass::Embedded, you need to create a new crate::Window for you content.

See crate::viewport for more information about viewports.

impl Context

Interaction

pub fn interaction_snapshot<R>( &self, reader: impl FnOnce(&InteractionSnapshot) -> R ) -> R

Read you what widgets are currently being interacted with.

pub fn dragged_id(&self) -> Option<Id>

The widget currently being dragged, if any.

For widgets that sense both clicks and drags, this will not be set until the mouse cursor has moved a certain distance.

NOTE: if the widget was released this pass, this will be None. Use Self::drag_stopped_id instead.

pub fn is_being_dragged(&self, id: Id) -> bool

Is this specific widget being dragged?

A widget that sense both clicks and drags is only marked as “dragged” when the mouse has moved a bit

See also: crate::Response::dragged.

pub fn drag_started_id(&self) -> Option<Id>

This widget just started being dragged this pass.

The same widget should also be found in Self::dragged_id.

pub fn drag_stopped_id(&self) -> Option<Id>

This widget was being dragged, but was released this pass

pub fn set_dragged_id(&self, id: Id)

Set which widget is being dragged.

pub fn stop_dragging(&self)

Stop dragging any widget.

pub fn dragging_something_else(&self, not_this: Id) -> bool

Is something else being dragged?

Returns true if we are dragging something, but not the given widget.

Trait Implementations

impl Clone for Context

fn clone(&self) -> Context

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ContextExt for Context

fn ctx(&self) -> &Context

fn text_format_body(&self) -> TextFormat

Text format used for regular body.

fn text_format_key(&self) -> TextFormat

Text format used for labels referring to keys and buttons.

fn rerun_logo_uri(&self) -> &'static str

fn hover_stroke(&self) -> Stroke

Hovered UI and spatial primitives should have this outline.

fn selection_stroke(&self) -> Stroke

Selected UI and spatial primitives should have this outline.

fn success_text(&self, text: impl Into<String>) -> RichText

Text colored to indicate success.

fn warning_text(&self, text: impl Into<String>) -> RichText

Text colored to indicate a warning.

fn error_text(&self, text: impl Into<String>) -> RichText

Text colored to indicate an error.

fn top_bar_style(&self, style_like_web: bool) -> TopBarStyle

fn paint_watermark(&self)

Paint a watermark

impl Debug for Context

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Context

fn default() -> Context

Returns the “default value” for a type.

impl PartialEq for Context

fn eq(&self, other: &Context) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.