Struct egui::Ui

pub struct Ui { /* fields omitted */ }

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

Implementations

impl Ui

pub fn new(
    ctx: CtxRef,
    layer_id: LayerId,
    id: Id,
    max_rect: Rect,
    clip_rect: Rect
) -> Self

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

pub fn __test() -> Self

Empty Ui for use in tests.

pub fn id(&self) -> Id

pub fn style(&self) -> &Style

Style options for this Ui and its children.

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

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

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

pub fn ctx(&self) -> &CtxRef

pub fn painter(&self) -> &Painter

Use this to paint stuff within this Ui.

pub fn layout(&self) -> &Layout

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 input(&self) -> &InputState

The Input of the Context associated with the Ui. Equivalent to .ctx().input().

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

The Memory of the Context associated with the Ui. Equivalent to .ctx().memory().

pub fn output(&self) -> MutexGuard<'_, Output>

The Output of the Context associated with the Ui. Equivalent to .ctx().output().

pub fn fonts(&self) -> &Fonts

The Fonts of the Context associated with the Ui. Equivalent to .ctx().fonts().

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

impl Ui

Sizes etc

pub fn min_rect(&self) -> Rect

Where and how large the Ui is already. All widgets that have been added ot 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 fn max_rect_finite(&self) -> Rect

This is like max_rect(), but will never be infinite. If the desired rect is infinite ("be as big as you want") this will be bounded by min_rect instead.

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 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 wider 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: RangeInclusive<f32>)

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

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

ui.set_width_range(width); is equivalent to ui.set_min_width(width); ui.set_max_width(width);.

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

pub fn available_size_before_wrap(&self) -> Vec2

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

pub fn available_size_before_wrap_finite(&self) -> Vec2

This is like available_size_before_wrap(), but will never be infinite. Use this for components that want to grow without bounds (but shouldn't). In most layouts the next widget will be put in the top left corner of this Rect.

pub fn available_rect_before_wrap(&self) -> Rect

pub fn available_rect_before_wrap_finite(&self) -> Rect

This is like available_rect_before_wrap(), but will never be infinite. Use this for components that want to grow without bounds (but shouldn't). In most layouts the next widget will be put in the top left corner of this Rect.

impl Ui

Id creation

pub fn make_persistent_id<IdSource>(&self, id_source: IdSource) -> Id where
    IdSource: Hash + Debug, 

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

pub fn make_position_id(&self) -> Id

👎 Deprecated:

This id now returned from ui.allocate_space

impl Ui

Interaction

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

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

pub fn ui_contains_mouse(&self) -> bool

Is the mouse above this Ui?

pub fn interact_hover(&self, rect: Rect) -> Response

👎 Deprecated:

Use: interact(rect, id, Sense::hover())

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

👎 Deprecated:

Use: rect_contains_mouse()

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

Advance the cursor (where the next widget is put) by this many points. The direction is dependent on the layout. This is useful for creating some extra space between 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 you minimum, and don't ask for more than you need. If you want to fill the space, ask about 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::color::WHITE));

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 you minimum, and don't ask for more than you need. If you want to fill the space, ask about 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());

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

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_painter(
    &mut self,
    desired_size: Vec2,
    sense: Sense
) -> (Response, Painter)

Convenience function to get a region to paint on

impl Ui

Adding widgets

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

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

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

pub fn colored_label(
    &mut self,
    color: impl Into<Srgba>,
    label: impl Into<Label>
) -> Response

Shortcut for add(Label::new(text).text_color(color))

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

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

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

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

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

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

pub fn hyperlink(&mut self, url: impl Into<String>) -> Response

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

pub fn text_edit(&mut self, text: &mut String) -> Response

👎 Deprecated:

Use text_edit_singleline or text_edit_multiline

pub fn text_edit_singleline(&mut self, text: &mut String) -> Response

Now newlines (\n) allowed. Pressing enter key will result in the TextEdit loosing focus (response.lost_kb_focus).

pub fn text_edit_multiline(&mut self, text: &mut String) -> Response

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

#[must_use = "You should check if the user clicked this with `if ui.button(...).clicked { ... } "]pub fn button(&mut self, text: impl Into<String>) -> Response

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

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

#[must_use = "You should check if the user clicked this with `if ui.small_button(...).clicked { ... } "]pub fn small_button(&mut self, text: impl Into<String>) -> 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(
    &mut self,
    checked: &mut bool,
    text: impl Into<String>
) -> Response

Show a checkbox.

pub fn radio(&mut self, selected: bool, text: impl Into<String>) -> Response

Show a radio button. Often you want to use ui.radio_value instead.

pub fn radio_value<Value: PartialEq>(
    &mut self,
    current_value: &mut Value,
    selected_value: Value,
    text: impl Into<String>
) -> Response

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

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

pub fn selectable_label(
    &mut self,
    checked: bool,
    text: impl Into<String>
) -> Response

Show a label which can be selected or not.

pub fn selectable_value<Value: PartialEq>(
    &mut self,
    current_value: &mut Value,
    selected_value: Value,
    text: impl Into<String>
) -> 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").

pub fn separator(&mut self) -> Response

Shortcut for add(Separator::new())

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(
    &mut self,
    texture_id: TextureId,
    desired_size: impl Into<Vec2>
) -> Response

Show an image here with the given size

impl Ui

Colors

pub fn color_edit_button_srgba(&mut self, srgba: &mut Srgba) -> 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_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: &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: &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 wrap<R>(
    &mut self,
    add_contents: impl FnOnce(&mut Ui) -> R
) -> (R, Response)

Create a child ui. You can use this to temporarily change the Style of a sub-region, for instance.

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

Redirect paint commands to another paint layer.

pub fn add_custom_contents(
    &mut self,
    desired_size: Vec2,
    add_contents: impl FnOnce(&mut Ui)
) -> Rect

👎 Deprecated:

Use ui.allocate_ui instead

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

A CollapsingHeader that starts out collapsed.

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

Create a child ui which is indented to the right

pub fn left_column(&mut self, width: f32) -> Self

👎 Deprecated

pub fn centered_column(&mut self, width: f32) -> Self

👎 Deprecated

pub fn right_column(&mut self, width: f32) -> Self

👎 Deprecated

pub fn column(&mut self, column_position: Align, width: f32) -> Self

👎 Deprecated

A column ui with a given width.

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

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

pub fn horizontal_for_text<R>(
    &mut self,
    text_style: TextStyle,
    add_contents: impl FnOnce(&mut Ui) -> R
) -> (R, Response)

Like horizontal, but will set up the spacing to match that of a normal label.

In particular, the space between widgets is the same width as the space character.

You can still add any widgets to the layout (not only Labels).

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

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

pub fn horizontal_wrapped_for_text<R>(
    &mut self,
    text_style: TextStyle,
    add_contents: impl FnOnce(&mut Ui) -> R
) -> (R, Response)

Like horizontal_wrapped, but will set up the spacing and line size to match that of a normal label.

In particular, the space between widgets is the same width as the space character and the line spacing is the same as that for text.

You can still add any widgets to the layout (not only Labels).

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

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

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

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

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

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

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

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

Temporarily split split an Ui into several columns.

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

impl Ui

Debug stuff

pub fn debug_paint_cursor(&self)

Shows where the next widget is going to be placed