Struct egui::Context

pub struct Context(_);

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); // create triangles to paint
    paint(full_output.textures_delta, clipped_primitives);
}

Implementations

impl 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

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

impl Context

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 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 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 the specified duration elapses in the case of no new input events being received.

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 milli seconds 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() + 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 set_style(&self, style: impl Into<Arc<Style>>)

The Style used by all new windows, panels etc.

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

Example:

let mut style: egui::Style = (*ctx.style()).clone();
style.spacing.item_spacing = egui::vec2(10.0, 20.0);
ctx.set_style(style);

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.

In order to display an image you must convert it to a texture using this function.

Make sure to only call this once for each image, i.e. NOT in your main GUI code.

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, texture.size_vec2());
    }
}

Se also crate::ImageData, crate::Ui::image and crate::ImageButton.

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

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

impl Context

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.

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

impl Context

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

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

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

Show stats about the allocated textures.

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

impl Context

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

impl Context

Accessibility

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

If it’s practical for the egui integration to immediately run the egui application when it is either initializing the AccessKit adapter or being called by the AccessKit adapter to provide the initial tree update, then it should do so, to provide a complete AccessKit tree to the adapter immediately. Otherwise, it should enqueue a repaint and use the placeholder tree update from Context::accesskit_placeholder_tree_update in the meantime.

pub fn accesskit_placeholder_tree_update(&self) -> TreeUpdate

Return a tree update that the egui integration should provide to the AccessKit adapter if it cannot immediately run the egui application to get a full tree update after running Context::enable_accesskit.

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 Debug for Context

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

Formats the value using the given formatter.

impl Default for Context

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq<Context> 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.