Struct Ui 

pub struct Ui {
    id: Id,
    unique_id: Id,
    next_auto_id_salt: u64,
    painter: Painter,
    style: Arc<Style>,
    placer: Placer,
    enabled: bool,
    sizing_pass: bool,
    menu_state: Option<Arc<RwLock<MenuState>>>,
    stack: Arc<UiStack>,
    sense: Sense,
    min_rect_already_remembered: bool,
}

This is what you use to place widgets.

Represents a region of the screen with a type of layout (horizontal or vertical).

ui.add(egui::Label::new("Hello World!"));
ui.label("A shorter and more convenient way to add a label.");
ui.horizontal(|ui| {
    ui.label("Add widgets");
    if ui.button("on the same row!").clicked() {
        /* … */
    }
});

Fields

id: Id

Generated based on id of parent ui together with an optional id salt.

This should be stable from one frame to next so it can be used as a source for storing state (e.g. window position, or if a collapsing header is open).

However, it is not necessarily globally unique. For instance, sibling Uis share the same Self::id unless they where explicitly given different id salts using UiBuilder::id_salt.

unique_id: Id

This is a globally unique ID of this Ui, based on where in the hierarchy of widgets this Ui is in.

This means it is not stable, as it can change if new widgets are added or removed prior to this one. It should therefore only be used for transient interactions (clicks etc), not for storing state over time.

next_auto_id_salt: u64

This is used to create a unique interact ID for some widgets.

This value is based on where in the hierarchy of widgets this Ui is in, and the value is increment with each added child widget. This works as an Id source only as long as new widgets aren’t added or removed. They are therefore only good for Id:s that have no state.

painter: Painter

Specifies paint layer, clip rectangle and a reference to Context.

style: Arc<Style>

The Style (visuals, spacing, etc) of this ui. Commonly many Uis share the same Style. The Ui implements copy-on-write for this.

placer: Placer

Handles the Ui size and the placement of new widgets.

enabled: bool

If false we are unresponsive to input, and all widgets will assume a gray style.

sizing_pass: bool

Set to true in special cases where we do one frame where we size up the contents of the Ui, without actually showing it.

menu_state: Option<Arc<RwLock<MenuState>>>

Indicates whether this Ui belongs to a Menu.

stack: Arc<UiStack>

The UiStack for this Ui.

sense: Sense

The sense for the ui background.

min_rect_already_remembered: bool

Whether Ui::remember_min_rect should be called when the Ui is dropped. This is an optimization, so we don’t call Ui::remember_min_rect multiple times at the end of a Ui::scope.

Implementations

impl Ui

pub fn new(ctx: Context, id: Id, ui_builder: UiBuilder) -> Self

Create a new top-level Ui.

Normally you would not use this directly, but instead use crate::Panel, crate::CentralPanel, crate::Window or crate::Area.

pub fn child_ui( &mut self, max_rect: Rect, layout: Layout, ui_stack_info: Option<UiStackInfo>, ) -> Self

👎Deprecated: Use ui.new_child() instead

Create a new Ui at a specific region.

Note: calling this function twice from the same Ui will create a conflict of id. Use Self::scope if needed.

When in doubt, use None for the UiStackInfo argument.

pub fn child_ui_with_id_source( &mut self, max_rect: Rect, layout: Layout, id_salt: impl Hash, ui_stack_info: Option<UiStackInfo>, ) -> Self

👎Deprecated: Use ui.new_child() instead

Create a new Ui at a specific region with a specific id.

When in doubt, use None for the UiStackInfo argument.

pub fn new_child(&mut self, ui_builder: UiBuilder) -> Self

Create a child Ui with the properties of the given builder.

This is a very low-level function. Usually you are better off using Self::scope_builder.

Note that calling this does not allocate any space in the parent Ui, so after adding widgets to the child Ui you probably want to allocate the Ui::min_rect of the child in the parent Ui using e.g. Ui::advance_cursor_after_rect.

pub fn set_sizing_pass(&mut self)

👎Deprecated: Use UiBuilder.sizing_pass().invisible()

Set to true in special cases where we do one frame where we size up the contents of the Ui, without actually showing it.

This will also turn the Ui invisible. Should be called right after Self::new, if at all.

pub fn is_sizing_pass(&self) -> bool

Set to true in special cases where we do one frame where we size up the contents of the Ui, without actually showing it.

pub fn id(&self) -> Id

Generated based on id of parent ui together with an optional id salt.

This should be stable from one frame to next so it can be used as a source for storing state (e.g. window position, or if a collapsing header is open).

However, it is not necessarily globally unique. For instance, sibling Uis share the same Self::id unless they were explicitly given different id salts using UiBuilder::id_salt.

pub fn unique_id(&self) -> Id

This is a globally unique ID of this Ui, based on where in the hierarchy of widgets this Ui is in.

This means it is not stable, as it can change if new widgets are added or removed prior to this one. It should therefore only be used for transient interactions (clicks etc), not for storing state over time.

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

Style options for this Ui and its children.

Note that this may be a different Style than that of Context::style.

pub fn style_mut(&mut self) -> &mut Style

Mutably borrow internal Style. Changes apply to this Ui and its subsequent children.

To set the style of all Uis, use Context::set_style_of.

Example:

ui.style_mut().override_text_style = Some(egui::TextStyle::Heading);

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

Changes apply to this Ui and its subsequent children.

To set the style of all Uis, use Context::set_style_of.

pub fn reset_style(&mut self)

Reset to the default style set in Context.

pub fn spacing(&self) -> &Spacing

The current spacing options for this Ui. Short for ui.style().spacing.

pub fn spacing_mut(&mut self) -> &mut Spacing

Mutably borrow internal Spacing. Changes apply to this Ui and its subsequent children.

Example:

ui.spacing_mut().item_spacing = egui::vec2(10.0, 2.0);

pub fn visuals(&self) -> &Visuals

The current visuals settings of this Ui. Short for ui.style().visuals.

pub fn visuals_mut(&mut self) -> &mut Visuals

Mutably borrow internal visuals. Changes apply to this Ui and its subsequent children.

To set the visuals of all Uis, use Context::set_visuals_of.

Example:

ui.visuals_mut().override_text_color = Some(egui::Color32::RED);

pub fn is_tooltip(&self) -> bool

Is this Ui in a tooltip?

pub fn stack(&self) -> &Arc<UiStack>

Get a reference to this Ui’s UiStack.

pub fn ctx(&self) -> &Context

Get a reference to the parent Context.

pub fn painter(&self) -> &Painter

Use this to paint stuff within this Ui.

pub fn pixels_per_point(&self) -> f32

Number of physical pixels for each logical UI point.

pub fn is_enabled(&self) -> bool

If false, the Ui does not allow any interaction and the widgets in it will draw with a gray look.

pub fn disable(&mut self)

Calling disable() will cause the Ui to deny all future interaction and all the widgets will draw with a gray look.

Usually it is more convenient to use Self::add_enabled_ui or Self::add_enabled.

Note that once disabled, there is no way to re-enable the Ui.

Example

ui.group(|ui| {
    ui.checkbox(&mut enabled, "Enable subsection");
    if !enabled {
        ui.disable();
    }
    if ui.button("Button that is not always clickable").clicked() {
        /* … */
    }
});

pub fn set_enabled(&mut self, enabled: bool)

👎Deprecated: Use disable(), add_enabled_ui(), or add_enabled() instead

Calling set_enabled(false) will cause the Ui to deny all future interaction and all the widgets will draw with a gray look.

Usually it is more convenient to use Self::add_enabled_ui or Self::add_enabled.

Calling set_enabled(true) has no effect - it will NOT re-enable the Ui once disabled.

Example

ui.group(|ui| {
    ui.checkbox(&mut enabled, "Enable subsection");
    ui.set_enabled(enabled);
    if ui.button("Button that is not always clickable").clicked() {
        /* … */
    }
});

pub fn is_visible(&self) -> bool

If false, any widgets added to the Ui will be invisible and non-interactive.

This is false if any parent had UiBuilder::invisible or if Context::will_discard.

pub fn set_invisible(&mut self)

Calling set_invisible() will cause all further widgets to be invisible, yet still allocate space.

The widgets will not be interactive (set_invisible() implies disable()).

Once invisible, there is no way to make the Ui visible again.

Usually it is more convenient to use Self::add_visible_ui or Self::add_visible.

Example

ui.group(|ui| {
    ui.checkbox(&mut visible, "Show subsection");
    if !visible {
        ui.set_invisible();
    }
    if ui.button("Button that is not always shown").clicked() {
        /* … */
    }
});

pub fn set_visible(&mut self, visible: bool)

👎Deprecated: Use set_invisible(), add_visible_ui(), or add_visible() instead

Calling set_visible(false) will cause all further widgets to be invisible, yet still allocate space.

The widgets will not be interactive (set_visible(false) implies set_enabled(false)).

Calling set_visible(true) has no effect.

Example

ui.group(|ui| {
    ui.checkbox(&mut visible, "Show subsection");
    ui.set_visible(visible);
    if ui.button("Button that is not always shown").clicked() {
        /* … */
    }
});

pub fn set_opacity(&mut self, opacity: f32)

Make the widget in this Ui semi-transparent.

opacity must be between 0.0 and 1.0, where 0.0 means fully transparent (i.e., invisible) and 1.0 means fully opaque.

Example

ui.group(|ui| {
    ui.set_opacity(0.5);
    if ui.button("Half-transparent button").clicked() {
        /* … */
    }
});

See also: Self::opacity and Self::multiply_opacity.

pub fn multiply_opacity(&mut self, opacity: f32)

Like Self::set_opacity, but multiplies the given value with the current opacity.

See also: Self::set_opacity and Self::opacity.

pub fn opacity(&self) -> f32

Read the current opacity of the underlying painter.

See also: Self::set_opacity and Self::multiply_opacity.

pub fn layout(&self) -> &Layout

Read the Layout.

pub fn wrap_mode(&self) -> TextWrapMode

Which wrap mode should the text use in this Ui?

This is determined first by Style::wrap_mode, and then by the layout of this Ui.

pub fn wrap_text(&self) -> bool

👎Deprecated: Use wrap_mode instead

Should text wrap in this Ui?

This is determined first by Style::wrap_mode, and then by the layout of this Ui.

pub fn text_valign(&self) -> Align

How to vertically align text

pub fn painter_at(&self, rect: Rect) -> Painter

Create a painter for a sub-region of this Ui.

The clip-rect of the returned Painter will be the intersection of the given rectangle and the clip_rect() of this Ui.

pub fn layer_id(&self) -> LayerId

Use this to paint stuff within this Ui.

pub fn text_style_height(&self, style: &TextStyle) -> f32

The height of text of this text style.

Returns a value rounded to emath::GUI_ROUNDING.

pub fn clip_rect(&self) -> Rect

Screen-space rectangle for clipping what we paint in this ui. This is used, for instance, to avoid painting outside a window that is smaller than its contents.

pub fn shrink_clip_rect(&mut self, new_clip_rect: Rect)

Constrain the rectangle in which we can paint.

Short for ui.set_clip_rect(ui.clip_rect().intersect(new_clip_rect)).

See also: Self::clip_rect and Self::set_clip_rect.

pub fn set_clip_rect(&mut self, clip_rect: Rect)

Screen-space rectangle for clipping what we paint in this ui. This is used, for instance, to avoid painting outside a window that is smaller than its contents.

Warning: growing the clip rect might cause unexpected results! When in doubt, use Self::shrink_clip_rect instead.

pub fn is_rect_visible(&self, rect: Rect) -> bool

Can be used for culling: if false, then no part of rect will be visible on screen.

This is false if the whole Ui is invisible (see UiBuilder::invisible) or if Context::will_discard is true.

impl Ui

Sizes etc

pub fn min_rect(&self) -> Rect

Where and how large the Ui is already. All widgets that have been added to this Ui fits within this rectangle.

No matter what, the final Ui will be at least this large.

This will grow as new widgets are added, but never shrink.

pub fn min_size(&self) -> Vec2

Size of content; same as min_rect().size()

pub fn max_rect(&self) -> Rect

New widgets will try to fit within this rectangle.

Text labels will wrap to fit within max_rect. Separator lines will span the max_rect.

If a new widget doesn’t fit within the max_rect then the Ui will make room for it by expanding both min_rect and max_rect.

pub(crate) fn force_set_min_rect(&mut self, min_rect: Rect)

Used for animation, kind of hacky

pub fn set_max_size(&mut self, size: Vec2)

Set the maximum size of the ui. You won’t be able to shrink it below the current minimum size.

pub fn set_max_width(&mut self, width: f32)

Set the maximum width of the ui. You won’t be able to shrink it below the current minimum size.

pub fn set_max_height(&mut self, height: f32)

Set the maximum height of the ui. You won’t be able to shrink it below the current minimum size.

pub fn set_min_size(&mut self, size: Vec2)

Set the minimum size of the ui. This can’t shrink the ui, only make it larger.

pub fn set_min_width(&mut self, width: f32)

Set the minimum width of the ui. This can’t shrink the ui, only make it larger.

pub fn set_min_height(&mut self, height: f32)

Set the minimum height of the ui. This can’t shrink the ui, only make it larger.

pub fn take_available_space(&mut self)

Makes the ui always fill up the available space.

This can be useful to call inside a panel with resizable == true to make sure the resized space is used.

pub fn take_available_width(&mut self)

Makes the ui always fill up the available space in the x axis.

This can be useful to call inside a side panel with resizable == true to make sure the resized space is used.

pub fn take_available_height(&mut self)

Makes the ui always fill up the available space in the y axis.

This can be useful to call inside a top bottom panel with resizable == true to make sure the resized space is used.

pub fn shrink_width_to_current(&mut self)

Helper: shrinks the max width to the current width, so further widgets will try not to be wider than previous widgets. Useful for normal vertical layouts.

pub fn shrink_height_to_current(&mut self)

Helper: shrinks the max height to the current height, so further widgets will try not to be taller than previous widgets.

pub fn expand_to_include_rect(&mut self, rect: Rect)

Expand the min_rect and max_rect of this ui to include a child at the given rect.

pub fn set_width_range(&mut self, width: impl Into<Rangef>)

ui.set_width_range(min..=max); is equivalent to ui.set_min_width(min); ui.set_max_width(max);.

pub fn set_height_range(&mut self, height: impl Into<Rangef>)

ui.set_height_range(min..=max); is equivalent to ui.set_min_height(min); ui.set_max_height(max);.

pub fn set_width(&mut self, width: f32)

Set both the minimum and maximum width.

pub fn set_height(&mut self, height: f32)

Set both the minimum and maximum height.

pub fn expand_to_include_x(&mut self, x: f32)

Ensure we are big enough to contain the given x-coordinate. This is sometimes useful to expand a ui to stretch to a certain place.

pub fn expand_to_include_y(&mut self, y: f32)

Ensure we are big enough to contain the given y-coordinate. This is sometimes useful to expand a ui to stretch to a certain place.

pub fn available_size(&self) -> Vec2

The available space at the moment, given the current cursor.

This how much more space we can take up without overflowing our parent. Shrinks as widgets allocate space and the cursor moves. A small size should be interpreted as “as little as possible”. An infinite size should be interpreted as “as much as you want”.

pub fn available_width(&self) -> f32

The available width at the moment, given the current cursor.

See Self::available_size for more information.

pub fn available_height(&self) -> f32

The available height at the moment, given the current cursor.

See Self::available_size for more information.

pub fn available_size_before_wrap(&self) -> Vec2

In case of a wrapping layout, how much space is left on this row/column?

If the layout does not wrap, this will return the same value as Self::available_size.

pub fn available_rect_before_wrap(&self) -> Rect

In case of a wrapping layout, how much space is left on this row/column?

If the layout does not wrap, this will return the same value as Self::available_size.

impl Ui

Id

creation

pub fn make_persistent_id<IdSource>(&self, id_salt: IdSource) -> Id

where IdSource: Hash,

Use this to generate widget ids for widgets that have persistent state in Memory.

pub fn next_auto_id(&self) -> Id

This is the Id that will be assigned to the next widget added to this Ui.

pub fn auto_id_with<IdSource>(&self, id_salt: IdSource) -> Id

where IdSource: Hash,

Same as ui.next_auto_id().with(id_salt)

pub fn skip_ahead_auto_ids(&mut self, count: usize)

Pretend like count widgets have been allocated.

impl Ui

Interaction

pub fn interact(&self, rect: Rect, id: Id, sense: Sense) -> Response

Check for clicks, drags and/or hover on a specific region of this Ui.

pub fn interact_opt( &self, rect: Rect, id: Id, sense: Sense, options: InteractOptions, ) -> Response

Check for clicks, drags and/or hover on a specific region of this Ui.

pub fn interact_with_hovered( &self, rect: Rect, _contains_pointer: bool, id: Id, sense: Sense, ) -> Response

👎Deprecated: The contains_pointer argument is ignored. Use ui.interact instead.

Deprecated: use Self::interact instead.

pub fn response(&self) -> Response

Read the Ui’s background Response. Its Sense will be based on the UiBuilder::sense used to create this Ui.

The rectangle of the Response (and interactive area) will be Self::min_rect of the last pass.

The very first time when the Ui is created, this will return a Response with a Rect of Rect::NOTHING.

fn remember_min_rect(&mut self) -> Response

Update the WidgetRect created in Ui::new or Ui::new_child with the current Ui::min_rect.

pub fn interact_bg(&self, sense: Sense) -> Response

👎Deprecated: Use UiBuilder::sense with Ui::response instead

Interact with the background of this Ui, i.e. behind all the widgets.

The rectangle of the Response (and interactive area) will be Self::min_rect.

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

Is the pointer (mouse/touch) above this rectangle in this Ui?

The clip_rect and layer of this Ui will be respected, so, for instance, if this Ui is behind some other window, this will always return false.

However, this will NOT check if any other widget in the same layer is covering this widget. For that, use Response::contains_pointer instead.

pub fn ui_contains_pointer(&self) -> bool

Is the pointer (mouse/touch) above the current Ui?

Equivalent to ui.rect_contains_pointer(ui.min_rect())

Note that this tests against the current Ui::min_rect. If you want to test against the final min_rect, use Self::response instead.

pub fn close(&self)

Find and close the first closable parent.

Use UiBuilder::closable to make a Ui closable. You can then use Ui::should_close to check if it should be closed.

This is implemented for all egui containers, e.g. crate::Popup, crate::Modal, crate::Area, crate::Window, crate::CollapsingHeader, etc.

What exactly happens when you close a container depends on the container implementation. crate::Area e.g. will return true from its Response::should_close method.

If you want to close a specific kind of container, use Ui::close_kind instead.

Also note that this won’t bubble up across crate::Areas. If needed, you can check response.should_close() and close the parent manually. (menu does this for example).

See also:

• Ui::close_kind
• Ui::should_close
• Ui::will_parent_close

pub fn close_kind(&self, ui_kind: UiKind)

Find and close the first closable parent of a specific UiKind.

This is useful if you want to e.g. close a crate::Window. Since it contains a Collapsible, Ui::close would close the Collapsible instead. You can close the crate::Window by calling ui.close_kind(UiKind::Window).

See also:

• Ui::close
• Ui::should_close
• Ui::will_parent_close

pub fn should_close(&self) -> bool

Was Ui::close called on this Ui or any of its children? Only works if the Ui was created with UiBuilder::closable.

You can also check via this Ui’s Response::should_close.

See also:

• Ui::will_parent_close
• Ui::close
• Ui::close_kind
• Response::should_close

pub fn will_parent_close(&self) -> bool

Will this Ui or any of its parents close this frame?

See also

• Ui::should_close
• Ui::close
• Ui::close_kind

impl Ui

Allocating space: where do I put my widgets?

pub fn allocate_response( &mut self, desired_size: Vec2, sense: Sense, ) -> Response

Allocate space for a widget and check for interaction in the space. Returns a Response which contains a rectangle, id, and interaction info.

How sizes are negotiated

Each widget should have a minimum desired size and a desired size. When asking for space, ask AT LEAST for your minimum, and don’t ask for more than you need. If you want to fill the space, ask about Ui::available_size and use that.

You may get MORE space than you asked for, for instance for justified layouts, like in menus.

You will never get a rectangle that is smaller than the amount of space you asked for.

let response = ui.allocate_response(egui::vec2(100.0, 200.0), egui::Sense::click());
if response.clicked() { /* … */ }
ui.painter().rect_stroke(response.rect, 0.0, (1.0, egui::Color32::WHITE), egui::StrokeKind::Inside);

pub fn allocate_exact_size( &mut self, desired_size: Vec2, sense: Sense, ) -> (Rect, Response)

Returns a Rect with exactly what you asked for.

The response rect will be larger if this is part of a justified layout or similar. This means that if this is a narrow widget in a wide justified layout, then the widget will react to interactions outside the returned Rect.

pub fn allocate_at_least( &mut self, desired_size: Vec2, sense: Sense, ) -> (Rect, Response)

Allocate at least as much space as needed, and interact with that rect.

The returned Rect will be the same size as Response::rect.

pub fn allocate_space(&mut self, desired_size: Vec2) -> (Id, Rect)

Reserve this much space and move the cursor. Returns where to put the widget.

How sizes are negotiated

Each widget should have a minimum desired size and a desired size. When asking for space, ask AT LEAST for your minimum, and don’t ask for more than you need. If you want to fill the space, ask about Ui::available_size and use that.

You may get MORE space than you asked for, for instance for justified layouts, like in menus.

You will never get a rectangle that is smaller than the amount of space you asked for.

Returns an automatic Id (which you can use for interaction) and the Rect of where to put your widget.

let (id, rect) = ui.allocate_space(egui::vec2(100.0, 200.0));
let response = ui.interact(rect, id, egui::Sense::click());

fn allocate_space_impl(&mut self, desired_size: Vec2) -> Rect

Reserve this much space and move the cursor. Returns where to put the widget.

pub fn allocate_rect(&mut self, rect: Rect, sense: Sense) -> Response

Allocate a specific part of the Ui.

Ignore the layout of the Ui: just put my widget here! The layout cursor will advance to past this rect.

pub fn advance_cursor_after_rect(&mut self, rect: Rect) -> Id

Allocate a rect without interacting with it.

pub(crate) fn placer(&self) -> &Placer

pub fn cursor(&self) -> Rect

Where the next widget will be put.

One side of this will always be infinite: the direction in which new widgets will be added. The opposing side is what is incremented. The crossing sides are initialized to max_rect.

So one can think of cursor as a constraint on the available region.

If something has already been added, this will point to style.spacing.item_spacing beyond the latest child. The cursor can thus be style.spacing.item_spacing pixels outside of the min_rect.

pub(crate) fn set_cursor(&mut self, cursor: Rect)

pub fn next_widget_position(&self) -> Pos2

Where do we expect a zero-sized widget to be placed?

pub fn allocate_ui<R>( &mut self, desired_size: Vec2, add_contents: impl FnOnce(&mut Self) -> R, ) -> InnerResponse<R>

Allocated the given space and then adds content to that space. If the contents overflow, more space will be allocated. When finished, the amount of space actually used (min_rect) will be allocated. So you can request a lot of space and then use less.

pub fn allocate_ui_with_layout<R>( &mut self, desired_size: Vec2, layout: Layout, add_contents: impl FnOnce(&mut Self) -> R, ) -> InnerResponse<R>

Allocated the given space and then adds content to that space. If the contents overflow, more space will be allocated. When finished, the amount of space actually used (min_rect) will be allocated. So you can request a lot of space and then use less.

fn allocate_ui_with_layout_dyn<'c, R>( &mut self, desired_size: Vec2, layout: Layout, add_contents: Box<dyn FnOnce(&mut Self) -> R + 'c>, ) -> InnerResponse<R>

pub fn allocate_ui_at_rect<R>( &mut self, max_rect: Rect, add_contents: impl FnOnce(&mut Self) -> R, ) -> InnerResponse<R>

👎Deprecated: Use allocate_new_ui instead

Allocated the given rectangle and then adds content to that rectangle.

If the contents overflow, more space will be allocated. When finished, the amount of space actually used (min_rect) will be allocated. So you can request a lot of space and then use less.

pub fn allocate_new_ui<R>( &mut self, ui_builder: UiBuilder, add_contents: impl FnOnce(&mut Self) -> R, ) -> InnerResponse<R>

👎Deprecated: Use scope_builder instead

Allocated space (UiBuilder::max_rect) and then add content to it.

If the contents overflow, more space will be allocated. When finished, the amount of space actually used (min_rect) will be allocated in the parent. So you can request a lot of space and then use less.

pub fn allocate_painter( &mut self, desired_size: Vec2, sense: Sense, ) -> (Response, Painter)

Convenience function to get a region to paint on.

Note that egui uses screen coordinates for everything.

let size = Vec2::splat(16.0);
let (response, painter) = ui.allocate_painter(size, Sense::hover());
let rect = response.rect;
let c = rect.center();
let r = rect.width() / 2.0 - 1.0;
let color = Color32::from_gray(128);
let stroke = Stroke::new(1.0, color);
painter.circle_stroke(c, r, stroke);
painter.line_segment([c - vec2(0.0, r), c + vec2(0.0, r)], stroke);
painter.line_segment([c, c + r * Vec2::angled(TAU * 1.0 / 8.0)], stroke);
painter.line_segment([c, c + r * Vec2::angled(TAU * 3.0 / 8.0)], stroke);

impl Ui

Scrolling

pub fn scroll_to_rect(&self, rect: Rect, align: Option<Align>)

Adjust the scroll position of any parent crate::ScrollArea so that the given Rect becomes visible.

If align is Align::TOP it means “put the top of the rect at the top of the scroll area”, etc. If align is None, it’ll scroll enough to bring the cursor into view.

See also: Response::scroll_to_me, Ui::scroll_to_cursor. Ui::scroll_with_delta..

egui::ScrollArea::vertical().show(ui, |ui| {
    // …
    let response = ui.button("Center on me.");
    if response.clicked() {
        ui.scroll_to_rect(response.rect, Some(Align::Center));
    }
});

pub fn scroll_to_rect_animation( &self, rect: Rect, align: Option<Align>, animation: ScrollAnimation, )

Same as Self::scroll_to_rect, but allows you to specify the style::ScrollAnimation.

pub fn scroll_to_cursor(&self, align: Option<Align>)

Adjust the scroll position of any parent crate::ScrollArea so that the cursor (where the next widget goes) becomes visible.

If align is Align::TOP it means “put the top of the rect at the top of the scroll area”, etc. If align is not provided, it’ll scroll enough to bring the cursor into view.

See also: Response::scroll_to_me, Ui::scroll_to_rect. Ui::scroll_with_delta.

egui::ScrollArea::vertical().show(ui, |ui| {
    let scroll_bottom = ui.button("Scroll to bottom.").clicked();
    for i in 0..1000 {
        ui.label(format!("Item {}", i));
    }

    if scroll_bottom {
        ui.scroll_to_cursor(Some(Align::BOTTOM));
    }
});

pub fn scroll_to_cursor_animation( &self, align: Option<Align>, animation: ScrollAnimation, )

Same as Self::scroll_to_cursor, but allows you to specify the style::ScrollAnimation.

pub fn scroll_with_delta(&self, delta: Vec2)

Scroll this many points in the given direction, in the parent crate::ScrollArea.

The delta dictates how the content (i.e. this UI) should move.

A positive X-value indicates the content is being moved right, as when swiping right on a touch-screen or track-pad with natural scrolling.

A positive Y-value indicates the content is being moved down, as when swiping down on a touch-screen or track-pad with natural scrolling.

If this is called multiple times per frame for the same crate::ScrollArea, the deltas will be summed.

See also: Response::scroll_to_me, Ui::scroll_to_rect, Ui::scroll_to_cursor

let mut scroll_delta = Vec2::ZERO;
if ui.button("Scroll down").clicked() {
    scroll_delta.y -= 64.0; // move content up
}
egui::ScrollArea::vertical().show(ui, |ui| {
    ui.scroll_with_delta(scroll_delta);
    for i in 0..1000 {
        ui.label(format!("Item {}", i));
    }
});

pub fn scroll_with_delta_animation( &self, delta: Vec2, animation: ScrollAnimation, )

Same as Self::scroll_with_delta, but allows you to specify the style::ScrollAnimation.

impl Ui

Adding widgets

pub fn add(&mut self, widget: impl Widget) -> Response

Add a Widget to this Ui at a location dependent on the current Layout.

The returned Response can be used to check for interactions, as well as adding tooltips using Response::on_hover_text.

See also Self::add_sized, Self::place and Self::put.

let response = ui.add(egui::Slider::new(&mut my_value, 0..=100));
response.on_hover_text("Drag me!");

pub fn add_sized( &mut self, max_size: impl Into<Vec2>, widget: impl Widget, ) -> Response

Add a Widget to this Ui with a given size. The widget will attempt to fit within the given size, but some widgets may overflow.

To fill all remaining area, use ui.add_sized(ui.available_size(), widget);

See also Self::add, Self::place and Self::put.

ui.add_sized([40.0, 20.0], egui::DragValue::new(&mut my_value));

pub fn place(&mut self, max_rect: Rect, widget: impl Widget) -> Response

Add a Widget to this Ui at a specific location (manual layout) without affecting this Uis cursor.

See also Self::add and Self::add_sized and Self::put.

pub fn put(&mut self, max_rect: Rect, widget: impl Widget) -> Response

Add a Widget to this Ui at a specific location (manual layout) and advance the cursor after the widget.

See also Self::add, Self::add_sized, and Self::place.

pub fn add_enabled(&mut self, enabled: bool, widget: impl Widget) -> Response

Add a single Widget that is possibly disabled, i.e. greyed out and non-interactive.

If you call add_enabled from within an already disabled Ui, the widget will always be disabled, even if the enabled argument is true.

See also Self::add_enabled_ui and Self::is_enabled.

ui.add_enabled(false, egui::Button::new("Can't click this"));

pub fn add_enabled_ui<R>( &mut self, enabled: bool, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<R>

Add a section that is possibly disabled, i.e. greyed out and non-interactive.

If you call add_enabled_ui from within an already disabled Ui, the result will always be disabled, even if the enabled argument is true.

See also Self::add_enabled and Self::is_enabled.

Example

ui.checkbox(&mut enabled, "Enable subsection");
ui.add_enabled_ui(enabled, |ui| {
    if ui.button("Button that is not always clickable").clicked() {
        /* … */
    }
});

pub fn add_visible(&mut self, visible: bool, widget: impl Widget) -> Response

Add a single Widget that is possibly invisible.

An invisible widget still takes up the same space as if it were visible.

If you call add_visible from within an already invisible Ui, the widget will always be invisible, even if the visible argument is true.

See also Self::add_visible_ui, Self::set_visible and Self::is_visible.

ui.add_visible(false, egui::Label::new("You won't see me!"));

pub fn add_visible_ui<R>( &mut self, visible: bool, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<R>

👎Deprecated: Use ‘ui.scope_builder’ instead

Add a section that is possibly invisible, i.e. greyed out and non-interactive.

An invisible ui still takes up the same space as if it were visible.

If you call add_visible_ui from within an already invisible Ui, the result will always be invisible, even if the visible argument is true.

See also Self::add_visible, Self::set_visible and Self::is_visible.

Example

ui.checkbox(&mut visible, "Show subsection");
ui.add_visible_ui(visible, |ui| {
    ui.label("Maybe you see this, maybe you don't!");
});

pub fn add_space(&mut self, amount: f32)

Add extra space before the next widget.

The direction is dependent on the layout. Note that add_space isn’t supported when in a grid layout.

This will be in addition to the crate::style::Spacing::item_spacing that is always added, but item_spacing won’t be added again by add_space.

Self::min_rect will expand to contain the space.

pub fn label(&mut self, text: impl Into<WidgetText>) -> Response

Show some text.

Shortcut for add(Label::new(text))

See also Label.

Example

use egui::{RichText, FontId, Color32};
ui.label("Normal text");
ui.label(RichText::new("Large text").font(FontId::proportional(40.0)));
ui.label(RichText::new("Red text").color(Color32::RED));

pub fn colored_label( &mut self, color: impl Into<Color32>, text: impl Into<RichText>, ) -> Response

Show colored text.

Shortcut for ui.label(RichText::new(text).color(color))

pub fn heading(&mut self, text: impl Into<RichText>) -> Response

Show large text.

Shortcut for ui.label(RichText::new(text).heading())

pub fn monospace(&mut self, text: impl Into<RichText>) -> Response

Show monospace (fixed width) text.

Shortcut for ui.label(RichText::new(text).monospace())

pub fn code(&mut self, text: impl Into<RichText>) -> Response

Show text as monospace with a gray background.

Shortcut for ui.label(RichText::new(text).code())

pub fn small(&mut self, text: impl Into<RichText>) -> Response

Show small text.

Shortcut for ui.label(RichText::new(text).small())

pub fn strong(&mut self, text: impl Into<RichText>) -> Response

Show text that stand out a bit (e.g. slightly brighter).

Shortcut for ui.label(RichText::new(text).strong())

pub fn weak(&mut self, text: impl Into<RichText>) -> Response

Show text that is weaker (fainter color).

Shortcut for ui.label(RichText::new(text).weak())

pub fn link(&mut self, text: impl Into<WidgetText>) -> Response

Looks like a hyperlink.

Shortcut for add(Link::new(text)).

if ui.link("Documentation").clicked() {
    // …
}

See also Link.

pub fn hyperlink(&mut self, url: impl ToString) -> Response

Link to a web page.

Shortcut for add(Hyperlink::new(url)).

ui.hyperlink("https://www.egui.rs/");

See also Hyperlink.

pub fn hyperlink_to( &mut self, label: impl Into<WidgetText>, url: impl ToString, ) -> Response

Shortcut for add(Hyperlink::from_label_and_url(label, url)).

ui.hyperlink_to("egui on GitHub", "https://www.github.com/emilk/egui/");

See also Hyperlink.

pub fn text_edit_singleline<S: TextBuffer>(&mut self, text: &mut S) -> Response

No newlines (\n) allowed. Pressing enter key will result in the TextEdit losing focus (response.lost_focus).

See also TextEdit.

pub fn text_edit_multiline<S: TextBuffer>(&mut self, text: &mut S) -> Response

A TextEdit for multiple lines. Pressing enter key will create a new line.

See also TextEdit.

pub fn code_editor<S: TextBuffer>(&mut self, text: &mut S) -> Response

A TextEdit for code editing.

This will be multiline, monospace, and will insert tabs instead of moving focus.

See also TextEdit::code_editor.

pub fn button<'a>(&mut self, atoms: impl IntoAtoms<'a>) -> Response

Usage: if ui.button("Click me").clicked() { … }

Shortcut for add(Button::new(text))

See also Button.

if ui.button("Click me!").clicked() {
    // …
}

if ui.button(RichText::new("delete").color(Color32::RED)).clicked() {
    // …
}

pub fn small_button(&mut self, text: impl Into<WidgetText>) -> Response

A button as small as normal body text.

Usage: if ui.small_button("Click me").clicked() { … }

Shortcut for add(Button::new(text).small())

pub fn checkbox<'a>( &mut self, checked: &'a mut bool, atoms: impl IntoAtoms<'a>, ) -> Response

Show a checkbox.

See also Self::toggle_value.

pub fn toggle_value<'a>( &mut self, selected: &mut bool, atoms: impl IntoAtoms<'a>, ) -> Response

Acts like a checkbox, but looks like a Button::selectable.

Click to toggle to bool.

See also Self::checkbox.

pub fn radio<'a>( &mut self, selected: bool, atoms: impl IntoAtoms<'a>, ) -> Response

Show a RadioButton. Often you want to use Self::radio_value instead.

pub fn radio_value<'a, Value: PartialEq>( &mut self, current_value: &mut Value, alternative: Value, atoms: impl IntoAtoms<'a>, ) -> Response

Show a RadioButton. It is selected if *current_value == selected_value. If clicked, selected_value is assigned to *current_value.

#[derive(PartialEq)]
enum Enum { First, Second, Third }
let mut my_enum = Enum::First;

ui.radio_value(&mut my_enum, Enum::First, "First");

// is equivalent to:

if ui.add(egui::RadioButton::new(my_enum == Enum::First, "First")).clicked() {
    my_enum = Enum::First
}

pub fn selectable_label<'a>( &mut self, checked: bool, text: impl IntoAtoms<'a>, ) -> Response

Show a label which can be selected or not.

See also Button::selectable and Self::toggle_value.

pub fn selectable_value<'a, Value: PartialEq>( &mut self, current_value: &mut Value, selected_value: Value, text: impl IntoAtoms<'a>, ) -> Response

Show selectable text. It is selected if *current_value == selected_value. If clicked, selected_value is assigned to *current_value.

Example: ui.selectable_value(&mut my_enum, Enum::Alternative, "Alternative").

See also Button::selectable and Self::toggle_value.

pub fn separator(&mut self) -> Response

Shortcut for add(Separator::default())

See also Separator.

pub fn spinner(&mut self) -> Response

Shortcut for add(Spinner::new())

See also Spinner.

pub fn drag_angle(&mut self, radians: &mut f32) -> Response

Modify an angle. The given angle should be in radians, but is shown to the user in degrees. The angle is NOT wrapped, so the user may select, for instance 720° = 2𝞃 = 4π

pub fn drag_angle_tau(&mut self, radians: &mut f32) -> Response

Modify an angle. The given angle should be in radians, but is shown to the user in fractions of one Tau (i.e. fractions of one turn). The angle is NOT wrapped, so the user may select, for instance 2𝞃 (720°)

pub fn image<'a>(&mut self, source: impl Into<ImageSource<'a>>) -> Response

Show an image available at the given uri.

⚠ This will do nothing unless you install some image loaders first! The easiest way to do this is via egui_extras::install_image_loaders.

The loaders handle caching image data, sampled textures, etc. across frames, so calling this is immediate-mode safe.

ui.image("https://picsum.photos/480");
ui.image("file://assets/ferris.png");
ui.image(egui::include_image!("../assets/ferris.png"));
ui.add(
    egui::Image::new(egui::include_image!("../assets/ferris.png"))
        .max_width(200.0)
        .corner_radius(10),
);

Using crate::include_image is often the most ergonomic, and the path will be resolved at compile-time and embedded in the binary. When using a “file://” url on the other hand, you need to make sure the files can be found in the right spot at runtime!

See also crate::Image, crate::ImageSource.

impl Ui

Colors

pub fn color_edit_button_srgba(&mut self, srgba: &mut Color32) -> Response

Shows a button with the given color.

If the user clicks the button, a full color picker is shown.

pub fn color_edit_button_hsva(&mut self, hsva: &mut Hsva) -> Response

Shows a button with the given color.

If the user clicks the button, a full color picker is shown.

pub fn color_edit_button_srgb(&mut self, srgb: &mut [u8; 3]) -> Response

Shows a button with the given color.

If the user clicks the button, a full color picker is shown. The given color is in sRGB space.

pub fn color_edit_button_rgb(&mut self, rgb: &mut [f32; 3]) -> Response

Shows a button with the given color.

If the user clicks the button, a full color picker is shown. The given color is in linear RGB space.

pub fn color_edit_button_srgba_premultiplied( &mut self, srgba: &mut [u8; 4], ) -> Response

Shows a button with the given color.

If the user clicks the button, a full color picker is shown. The given color is in sRGBA space with premultiplied alpha

pub fn color_edit_button_srgba_unmultiplied( &mut self, srgba: &mut [u8; 4], ) -> Response

Shows a button with the given color.

If the user clicks the button, a full color picker is shown. The given color is in sRGBA space without premultiplied alpha. If unsure what “premultiplied alpha” is, then this is probably the function you want to use.

pub fn color_edit_button_rgba_premultiplied( &mut self, rgba_premul: &mut [f32; 4], ) -> Response

Shows a button with the given color.

If the user clicks the button, a full color picker is shown. The given color is in linear RGBA space with premultiplied alpha

pub fn color_edit_button_rgba_unmultiplied( &mut self, rgba_unmul: &mut [f32; 4], ) -> Response

Shows a button with the given color.

If the user clicks the button, a full color picker is shown. The given color is in linear RGBA space without premultiplied alpha. If unsure, what “premultiplied alpha” is, then this is probably the function you want to use.

impl Ui

Adding Containers / Sub-uis:

pub fn group<R>( &mut self, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<R>

Put into a Frame::group, visually grouping the contents together

ui.group(|ui| {
    ui.label("Within a frame");
});

See also Self::scope.

pub fn push_id<R>( &mut self, id_salt: impl Hash, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<R>

Create a child Ui with an explicit Id.

for i in 0..10 {
    // ui.collapsing("Same header", |ui| { }); // this will cause an ID clash because of the same title!

    ui.push_id(i, |ui| {
        ui.collapsing("Same header", |ui| { }); // this is fine!
    });
}

pub fn push_stack_info<R>( &mut self, ui_stack_info: UiStackInfo, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<R>

👎Deprecated: Use ‘ui.scope_builder’ instead

Push another level onto the UiStack.

You can use this, for instance, to tag a group of widgets.

pub fn scope<R>( &mut self, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<R>

Create a scoped child ui.

You can use this to temporarily change the Style of a sub-region, for instance:

ui.scope(|ui| {
    ui.spacing_mut().slider_width = 200.0; // Temporary change
    // …
});

pub fn scope_builder<R>( &mut self, ui_builder: UiBuilder, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<R>

Create a child, add content to it, and then allocate only what was used in the parent Ui.

pub fn scope_dyn<'c, R>( &mut self, ui_builder: UiBuilder, add_contents: Box<dyn FnOnce(&mut Ui) -> R + 'c>, ) -> InnerResponse<R>

Create a child, add content to it, and then allocate only what was used in the parent Ui.

pub fn with_layer_id<R>( &mut self, layer_id: LayerId, add_contents: impl FnOnce(&mut Self) -> R, ) -> InnerResponse<R>

👎Deprecated: Use ui.scope_builder(UiBuilder::new().layer_id(…), …) instead

Redirect shapes to another paint layer.

let layer_id = LayerId::new(Order::Tooltip, Id::new("my_floating_ui"));
ui.with_layer_id(layer_id, |ui| {
    ui.label("This is now in a different layer");
});

pub fn collapsing<R>( &mut self, heading: impl Into<WidgetText>, add_contents: impl FnOnce(&mut Ui) -> R, ) -> CollapsingResponse<R>

A CollapsingHeader that starts out collapsed.

The name must be unique within the current parent, or you need to use CollapsingHeader::id_salt.

pub fn indent<R>( &mut self, id_salt: impl Hash, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<R>

Create a child ui which is indented to the right.

The id_salt here be anything at all.

fn indent_dyn<'c, R>( &mut self, id_salt: impl Hash, add_contents: Box<dyn FnOnce(&mut Ui) -> R + 'c>, ) -> InnerResponse<R>

pub fn horizontal<R>( &mut self, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<R>

Start a ui with horizontal layout. After you have called this, the function registers the contents as any other widget.

Elements will be centered on the Y axis, i.e. adjusted up and down to lie in the center of the horizontal layout. The initial height is style.spacing.interact_size.y. Centering is almost always what you want if you are planning to mix widgets or use different types of text.

If you don’t want the contents to be centered, use Self::horizontal_top instead.

The returned Response will only have checked for mouse hover but can be used for tooltips (on_hover_text). It also contains the Rect used by the horizontal layout.

ui.horizontal(|ui| {
    ui.label("Same");
    ui.label("row");
});

See also Self::with_layout for more options.

pub fn horizontal_centered<R>( &mut self, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<R>

Like Self::horizontal, but allocates the full vertical height and then centers elements vertically.

pub fn horizontal_top<R>( &mut self, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<R>

Like Self::horizontal, but aligns content with top.

pub fn horizontal_wrapped<R>( &mut self, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<R>

Start a ui with horizontal layout that wraps to a new row when it reaches the right edge of the max_size. After you have called this, the function registers the contents as any other widget.

Elements will be centered on the Y axis, i.e. adjusted up and down to lie in the center of the horizontal layout. The initial height is style.spacing.interact_size.y. Centering is almost always what you want if you are planning to mix widgets or use different types of text.

The returned Response will only have checked for mouse hover but can be used for tooltips (on_hover_text). It also contains the Rect used by the horizontal layout.

See also Self::with_layout for more options.

fn horizontal_with_main_wrap_dyn<'c, R>( &mut self, main_wrap: bool, add_contents: Box<dyn FnOnce(&mut Ui) -> R + 'c>, ) -> InnerResponse<R>

pub fn vertical<R>( &mut self, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<R>

Start a ui with vertical layout. Widgets will be left-justified.

ui.vertical(|ui| {
    ui.label("over");
    ui.label("under");
});

See also Self::with_layout for more options.

pub fn vertical_centered<R>( &mut self, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<R>

Start a ui with vertical layout. Widgets will be horizontally centered.

ui.vertical_centered(|ui| {
    ui.label("over");
    ui.label("under");
});

pub fn vertical_centered_justified<R>( &mut self, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<R>

Start a ui with vertical layout. Widgets will be horizontally centered and justified (fill full width).

ui.vertical_centered_justified(|ui| {
    ui.label("over");
    ui.label("under");
});

pub fn with_layout<R>( &mut self, layout: Layout, add_contents: impl FnOnce(&mut Self) -> R, ) -> InnerResponse<R>

The new layout will take up all available space.

ui.with_layout(egui::Layout::right_to_left(egui::Align::TOP), |ui| {
    ui.label("world!");
    ui.label("Hello");
});

If you don’t want to use up all available space, use Self::allocate_ui_with_layout.

See also the helpers Self::horizontal, Self::vertical, etc.

pub fn centered_and_justified<R>( &mut self, add_contents: impl FnOnce(&mut Self) -> R, ) -> InnerResponse<R>

This will make the next added widget centered and justified in the available space.

Only one widget may be added to the inner Ui!

pub(crate) fn set_grid(&mut self, grid: GridLayout)

pub(crate) fn save_grid(&mut self)

pub(crate) fn is_grid(&self) -> bool

pub fn end_row(&mut self)

Move to the next row in a grid layout or wrapping layout. Otherwise does nothing.

pub fn set_row_height(&mut self, height: f32)

Set row height in horizontal wrapping layout.

pub fn columns<R>( &mut self, num_columns: usize, add_contents: impl FnOnce(&mut [Self]) -> R, ) -> R

Temporarily split a Ui into several columns.

ui.columns(2, |columns| {
    columns[0].label("First column");
    columns[1].label("Second column");
});

fn columns_dyn<'c, R>( &mut self, num_columns: usize, add_contents: Box<dyn FnOnce(&mut [Self]) -> R + 'c>, ) -> R

pub fn columns_const<const NUM_COL: usize, R>( &mut self, add_contents: impl FnOnce(&mut [Self; NUM_COL]) -> R, ) -> R

Temporarily split a Ui into several columns.

The same as Self::columns(), but uses a constant for the column count. This allows for compile-time bounds checking, and makes the compiler happy.

ui.columns_const(|[col_1, col_2]| {
    col_1.label("First column");
    col_2.label("Second column");
});

pub fn dnd_drag_source<Payload, R>( &mut self, id: Id, payload: Payload, add_contents: impl FnOnce(&mut Self) -> R, ) -> InnerResponse<R>

where Payload: Any + Send + Sync,

Create something that can be drag-and-dropped.

The id needs to be globally unique. The payload is what will be dropped if the user starts dragging.

In contrast to Response::dnd_set_drag_payload, this function will paint the widget at the mouse cursor while the user is dragging.

pub fn dnd_drop_zone<Payload, R>( &mut self, frame: Frame, add_contents: impl FnOnce(&mut Ui) -> R, ) -> (InnerResponse<R>, Option<Arc<Payload>>)

where Payload: Any + Send + Sync,

Surround the given ui with a frame which changes colors when you can drop something onto it.

Returns the dropped item, if it was released this frame.

The given frame is used for its margins, but the color is ignored.

pub fn with_visual_transform<R>( &mut self, transform: TSTransform, add_contents: impl FnOnce(&mut Self) -> R, ) -> InnerResponse<R>

Create a new Scope and transform its contents via a emath::TSTransform. This only affects visuals, inputs will not be transformed. So this is mostly useful to create visual effects on interactions, e.g. scaling a button on hover / click.

Check out Context::set_transform_layer for a persistent transform that also affects inputs.

impl Ui

Menus

pub fn close_menu(&self)

👎Deprecated: Use ui.close() or ui.close_kind(UiKind::Menu) instead

Close the menu we are in (including submenus), if any.

See also: Self::menu_button and Response::context_menu.

pub(crate) fn set_menu_state( &mut self, menu_state: Option<Arc<RwLock<MenuState>>>, )

pub fn menu_button<'a, R>( &mut self, atoms: impl IntoAtoms<'a>, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<Option<R>>

Create a menu button that when clicked will show the given menu.

If called from within a menu this will instead create a button for a sub-menu.

ui.menu_button("My menu", |ui| {
    ui.menu_button("My sub-menu", |ui| {
        if ui.button("Close the menu").clicked() {
            ui.close();
        }
    });
});

See also: Self::close and Response::context_menu.

pub fn menu_image_button<'a, R>( &mut self, image: impl Into<Image<'a>>, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<Option<R>>

Create a menu button with an image that when clicked will show the given menu.

If called from within a menu this will instead create a button for a sub-menu.

let img = egui::include_image!("../assets/ferris.png");

ui.menu_image_button(title, img, |ui| {
    ui.menu_button("My sub-menu", |ui| {
        if ui.button("Close the menu").clicked() {
            ui.close();
        }
    });
});

See also: Self::close and Response::context_menu.

pub fn menu_image_text_button<'a, R>( &mut self, image: impl Into<Image<'a>>, title: impl Into<WidgetText>, add_contents: impl FnOnce(&mut Ui) -> R, ) -> InnerResponse<Option<R>>

Create a menu button with an image and a text that when clicked will show the given menu.

If called from within a menu this will instead create a button for a sub-menu.

let img = egui::include_image!("../assets/ferris.png");
let title = "My Menu";

ui.menu_image_text_button(img, title, |ui| {
    ui.menu_button("My sub-menu", |ui| {
        if ui.button("Close the menu").clicked() {
            ui.close();
        }
    });
});

See also: Self::close and Response::context_menu.

impl Ui

Debug stuff

pub fn debug_paint_cursor(&self)

Shows where the next widget is going to be placed

Methods from Deref<Target = Context>

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

Do read-only (shared access) transaction on Context

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

Do read-write (exclusive access) transaction on Context

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

Run the ui code for one frame.

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.

The Ui given to the callback will cover the entire Self::content_rect, with no margin or background color. Use crate::Frame to add that.

You can organize your GUI using crate::Panel.

Instead of calling run_ui, 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_ui(input, |ui| {
    ui.label("Hello egui!");
});
// handle full_output

See also

• Self::run

fn run_ui_dyn( &self, new_input: RawInput, run_ui: &mut dyn FnMut(&mut Ui), ) -> FullOutput

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

👎Deprecated: Call run_ui instead

Run the ui code for one frame.

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::Panel, 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

See also

• Self::run_ui

fn run_dyn( &self, new_input: RawInput, run_ui: &mut dyn FnMut(&Self), ) -> FullOutput

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.

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(crate) fn pass_state<R>(&self, reader: impl FnOnce(&PassState) -> R) -> R

Read-only access to PassState.

This is only valid during the call to Self::run (between Self::begin_pass and Self::end_pass).

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

Read-write access to PassState.

This is only valid during the call to Self::run (between Self::begin_pass and Self::end_pass).

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

Read-only access to the PassState from the previous pass.

This is swapped at the end of each pass.

pub fn fonts<R>(&self, reader: impl FnOnce(&FontsView<'_>) -> 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, reader: impl FnOnce(&mut FontsView<'_>) -> R) -> R

Read-write 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(crate) fn create_widget( &self, w: WidgetRect, allow_focus: bool, options: InteractOptions, ) -> Response

Create a widget and check for interaction.

If this is not called, the widget doesn’t exist.

You should use Ui::interact instead.

If the widget already exists, its state (sense, Rect, etc) will be updated.

allow_focus should usually be true, unless you call this function multiple times with the same widget, then allow_focus should only be true once (like in Ui::new (true) and Ui::remember_min_rect (false)).

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.

If you try to read a Ui’s response, while still inside, this will return the Rect from the previous frame.

pub(crate) fn get_response(&self, widget_rect: WidgetRect) -> Response

Do all interaction for an existing widget, without (re-)registering it.

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 (even on top of tooltips and popups).

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 time(&self) -> f64

Current time in seconds, relative to some unknown epoch.

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 send_cmd(&self, cmd: OutputCommand)

Add a command to PlatformOutput::commands, for the integration to execute at the end of the frame.

pub fn open_url(&self, open_url: OpenUrl)

Open an URL in a browser.

Equivalent to:

ctx.send_cmd(egui::OutputCommand::OpenUrl(open_url));

pub fn copy_text(&self, text: String)

Copy the given text to the system clipboard.

Note that in web applications, the clipboard is only accessible in secure contexts (e.g., HTTPS or localhost). If this method is used outside of a secure context, it will log an error and do nothing. See https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts.

pub fn copy_image(&self, image: ColorImage)

Copy the given image to the system clipboard.

Note that in web applications, the clipboard is only accessible in secure contexts (e.g., HTTPS or localhost). If this method is used outside of a secure context, it will log an error and do nothing. See https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts.

fn can_show_modifier_symbols(&self) -> bool

pub fn format_modifiers(&self, modifiers: Modifiers) -> String

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

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_frame_nr(&self) -> u64

The total number of completed frames.

Starts at zero, and is incremented once at the end of each call to Self::run.

This is always smaller or equal to Self::cumulative_pass_nr.

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

The total number of completed frames.

Starts at zero, and is incremented once at the end of each call to Self::run.

This is always smaller or equal to Self::cumulative_pass_nr_for.

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

If you instead want to know which pass index this is within the current frame, use Self::current_pass_index.

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 current_pass_index(&self) -> usize

The index of the current pass in the current frame, starting at zero.

Usually this is zero, but if something called Self::request_discard to do multi-pass layout, then this will be incremented for each pass.

This just reads the value of PlatformOutput::num_completed_passes.

To know the total number of passes ever completed, use Self::cumulative_pass_nr.

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 (default=2). 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.

pub fn on_begin_pass(&self, debug_name: &'static str, cb: ContextCallback)

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

This is a convenience wrapper around Self::add_plugin.

pub fn on_end_pass(&self, debug_name: &'static str, cb: ContextCallback)

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

This is a convenience wrapper around Self::add_plugin.

pub fn add_plugin(&self, plugin: impl Plugin + 'static)

Register a Plugin

Plugins are called in the order they are added.

A plugin of the same type can only be added once (further calls with the same type will be ignored). This way it’s convenient to add plugins in eframe::run_simple_native.

pub fn with_plugin<T: Plugin + 'static, R>( &self, f: impl FnOnce(&mut T) -> R, ) -> Option<R>

Call the provided closure with the plugin of type T, if it was registered.

Returns None if the plugin was not registered.

pub fn plugin<T: Plugin>(&self) -> TypedPluginHandle<T>

Get a handle to the plugin of type T.

Panics

If the plugin of type T was not registered, this will panic.

pub fn plugin_opt<T: Plugin>(&self) -> Option<TypedPluginHandle<T>>

Get a handle to the plugin of type T, if it was registered.

pub fn plugin_or_default<T: Plugin + Default>(&self) -> TypedPluginHandle<T>

Get a handle to the plugin of type T, or insert its default.

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. This will overwrite the existing fonts.

pub fn add_font(&self, new_font: FontInsert)

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 font will become active at the start of the next pass. This will keep the existing fonts.

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 popups, menus, 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 popups, menus, etc.

Example:

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

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

The currently active Style used by all subsequent popups, menus, etc.

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

👎Deprecated: Renamed to global_style to avoid confusion with ui.style()

The currently active Style used by all subsequent popups, menus, etc.

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

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

Example:

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

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

👎Deprecated: Renamed to global_style_mut to avoid confusion with ui.style_mut()

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

Example:

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

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

The currently active Style used by all new popups, menus, etc.

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

You can also change this using Self::global_style_mut.

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

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

👎Deprecated: Renamed to set_global_style to avoid confusion with ui.set_style()

The currently active Style used by all new popups, menus, 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 popups, menus, 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 popups, menus, etc.

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

Mutate the Style used by all subsequent popups, menus, 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 popups, menus, 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 popups, menus, 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 popups, menus, 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.

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.

fn debug_painting(&self)

Called at the end of the pass.

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 content_rect(&self) -> Rect

Returns the position and size of the egui area that is safe for content rendering.

Returns Self::viewport_rect minus areas that might be partially covered by, for example, the OS status bar or display notches.

If you want to render behind e.g. the dynamic island on iOS, use Self::viewport_rect.

pub fn viewport_rect(&self) -> Rect

Returns the position and size of the full area available to egui

This includes reas that might be partially covered by, for example, the OS status bar or display notches. See Self::content_rect to get a rect that is safe for content.

This rectangle includes e.g. the dynamic island on iOS. If you want to only render below the that (not behind), then you should use Self::content_rect instead.

See also RawInput::safe_area_insets.

pub fn screen_rect(&self) -> Rect

👎Deprecated: screen_rect has been split into viewport_rect() and content_rect(). You likely should use content_rect()

Position and size of the egui area.

pub fn available_rect(&self) -> Rect

👎Deprecated: Use content_rect (or viewport_rect) instead

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

pub fn globally_used_rect(&self) -> Rect

How much space is used by windows and the top-level Ui.

pub fn used_rect(&self) -> Rect

👎Deprecated: Renamed to globally_used_rect

How much space is used by windows and the top-level Ui.

pub fn used_size(&self) -> Vec2

👎Deprecated: Use globally_used_rect instead

How much space is used by windows and the top-level Ui.

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

pub fn is_pointer_over_egui(&self) -> bool

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

pub fn is_pointer_over_area(&self) -> bool

👎Deprecated: Renamed to is_pointer_over_egui

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

pub fn egui_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 wants_pointer_input(&self) -> bool

👎Deprecated: Renamed to egui_wants_pointer_input

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 egui_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 is_using_pointer(&self) -> bool

👎Deprecated: Renamed to egui_is_using_pointer

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 egui_wants_keyboard_input(&self) -> bool

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

pub fn wants_keyboard_input(&self) -> bool

👎Deprecated: Renamed to egui_wants_keyboard_input

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

pub fn text_edit_focused(&self) -> bool

Is the currently focused widget a text edit?

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

👎Deprecated: Use any_popup_open instead

Is an egui context menu open?

This only works with the old, deprecated crate::menu API.

pub fn any_popup_open(&self) -> bool

Is a popup or (context) menu open?

Will return false for crate::Tooltips (which are technically popups as well).

pub fn is_popup_open(&self) -> bool

👎Deprecated: Renamed to any_popup_open

Is a popup or (context) menu open?

Will return false for crate::Tooltips (which are technically popups as well).

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

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

Transform the graphics of the given layer.

This will also affect input. The direction of the given transform is “into the global coordinate system”.

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 or Ui::with_visual_transform.

pub fn layer_transform_to_global( &self, layer_id: LayerId, ) -> Option<TSTransform>

Return how to transform the graphics of the given layer into the global coordinate system.

Set this with Self::layer_transform_to_global.

pub fn layer_transform_from_global( &self, layer_id: LayerId, ) -> Option<TSTransform>

Return how to transform the graphics of the global coordinate system into the local coordinate system of the given layer.

This returns the inverse of Self::layer_transform_to_global.

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

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 the reverse behavior.

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

Smoothly animate an f32 value.

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

pub fn clear_animations(&self)

Clear memory of any animations.

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

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

fn fonts_tweak_ui(&self, ui: &mut Ui)

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 loaders_ui(&self, ui: &mut Ui)

Show stats about different image loaders.

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

Shows the contents of Self::memory.

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

Edit the Style.

pub fn accesskit_node_builder<R>( &self, id: Id, writer: impl FnOnce(&mut Node) -> 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 parent Uis ID. And an Uis parent can be set with UiBuilder::accessibility_parent.

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

Returns None if accesskit is off.

pub(crate) fn register_accesskit_parent(&self, id: Id, parent_id: Id)

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.

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

Associate some static bytes with a uri.

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

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

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

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

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

Add a new bytes loader.

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

See load for more information.

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

Add a new image loader.

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

See load for more information.

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

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. Also this cancels any ongoing loading of the image.

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

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

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, ) -> TextureLoadResult

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.

pub fn has_pending_images(&self) -> bool

Returns true if any image is currently being loaded.

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 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(&mut Ui, 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, inside of a crate::Window. You can know by checking for ViewportClass::EmbeddedWindow.

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(&mut Ui, 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 as it requires both parent and child to repaint if any one of them needs repainting, which effectively 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, inside of a crate::Window. You can know by checking for ViewportClass::EmbeddedWindow.

See crate::viewport for more information about viewports.

fn show_embedded_viewport<T>( &self, new_viewport_id: ViewportId, builder: ViewportBuilder, viewport_ui_cb: impl FnOnce(&mut Ui) -> T, ) -> T

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 Deref for Ui

Allow using Ui like a Context.

type Target = Context

The resulting type after dereferencing.

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

Dereferences the value.

impl Drop for Ui

fn drop(&mut self)

Executes the destructor for this type.