Struct egui::Context

source ·
pub struct Context(Arc<RwLock<ContextImpl>>);
Expand description

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

Tuple Fields§

§0: Arc<RwLock<ContextImpl>>

Implementations§

source§

impl Context

source

fn read<R>(&self, reader: impl FnOnce(&ContextImpl) -> R) -> R

source

fn write<R>(&self, writer: impl FnOnce(&mut ContextImpl) -> R) -> R

source

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
source

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
source§

impl Context

Borrows parts of Context

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

source

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!
}
source

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

Read-write access to InputState.

source

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

Read-only access to Memory.

source

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

Read-write access to Memory.

source

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

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

source

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

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

source

pub(crate) fn graphics_mut<R>( &self, writer: impl FnOnce(&mut GraphicLayers) -> R ) -> R

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

source

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);
source

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

Read-write access to PlatformOutput.

source

pub(crate) fn frame_state<R>(&self, reader: impl FnOnce(&FrameState) -> R) -> R

Read-only access to FrameState.

source

pub(crate) fn frame_state_mut<R>( &self, writer: impl FnOnce(&mut FrameState) -> R ) -> R

Read-write access to FrameState.

source

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.

source

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

Read-write access to Fonts.

source

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

Read-only access to Options.

source

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

Read-write access to Options.

source

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

Read-only access to TessellationOptions.

source

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

Read-write access to TessellationOptions.

source§

impl Context

source

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.

source

pub(crate) fn interact( &self, clip_rect: Rect, item_spacing: Vec2, layer_id: LayerId, id: Id, rect: Rect, sense: Sense, enabled: bool ) -> Response

Use ui.interact instead

source

pub(crate) fn interact_with_hovered( &self, layer_id: LayerId, id: Id, rect: Rect, sense: Sense, enabled: bool, hovered: bool ) -> Response

You specify if a thing is hovered, and the function gives a Response.

source

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

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

source

pub fn debug_painter(&self) -> Painter

Paint on top of everything else

source

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.

source

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.

source

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);
source

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.

source

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.

source

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

source

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.

source

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.

source

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.

source

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

The Style used by all subsequent windows, panels etc.

source

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);
source

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
source

pub fn pixels_per_point(&self) -> f32

The number of physical pixels for each logical point.

source

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.

source

pub(crate) fn round_to_pixel(&self, point: f32) -> f32

Useful for pixel-perfect rendering

source

pub(crate) fn round_pos_to_pixels(&self, pos: Pos2) -> Pos2

Useful for pixel-perfect rendering

source

pub(crate) fn round_vec_to_pixels(&self, vec: Vec2) -> Vec2

Useful for pixel-perfect rendering

source

pub(crate) fn round_rect_to_pixels(&self, rect: Rect) -> Rect

Useful for pixel-perfect rendering

source

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.

source

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.

source

pub(crate) fn constrain_window_rect_to_area( &self, window: Rect, area: Option<Rect> ) -> Rect

Constrain the position of a window/area so it fits within the provided boundary.

If area is None, will constrain to Self::available_rect.

source§

impl Context

source

pub fn end_frame(&self) -> FullOutput

Call at the end of each frame.

source

fn drain_paint_lists(&self) -> Vec<ClippedShape>

source

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

Tessellate the given shapes into triangle meshes.

source

pub fn screen_rect(&self) -> Rect

Position and size of the egui area.

source

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.

source

pub fn used_rect(&self) -> Rect

How much space is used by panels and windows.

source

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.

source

pub fn is_pointer_over_area(&self) -> bool

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

source

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.

source

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.

source

pub fn wants_keyboard_input(&self) -> bool

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

source

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.

source§

impl Context

source

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

Latest reported pointer position.

When tapping a touch screen, this will be None.

source

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

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

source

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.

source

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

source§

impl Context

source

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

source

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

Top-most layer at the given position.

source

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.

source

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

source

pub fn debug_on_hover(&self) -> bool

Whether or not to debug widget layout on hover.

source

pub fn set_debug_on_hover(&self, debug_on_hover: bool)

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

source§

impl Context

source

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.

source

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.

source

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.

source

pub fn clear_animations(&self)

Clear memory of any animations.

source§

impl Context

source

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

source

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

source

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

Show stats about the allocated textures.

source

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

source§

impl Context

source

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

source§

impl Context

source

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.

Trait Implementations§

source§

impl Clone for Context

source§

fn clone(&self) -> Context

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Context

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for Context

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

impl PartialEq<Context> for Context

source§

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

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

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.

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> SerializableAny for Twhere T: 'static + Any + Clone + Send + Sync,