Struct me3_framework::overlay::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).

All methods are marked &self; Context has interior mutability (protected by a mutex).

You can store

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

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

impl Context

Borrows parts of Context

pub fn memory(&self) -> MappedRwLockWriteGuard<'_, RawRwLock, Memory>

Stores all the egui state.

If you want to store/restore egui, serialize this.

pub fn data(&self) -> MappedRwLockWriteGuard<'_, RawRwLock, IdTypeMap>

Stores superficial widget state.

pub fn output(&self) -> MappedRwLockWriteGuard<'_, RawRwLock, PlatformOutput>

What egui outputs each frame.

ctx.output().cursor_icon = egui::CursorIcon::Progress;

pub fn input(&self) -> MappedRwLockReadGuard<'_, RawRwLock, InputState>

Access the InputState.

Note that this locks the Context, so be careful with if-let bindings:

if let Some(pos) = ctx.input().pointer.hover_pos() {
    // ⚠️ Using `ctx` again here will lead to a dead-lock!
}

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

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

pub fn input_mut(&self) -> MappedRwLockWriteGuard<'_, RawRwLock, InputState>

pub fn fonts(&self) -> MappedRwLockReadGuard<'_, RawRwLock, 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(&self) -> MappedRwLockWriteGuard<'_, RawRwLock, Options>

pub fn tessellation_options(
    &self
) -> MappedRwLockWriteGuard<'_, RawRwLock, TessellationOptions>

Change the options used by the tessellator.

impl Context

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>,
    filter: TextureFilter
) -> 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(),
                egui::TextureFilter::Linear
            )
        });

        // 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, Global>
) -> Vec<ClippedPrimitive, Global>

Tessellate the given shapes into triangle meshes.

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

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,
    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,
    value: f32,
    animation_time: f32
) -> f32

Allows you to smoothly change the 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)

Trait Implementations

impl Clone for Context

fn clone(&self) -> Context

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for Context

fn default() -> Context

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

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