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: Arc<Context>, layer: Layer, id: Id, max_rect: Rect) -> Self

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

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: Style)

pub fn ctx(&self) -> &Arc<Context>

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

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

The current size of this Ui. Bounding box of all contained child widgets. 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

This is the soft max size of the Ui. New widgets will try to fit within this rectangle. For instance, text will wrap to fit within it. If a widget doesn't fit within the max_rect then it will expand. max_rect() is always at least as large as min_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 available(&self) -> Rect

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 rectangle should be interpreted as "as little as possible". An infinite rectangle should be interpreted as "as much as you want". In most layouts the next widget will be put in the top left corner of this Rect.

pub fn available_finite(&self) -> Rect

This is like available(), 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_unique_child_id<IdSource>(&self, id_source: IdSource) -> Id where
    IdSource: Hash + Debug, 

Will warn if the returned id is not guaranteed unique. Use this to generate widget ids for widgets that have persistent state in Memory. If the id_source is not unique within this ui then an error will be printed at the current cursor position.

pub fn make_unique_child_id_full(
    &mut self,
    explicit_id_source: Option<Id>,
    default_id_source: Option<&str>
) -> Id

Ideally, all widgets should use this. TODO Widgets can set an explicit id source (user picked, e.g. some loop index), and a default id source (e.g. label). If they fail to be unique, a positional id will be used instead.

pub fn make_position_id(&self) -> Id

Make an Id that is unique to this position. Can be used for widgets that do NOT persist state in Memory but you still need to interact with (e.g. buttons, sliders).

pub fn make_child_id(&self, id_seed: impl Hash) -> Id

impl Ui

Interaction

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

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

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

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

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_space(&mut self, desired_size: Vec2) -> 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 aligned layouts, like in menus.

You may get LESS space than you asked for if the current layout won't fit what you asked for.

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 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 hyperlink(&mut self, url: impl Into<String>) -> Response

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

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

#[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

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

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

Show a checkbox.

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

Show a radio button.

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

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

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 image(&mut self, texture_id: TextureId, desired_size: 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 collapsing<R>(
    &mut self,
    heading: impl Into<String>,
    add_contents: impl FnOnce(&mut Ui) -> R
) -> Option<R>

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

Create a child ui at the current cursor. size is the desired size. Actual size may be much smaller if available_size() is not enough. Set size to Vec::infinity() to get as much space as possible. Just because you ask for a lot of space does not mean you have to use it! After add_contents is called the contents of min_size will decide how much space will be used in the parent ui.

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

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

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

Create a child ui which is indented to the right

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

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

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

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

A column ui with a given width.

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

Start a ui with horizontal layout. After you have called this, the 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 just different types of text.

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

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

pub fn inner_layout<R>(
    &mut self,
    layout: Layout,
    initial_size: Vec2,
    add_contents: impl FnOnce(&mut Self) -> R
) -> (R, Rect)

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

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].add(egui::widgets::label!("First column"));
    columns[1].add(egui::widgets::label!("Second column"));
});

impl Ui

Debug stuff

pub fn debug_paint_cursor(&self)

Shows where the next widget is going to be placed