SourceClass Ui ⧉

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 egui.Ui.add_sized, egui.Ui.place and egui.Ui.put.

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 egui.Ui.add_enabled_ui and egui.Ui.is_enabled.

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 egui.Ui.add_enabled and egui.Ui.is_enabled.

Example

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 egui.Ui.add, egui.Ui.place and egui.Ui.put.

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 egui.style.Spacing.item_spacing that is always added, but item_spacing won't be added again by add_space.

egui.Ui.min_rect will expand to contain the space.

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 egui.Ui.set_invisible and egui.Ui.is_visible.

Allocate a rect without interacting with it.

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

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

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.

Convenience function to get a region to paint on.

Note that egui uses screen coordinates for everything.

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.

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.

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.

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.

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

Like egui.Ui.next_auto_id, this is NOT stable over time.

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

See egui.Ui.available_size for more information.

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 egui.Ui.available_size.

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

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 egui.Ui.available_size.

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

See egui.Ui.available_size for more information.

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

Shortcut for add(Button.new(text))

See also Button.

Show a checkbox.

See also egui.Ui.toggle_value.

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.

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. egui.Popup, egui.Modal, egui.Area, egui.Window, egui.CollapsingHeader, etc.

What exactly happens when you close a container depends on the container implementation. egui.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 egui.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

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

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

See also: - Ui.close - Ui.should_close - Ui.will_parent_close

Show text as monospace with a gray background.

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

A TextEdit for code editing.

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

See also TextEdit.code_editor.

A CollapsingHeader that starts out collapsed.

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

Shows a button with the given color.

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

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.

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

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.

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.

Shows a button with the given color.

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

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

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.

Show colored text.

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

Temporarily split a Ui into several columns.

Get a reference to the parent Context.

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.

Shows where the next widget is going to be placed

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 egui.Ui.add_enabled_ui or egui.Ui.add_enabled.

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

Example

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.

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.

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π

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

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

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

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.

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.

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

See also egui.Ui.scope.

Show large text.

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

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

See also egui.Ui.with_layout for more options.

Like egui.Ui.horizontal, but allocates the full vertical height and then centers elements vertically.

Like egui.Ui.horizontal, but aligns content with top.

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 egui.Ui.with_layout for more options.

Link to a web page.

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

See also Hyperlink.

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

See also Hyperlink.

Renamed to egui.Ui.scope_id.

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.

Using egui.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 egui.Image, egui.ImageSource.

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

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

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

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.

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

Is this Ui in a tooltip?

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.

Show some text.

Shortcut for add(Label.new(text))

See also Label.

Example

Use this to paint stuff within this Ui.

Read the Layout.

Looks like a hyperlink.

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

See also Link.

Generate an Id for a widget that has persistent state in Memory.

This is the same as ui.scope_id().with(id_salt). Since it is based on the stable egui.Ui.scope_id, it is stable over time, as long as id_salt is unique within the current id scope.

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.

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.

See also: egui.Ui.close and Response.context_menu.

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.

See also: egui.Ui.close and Response.context_menu.

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.

See also: egui.Ui.close and Response.context_menu.

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.

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

Show monospace (fixed width) text.

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

Like egui.Ui.set_opacity, but multiplies the given value with the current opacity.

See also: egui.Ui.set_opacity and egui.Ui.opacity.

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

This is a very low-level function. Usually you are better off using egui.Ui.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.

The Id that will be assigned to the next widget added to this Ui, unless it has an explicit Id.

This is based on the egui.Ui.unique_id of this Ui and the number of widgets added so far. It is therefore NOT stable: it changes if widgets are added or removed before it. Do not use it for widgets that store state; use egui.Ui.make_persistent_id for that.

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

Read the current opacity of the underlying painter.

See also: egui.Ui.set_opacity and egui.Ui.multiply_opacity.

Use this to paint stuff within this Ui.

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.

Number of physical pixels for each logical UI point.

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

See also egui.Ui.add and egui.Ui.add_sized and egui.Ui.put.

Create a child Ui with an explicit Id.

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

See also egui.Ui.add, egui.Ui.add_sized, and egui.Ui.place.

Show a RadioButton. Often you want to use egui.Ui.radio_value instead.

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

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.

Reset to the default style set in Context.

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

Create a scoped child ui.

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

See also egui.Ui.scope_builder for more options.

Create a scoped child ui, inheriting properties from the parent as specified by the UiBuilder. In contrast to egui.Ui.new_child, this allocates the space used by the child.

See also egui.Ui.scope and egui.Ui.scope_dyn.

Adjust the scroll position of any parent egui.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.

Same as egui.Ui.scroll_to_cursor, but allows you to specify the style.ScrollAnimation.

Adjust the scroll position of any parent egui.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..

Same as egui.Ui.scroll_to_rect, but allows you to specify the style.ScrollAnimation.

Scroll this many points in the given direction, in the parent egui.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 egui.ScrollArea, the deltas will be summed.

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

Same as egui.Ui.scroll_with_delta, but allows you to specify the style.ScrollAnimation.

Show a label which can be selected or not.

See also Button.selectable and egui.Ui.toggle_value.

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

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

See also Button.selectable and egui.Ui.toggle_value.

Shortcut for add(Separator.default())

See also Separator.

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 egui.Ui.shrink_clip_rect instead.

Set both the minimum and maximum height.

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

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 egui.Ui.add_visible.

Example

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

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

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

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

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

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

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

See also: egui.Ui.opacity and egui.Ui.multiply_opacity.

Set row height in horizontal wrapping layout.

Changes apply to this Ui and its subsequent children.

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

Set both the minimum and maximum width.

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

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

Constrain the rectangle in which we can paint.

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

See also: egui.Ui.clip_rect and egui.Ui.set_clip_rect.

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

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.

Pretend like count widgets have been allocated, advancing egui.Ui.next_auto_id.

Show small text.

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

A button as small as normal body text.

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

Shortcut for add(Button.new(atoms).small())

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

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

Shortcut for add(Spinner.new())

See also Spinner.

Get a reference to this Ui's UiStack.

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

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

Style options for this Ui and its children.

Note that this may be a different Style than that of Context.global_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.

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.

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.

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.

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

See also TextEdit.

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

See also TextEdit.

The height of text of this text style.

Returns a value rounded to emath.GUI_ROUNDING.

How to vertically align text

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

Click to toggle to bool.

See also egui.Ui.checkbox.

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 egui.Ui.response instead.

A globally unique, but unstable, Id of this Ui.

This is NOT stable: it is based on where in the widget hierarchy this Ui is, so it changes if widgets are added or removed before it. It should therefore only be used for transient interactions (clicks etc), never for storing state over time.

For a stable Id to base widget state on, see egui.Ui.scope_id.

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

See also egui.Ui.with_layout for more options.

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

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

The current visuals settings of this Ui. Short for ui.style().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.

Show text that is weaker (fainter color).

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

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

See also - Ui.should_close - Ui.close - Ui.close_kind

The new layout will take up all available space.

If you don't want to use up all available space, use egui.Ui.allocate_ui_with_layout.

See also the helpers egui.Ui.horizontal, egui.Ui.vertical, etc.

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.

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.