Struct arc_util::ui::Ui

pub struct Ui<'ui> { /* private fields */ }

A temporary reference for building the user interface for one frame

Implementations

impl<'ui> Ui<'ui>

Clipboard

pub fn clipboard_text(&self) -> Option<String>

Returns the current clipboard contents as text, or None if the clipboard is empty or cannot be accessed

pub fn set_clipboard_text(&self, text: impl AsRef<str>)

Sets the clipboard contents.

Does nothing if the clipboard cannot be accessed.

impl<'ui> Ui<'ui>

Columns

pub fn columns(&self, count: i32, id: impl AsRef<str>, border: bool)

pub fn next_column(&self)

Switches to the next column.

If the current row is finished, switches to first column of the next row

pub fn current_column_index(&self) -> i32

Returns the index of the current column

pub fn current_column_width(&self) -> f32

Returns the width of the current column (in pixels)

pub fn column_width(&self, column_index: i32) -> f32

Returns the width of the given column (in pixels)

pub fn set_current_column_width(&self, width: f32)

Sets the width of the current column (in pixels)

pub fn set_column_width(&self, column_index: i32, width: f32)

Sets the width of the given column (in pixels)

pub fn current_column_offset(&self) -> f32

Returns the offset of the current column (in pixels from the left side of the content region)

pub fn column_offset(&self, column_index: i32) -> f32

Returns the offset of the given column (in pixels from the left side of the content region)

pub fn set_current_column_offset(&self, offset_x: f32)

Sets the offset of the current column (in pixels from the left side of the content region)

pub fn set_column_offset(&self, column_index: i32, offset_x: f32)

Sets the offset of the given column (in pixels from the left side of the content region)

pub fn column_count(&self) -> i32

Returns the current amount of columns

impl<'ui> Ui<'ui>

Fonts

pub fn current_font(&self) -> &Font

Returns the current font

pub fn current_font_size(&self) -> f32

Returns the current font size (= height in pixels) with font scale applied

pub fn font_tex_uv_white_pixel(&self) -> [f32; 2]

Returns the UV coordinate for a white pixel.

Useful for drawing custom shapes with the draw list API.

pub fn set_window_font_scale(&self, scale: f32)

Sets the font scale of the current window

impl<'ui> Ui<'ui>

Input: Keyboard

pub fn is_key_down(&self, key: Key) -> bool

Returns true if the key is being held.

Equivalent to indexing the Io struct keys_down field: ui.io().keys_down[key_index]

pub fn is_key_index_down(&self, key_index: i32) -> bool

Same as is_key_down but takes a key index. The meaning of index is defined by your backend implementation.

pub fn is_key_pressed(&self, key: Key) -> bool

Returns true if the key was pressed (went from !down to down).

Affected by key repeat settings (io.key_repeat_delay, io.key_repeat_rate)

pub fn is_key_index_pressed(&self, key_index: i32) -> bool

Same as is_key_pressed but takes a key index.

The meaning of index is defined by your backend implementation.

pub fn is_key_pressed_no_repeat(&self, key: Key) -> bool

Returns true if the key was pressed (went from !down to down).

Is not affected by key repeat settings (io.key_repeat_delay, io.key_repeat_rate)

pub fn is_key_index_pressed_no_repeat(&self, key_index: i32) -> bool

Same as is_key_pressed_no_repeat but takes a key index.

The meaning of index is defined by your backend implementation.

pub fn is_key_released(&self, key: Key) -> bool

Returns true if the key was released (went from down to !down)

pub fn is_key_index_released(&self, key_index: i32) -> bool

Same as is_key_released but takes a key index.

The meaning of index is defined by your backend implementation.

pub fn key_pressed_amount(&self, key: Key, repeat_delay: f32, rate: f32) -> u32

Returns a count of key presses using the given repeat rate/delay settings.

Usually returns 0 or 1, but might be >1 if rate is small enough that io.delta_time > rate.

pub fn key_index_pressed_amount( &self, key_index: i32, repeat_delay: f32, rate: f32 ) -> u32

pub fn set_keyboard_focus_here(&self)

Focuses keyboard on the next widget.

This is the equivalent to set_keyboard_focus_here_with_offset with target_widget set to FocusedWidget::Next.

pub fn set_keyboard_focus_here_with_offset(&self, target_widget: FocusedWidget)

Focuses keyboard on a widget relative to current position.

impl<'ui> Ui<'ui>

Input: Mouse

pub fn is_mouse_down(&self, button: MouseButton) -> bool

Returns true if the given mouse button is held down.

Equivalent to indexing the Io struct with the button, e.g. ui.io()[button].

pub fn is_any_mouse_down(&self) -> bool

Returns true if any mouse button is held down

pub fn is_mouse_clicked(&self, button: MouseButton) -> bool

Returns true if the given mouse button was clicked (went from !down to down)

pub fn is_mouse_double_clicked(&self, button: MouseButton) -> bool

Returns true if the given mouse button was double-clicked

pub fn is_mouse_released(&self, button: MouseButton) -> bool

Returns true if the given mouse button was released (went from down to !down)

pub fn is_mouse_dragging(&self, button: MouseButton) -> bool

Returns true if the mouse is currently dragging with the given mouse button held down

pub fn is_mouse_dragging_with_threshold( &self, button: MouseButton, threshold: f32 ) -> bool

Returns true if the mouse is currently dragging with the given mouse button held down.

If the given threshold is invalid or negative, the global distance threshold is used (io.mouse_drag_threshold).

pub fn is_mouse_hovering_rect(&self, r_min: [f32; 2], r_max: [f32; 2]) -> bool

Returns true if the mouse is hovering over the given bounding rect.

Clipped by current clipping settings, but disregards other factors like focus, window ordering, modal popup blocking.

pub fn mouse_pos_on_opening_current_popup(&self) -> [f32; 2]

Returns the mouse position backed up at the time of opening a popup

pub fn mouse_drag_delta(&self) -> [f32; 2]

Returns the delta from the initial position when the left mouse button clicked.

This is locked and returns [0.0, 0.0] until the mouse has moved past the global distance threshold (io.mouse_drag_threshold).

This is the same as mouse_drag_delta_with_button with button set to MouseButton::Left.

pub fn mouse_drag_delta_with_button(&self, button: MouseButton) -> [f32; 2]

Returns the delta from the initial position when the given button was clicked.

This is locked and returns [0.0, 0.0] until the mouse has moved past the global distance threshold (io.mouse_drag_threshold).

This is the same as mouse_drag_delta_with_threshold with threshold set to -1.0, which uses the global threshold io.mouse_drag_threshold.

pub fn mouse_drag_delta_with_threshold( &self, button: MouseButton, threshold: f32 ) -> [f32; 2]

Returns the delta from the initial clicking position.

This is locked and returns [0.0, 0.0] until the mouse has moved past the given threshold. If the given threshold is invalid or negative, the global distance threshold is used (io.mouse_drag_threshold).

pub fn reset_mouse_drag_delta(&self, button: MouseButton)

Resets the current delta from initial clicking position.

pub fn mouse_cursor(&self) -> Option<MouseCursor>

Returns the currently desired mouse cursor type.

Returns None if no cursor should be displayed

pub fn set_mouse_cursor(&self, cursor_type: Option<MouseCursor>)

Sets the desired mouse cursor type.

Passing None hides the mouse cursor.

pub fn is_current_mouse_pos_valid(&self) -> bool

pub fn is_mouse_pos_valid(&self, mouse_pos: [f32; 2]) -> bool

impl<'ui> Ui<'ui>

Cursor / Layout

pub fn separator(&self)

Renders a separator (generally horizontal).

This becomes a vertical separator inside a menu bar or in horizontal layout mode.

pub fn same_line(&self)

Call between widgets or groups to layout them horizontally.

X position is given in window coordinates.

This is equivalent to calling same_line_with_pos with the pos set to 0.0, which uses Style::item_spacing.

pub fn same_line_with_pos(&self, pos_x: f32)

Call between widgets or groups to layout them horizontally.

X position is given in window coordinates.

This is equivalent to calling same_line_with_spacing with the spacing set to -1.0, which means no extra spacing.

pub fn same_line_with_spacing(&self, pos_x: f32, spacing_w: f32)

Call between widgets or groups to layout them horizontally.

X position is given in window coordinates.

pub fn new_line(&self)

Undo a same_line call or force a new line when in horizontal layout mode

pub fn spacing(&self)

Adds vertical spacing

pub fn dummy(&self, size: [f32; 2])

Fills a space of size in pixels with nothing on the current window.

Can be used to move the cursor on the window.

pub fn indent(&self)

Moves content position to the right by Style::indent_spacing

This is equivalent to indent_by with width set to Style::ident_spacing.

pub fn indent_by(&self, width: f32)

Moves content position to the right by width

pub fn unindent(&self)

Moves content position to the left by Style::indent_spacing

This is equivalent to unindent_by with width set to Style::ident_spacing.

pub fn unindent_by(&self, width: f32)

Moves content position to the left by width

pub fn begin_group(&self) -> GroupToken<'_>

Groups items together as a single item.

May be useful to handle the same mouse event on a group of items, for example.

Returns a GroupToken that must be ended by calling .end()

pub fn group<R, F>(&self, f: F) -> R

where F: FnOnce() -> R,

Creates a layout group and runs a closure to construct the contents.

May be useful to handle the same mouse event on a group of items, for example.

pub fn cursor_pos(&self) -> [f32; 2]

Returns the cursor position (in window coordinates)

pub fn set_cursor_pos(&self, pos: [f32; 2])

Sets the cursor position (in window coordinates).

This sets the point on which the next widget will be drawn.

pub fn cursor_start_pos(&self) -> [f32; 2]

Returns the initial cursor position (in window coordinates)

pub fn cursor_screen_pos(&self) -> [f32; 2]

Returns the cursor position (in absolute screen coordinates).

This is especially useful for drawing, as the drawing API uses screen coordinates.

pub fn set_cursor_screen_pos(&self, pos: [f32; 2])

Sets the cursor position (in absolute screen coordinates)

pub fn align_text_to_frame_padding(&self)

Vertically aligns text baseline so that it will align properly to regularly frame items.

Call this if you have text on a line before a framed item.

pub fn text_line_height(&self) -> f32

pub fn text_line_height_with_spacing(&self) -> f32

pub fn frame_height(&self) -> f32

pub fn frame_height_with_spacing(&self) -> f32

impl<'ui> Ui<'ui>

pub fn open_popup(&self, str_id: impl AsRef<str>)

Instructs ImGui to open a popup, which must be began with either begin_popup or popup. You also use this function to begin PopupModal.

The confusing aspect to popups is that ImGui holds “control” over the popup fundamentally, so that ImGui can also force close a popup when a user clicks outside a popup. If you do not want users to be able to close a popup without selected an option, use PopupModal.

pub fn begin_popup(&self, str_id: impl AsRef<str>) -> Option<PopupToken<'_>>

Construct a popup that can have any kind of content.

This should be called per frame, whereas open_popup should be called once when you want to actual create the popup.

pub fn popup<F>(&self, str_id: impl AsRef<str>, f: F)

where F: FnOnce(),

Construct a popup that can have any kind of content.

This should be called per frame, whereas open_popup should be called once when you want to actual create the popup.

pub fn popup_modal<'p, Label>(&self, str_id: Label) -> PopupModal<'p, Label>

where Label: AsRef<str>,

Creates a PopupModal directly.

pub fn close_current_popup(&self)

Close a popup. Should be called within the closure given as argument to Ui::popup or Ui::popup_modal.

impl<'ui> Ui<'ui>

Parameter stacks (shared)

pub fn push_font(&self, id: FontId) -> FontStackToken<'_>

Switches to the given font by pushing it to the font stack.

Returns a FontStackToken that must be popped by calling .pop()

Panics

Panics if the font atlas does not contain the given font

Examples

// At initialization time
let my_custom_font = ctx.fonts().add_font(&font_data_sources);
// During UI construction
let font = ui.push_font(my_custom_font);
ui.text("I use the custom font!");
font.pop();

pub fn push_style_color( &self, style_color: StyleColor, color: [f32; 4] ) -> ColorStackToken<'_>

Changes a style color by pushing a change to the color stack.

Returns a ColorStackToken that must be popped by calling .pop()

Examples

const RED: [f32; 4] = [1.0, 0.0, 0.0, 1.0];
let color = ui.push_style_color(StyleColor::Text, RED);
ui.text("I'm red!");
color.pop();

pub fn push_style_colors<'a, I>(&self, style_colors: I) -> MultiColorStackToken

where I: IntoIterator<Item = &'a (StyleColor, [f32; 4])>,

👎Deprecated: deprecated in 0.7.0. Use push_style_color multiple times for similar effect.

Changes style colors by pushing several changes to the color stack.

Returns a ColorStackToken that must be popped by calling .pop()

Examples

const RED: [f32; 4] = [1.0, 0.0, 0.0, 1.0];
const GREEN: [f32; 4] = [0.0, 1.0, 0.0, 1.0];
let colors = ui.push_style_colors(&[
    (StyleColor::Text, RED),
    (StyleColor::TextDisabled, GREEN),
]);
ui.text("I'm red!");
ui.text_disabled("I'm green!");
colors.pop(&ui);

pub fn push_style_var(&self, style_var: StyleVar) -> StyleStackToken<'_>

Changes a style variable by pushing a change to the style stack.

Returns a StyleStackToken that can be popped by calling .end() or by allowing to drop.

Examples

let style = ui.push_style_var(StyleVar::Alpha(0.2));
ui.text("I'm transparent!");
style.pop();

pub fn push_style_vars<'a, I>(&self, style_vars: I) -> MultiStyleStackToken

where I: IntoIterator<Item = &'a StyleVar>,

👎Deprecated: deprecated in 0.7.0. Use push_style_var multiple times for similar effect.

Changes style variables by pushing several changes to the style stack.

Returns a StyleStackToken that must be popped by calling .pop()

Examples

let styles = ui.push_style_vars(&[
    StyleVar::Alpha(0.2),
    StyleVar::ItemSpacing([50.0, 50.0])
]);
ui.text("We're transparent...");
ui.text("...with large spacing as well");
styles.pop(&ui);

impl<'ui> Ui<'ui>

Parameter stacks (current window)

pub fn push_item_width(&self, item_width: f32) -> ItemWidthStackToken

Changes the item width by pushing a change to the item width stack.

Returns an ItemWidthStackToken that may be popped by calling .pop()

• > 0.0: width is item_width pixels
• = 0.0: default to ~2/3 of window width
• < 0.0: item_width pixels relative to the right of window (-1.0 always aligns width to the right side)

pub fn set_next_item_width(&self, item_width: f32)

Sets the width of the next item.

• > 0.0: width is item_width pixels
• = 0.0: default to ~2/3 of window width
• < 0.0: item_width pixels relative to the right of window (-1.0 always aligns width to the right side)

pub fn calc_item_width(&self) -> f32

Returns the width of the item given the pushed settings and the current cursor position.

This is NOT necessarily the width of last item.

pub fn push_text_wrap_pos(&self) -> TextWrapPosStackToken

Changes the text wrapping position to the end of window (or column), which is generally the default.

This is the same as calling push_text_wrap_pos_with_pos with wrap_pos_x set to 0.0.

Returns a TextWrapPosStackToken that may be popped by calling .pop()

pub fn push_text_wrap_pos_with_pos( &self, wrap_pos_x: f32 ) -> TextWrapPosStackToken

Changes the text wrapping position by pushing a change to the text wrapping position stack.

Returns a TextWrapPosStackToken that may be popped by calling .pop()

• > 0.0: wrap at wrap_pos_x position in window local space
• = 0.0: wrap to end of window (or column)
• < 0.0: no wrapping

pub fn push_item_flag(&self, item_flag: ItemFlag) -> ItemFlagsStackToken

Changes an item flag by pushing a change to the item flag stack.

Returns a ItemFlagsStackToken that may be popped by calling .pop()

impl<'ui> Ui<'ui>

ID stack

pub fn push_id<'a, I>(&self, id: I) -> IdStackToken<'ui>

where I: Into<Id<'a>>,

Pushes an identifier to the ID stack.

Returns an IdStackToken that can be popped by calling .end() or by dropping manually.

impl<'ui> Ui<'ui>

pub fn begin_table( &self, str_id: impl AsRef<str>, column_count: usize ) -> Option<TableToken<'ui>>

Begins a table with no flags and with standard sizing contraints.

This does no work on styling the headers (the top row) – see either begin_table_header or the more complex table_setup_column.

Nb: we take column as a usize, but it will be converted with as i32 to an i32. If this makes a difference to you, you are probably trying to make too many columns.

pub fn begin_table_with_flags( &self, str_id: impl AsRef<str>, column_count: usize, flags: TableFlags ) -> Option<TableToken<'ui>>

Begins a table with flags and standard sizing contraints.

This does no work on styling the headers (the top row) – see either begin_table_header or the more complex table_setup_column.

Nb: we take column as a usize, but it will be converted with as i32 to an i32. If this makes a difference to you, you are probably trying to make too many columns.

pub fn begin_table_with_sizing( &self, str_id: impl AsRef<str>, column: usize, flags: TableFlags, outer_size: [f32; 2], inner_width: f32 ) -> Option<TableToken<'ui>>

Begins a table with all flags and sizing contraints. This is the base method, and gives users the most flexibility.

This does no work on styling the headers (the top row) – see either begin_table_header or the more complex table_setup_column.

Nb: we take column as a usize, but it will be converted with as i32 to an i32. If this makes a difference to you, you are probably trying to make too many columns.

pub fn begin_table_header<'a, Name, const N: usize>( &self, str_id: impl AsRef<str>, column_data: [TableColumnSetup<'a, Name>; N] ) -> Option<TableToken<'ui>>

where Name: AsRef<str>,

Begins a table with no flags and with standard sizing contraints.

Takes an array of table header information, the length of which determines how many columns will be created.

pub fn begin_table_header_with_flags<'a, Name, const N: usize>( &self, str_id: impl AsRef<str>, column_data: [TableColumnSetup<'a, Name>; N], flags: TableFlags ) -> Option<TableToken<'ui>>

where Name: AsRef<str>,

Begins a table with flags and standard sizing contraints.

Takes an array of table header information, the length of which determines how many columns will be created.

pub fn begin_table_header_with_sizing<'a, Name, const N: usize>( &self, str_id: impl AsRef<str>, column_data: [TableColumnSetup<'a, Name>; N], flags: TableFlags, outer_size: [f32; 2], inner_width: f32 ) -> Option<TableToken<'ui>>

where Name: AsRef<str>,

Begins a table with all flags and sizing contraints. This is the base method, and gives users the most flexibility. Takes an array of table header information, the length of which determines how many columns will be created.

pub fn table_next_row(&self)

Moves a table to the next row (ie, down) with no flags, and with the next row having a standard computed height.

If your table was made with begin_table, this must be called before rendering any cells (along with table_next_column). If your table was made with begin_table_header, this does not need to be called, though table_next_column still should be.

pub fn table_next_row_with_flags(&self, flags: TableRowFlags)

Moves a table to the next row (ie, down), with the given flags, and with the next row having a standard computed height.

Setting a flag here will make the next row a “header” now, which may require setup of column data.

See table_next_row for information on how moving rows work. To set the row with a given height, see table_next_row_with_height.

pub fn table_next_row_with_height( &self, flags: TableRowFlags, min_row_height: f32 )

Moves a table to the next row (ie, down), with the given flags, and with the given minimum height.

See table_next_row for information on how moving rows work.

pub fn table_next_column(&self) -> bool

Moves onto the next column. If at column_count, this will move to the next row. In this way, you can use this function as an iterator over each cell in the table.

Example

if let Some(_t) = ui.begin_table("Basic-Table", 2) {
    // we have to call next_row because we didn't make headers..
    ui.table_next_row();

    // you always have to call this to start...
    // take advantage of this in loops!
    ui.table_next_column();
    ui.text("x: 0, y: 0");

    ui.table_next_column();
    ui.text("x: 1, y: 0");
     
    // notice that we go down a row here too.
    ui.table_next_column();
    ui.text("x: 0, y: 1");

    ui.table_next_column();
    ui.text("x: 1, y: 1");
}

This functions returns true if the given column is visible. It is not marked as must use, as you can still render commands into the not-visible column, though you can choose to not as an optimization.

pub fn table_set_column_index(&self, column_index: usize) -> bool

Moves onto the given column.

Example

if let Some(_t) = ui.begin_table("Basic-Table", 2) {
    // we have to call next_row because we didn't make headers..
    ui.table_next_row();

    for i in 0..2 {
        ui.table_set_column_index(i);
        ui.text(format!("x: {}", i));
    }
     
    // oops I just remembered, i need to add something on idx 0!
    ui.table_set_column_index(0);
    // if i uncomment this line, we'll write on top of our previous "x: 0"
    // line:
    // ui.text("hello from the future on top of the past");
    // so we do a .newline();
    ui.new_line();
    ui.text("hello from the future");

    // imgui will understand this and row spacing will be adjusted automatically.
}

This functions returns true if the given column is visible. It is not marked as must use, as you can still render commands into the not-visible column, though you can choose to not as an optimization.

Panics

If column_index >= ui.table_columm_count, this function will panic. In debug releases, we will panic on the Rust side, for a nicer error message, though in release, we will panic in C++, which will result in an ugly stack overflow.

pub fn table_setup_column(&self, str_id: impl AsRef<str>)

Specify label per column, with no flags and default sizing. You can avoid calling this method entirely by using begin_table_header.

Example

if let Some(_t) = ui.begin_table("My Table", 2) {
    ui.table_setup_column("One");
    ui.table_setup_column("Two");
    ui.table_setup_column("Three");
    ui.table_headers_row();

    // call next_column/set_column_index and proceed like normal.
    // the above code is the equivalent of just using `begin_table_header`
    // but does allow for some columns to have headers and others to not
}

Along with table_headers_row, this method is used to create a header row and automatically submit a table header for each column. Headers are required to perform: reordering, sorting, and opening the context menu (though, the context menu can also be made available in columns body using TableFlags::CONTEXT_MENU_IN_BODY.

pub fn table_setup_column_with<N>(&self, data: TableColumnSetup<'_, N>)

where N: AsRef<str>,

Specify label per column, with data given in TableColumnSetup. You can avoid calling this method entirely by using begin_table_header.

See table_setup_column for an example of how to setup columns yourself.

Along with table_headers_row, this method is used to create a header row and automatically submit a table header for each column. Headers are required to perform: reordering, sorting, and opening the context menu (though, the context menu can also be made available in columns body using TableFlags::CONTEXT_MENU_IN_BODY.

pub fn table_setup_scroll_freeze( &self, locked_columns: usize, locked_rows: usize )

Locks columns/rows so they stay visible when scrolled. Generally, you will be calling this so that the header column is always visible (though go wild if you want). You can avoid calling this entirely by passing true to begin_table_header.

Example

const COLUMN_COUNT: usize = 3;
if let Some(_t) = ui.begin_table("scroll-freeze-example", COLUMN_COUNT) {
    // locks the header row. Notice how we need to call it BEFORE `table_headers_row`.
    ui.table_setup_scroll_freeze(1, COLUMN_COUNT);
    ui.table_setup_column("One");
    ui.table_setup_column("Two");
    ui.table_setup_column("Three");
    ui.table_headers_row();
}

Nb: we take locked_columns and locked_rows as a usize, but it will be converted with as i32 to an i32. If this makes a difference to you, you are probably trying to make too many columns.

pub fn table_headers_row(&self)

Along with table_setup_column, this method is used to create a header row and automatically submit a table header for each column.

For an example of using this method, see table_setup_column.

Headers are required to perform: reordering, sorting, and opening the context menu (though, the context menu can also be made available in columns body using TableFlags::CONTEXT_MENU_IN_BODY.

You may manually submit headers using table_next_column + table_header calls, but this is only useful in some advanced use cases (e.g. adding custom widgets in header row). See table_header for more information.

pub fn table_header(&self, label: impl AsRef<str>)

Use this function to manually declare a column cell to be a header.

You generally should avoid using this outside of specific cases, such as custom widgets. Instead, use table_headers_row and table_setup_column.

pub fn table_column_count(&self) -> usize

Gets the numbers of columns in the current table.

pub fn table_column_index(&self) -> usize

Gets the current column index in the current table.

pub fn table_row_index(&self) -> usize

Gets the current row index in the current table.

pub fn table_column_name(&mut self) -> &str

Gets the name of the current column. If there is no currently bound name for this column, we will return an empty string.

Use table_column_name_with_column for arbitrary indices.

pub fn table_column_name_with_column(&mut self, column: usize) -> &str

Gets the name of a given column. If there is no currently bound name for this column, we will return an empty string.

Use table_column_name for the current column.

pub fn table_column_flags(&self) -> TableColumnFlags

Gets the flags on the current column in the current table.

pub fn table_column_flags_with_column( &self, column_n: usize ) -> TableColumnFlags

Gets the flags on the given column in the current table. To get the current column’s flags without having to call table_column_index, use table_column_flags.

pub fn table_set_bg_color( &self, target: TableBgTarget, color: impl Into<ImColor32> )

Sets the given background color for this column. See TableBgTarget for more information on how colors work for tables.

Use table_set_bg_color_with_column to set for arbitrary indices.

pub fn table_set_bg_color_with_column( &self, target: TableBgTarget, color: impl Into<ImColor32>, column_index: usize )

Sets the given background color for any column. See TableBgTarget for more information on how colors work for tables.

Use table_set_bg_color for the current column.

pub fn table_sort_specs_mut(&self) -> Option<TableSortSpecsMut<'_>>

Gets the sorting data for a table. This will be None when not sorting.

See the examples folder for how to use the sorting API.

impl<'ui> Ui<'ui>

Item/widget utilities

pub fn is_item_hovered(&self) -> bool

Returns true if the last item is hovered

pub fn is_item_hovered_with_flags(&self, flags: ItemHoveredFlags) -> bool

Returns true if the last item is hovered based on the given flags

pub fn is_item_active(&self) -> bool

Returns true if the last item is active

pub fn is_item_focused(&self) -> bool

Returns true if the last item is focused for keyboard/gamepad navigation

pub fn is_item_clicked(&self) -> bool

Returns true if the last item is being clicked by MouseButton::Left.

This is the same as is_item_clicked_with_button with button set to MouseButton::Left.

pub fn is_item_clicked_with_button(&self, button: MouseButton) -> bool

Returns true if the last item is being clicked

pub fn is_item_visible(&self) -> bool

Returns true if the last item is visible

pub fn is_item_edited(&self) -> bool

Returns true if the last item modified its underlying value this frame or was pressed

pub fn is_item_activated(&self) -> bool

Returns true if the last item was just made active

pub fn is_item_deactivated(&self) -> bool

Returns true if the last item was just made inactive

pub fn is_item_deactivated_after_edit(&self) -> bool

Returns true if the last item was just made inactive and made a value change when it was active

pub fn is_item_toggled_open(&self) -> bool

Returns true if the last item open state was toggled

pub fn is_any_item_hovered(&self) -> bool

Returns true if any item is hovered

pub fn is_any_item_active(&self) -> bool

Returns true if any item is active

pub fn is_any_item_focused(&self) -> bool

Returns true if any item is focused

pub fn item_rect_min(&self) -> [f32; 2]

Returns the upper-left bounding rectangle of the last item (in screen coordinates)

pub fn item_rect_max(&self) -> [f32; 2]

Returns the lower-right bounding rectangle of the last item (in screen coordinates)

pub fn item_rect_size(&self) -> [f32; 2]

Returns the size of the last item

pub fn set_item_allow_overlap(&self)

Allows the last item to be overlapped by a subsequent item.

Both may be activated during the same frame before the later one takes priority.

pub fn set_item_default_focus(&self)

Makes the last item the default focused item of the window

impl<'ui> Ui<'ui>

Miscellaneous utilities

pub fn is_cursor_rect_visible(&self, size: [f32; 2]) -> bool

Returns true if the rectangle (of given size, starting from cursor position) is visible

pub fn is_rect_visible(&self, rect_min: [f32; 2], rect_max: [f32; 2]) -> bool

Returns true if the rectangle (in screen coordinates) is visible

pub fn time(&self) -> f64

Returns the global imgui-rs time.

Incremented by Io::delta_time every frame.

pub fn frame_count(&self) -> i32

Returns the global imgui-rs frame count.

Incremented by 1 every frame.

pub fn style_color(&self, style_color: StyleColor) -> [f32; 4]

Returns a single style color from the user interface style.

Use this function if you need to access the colors, but don’t want to clone the entire style object.

impl<'ui> Ui<'ui>

Widgets: Color Editor/Picker

pub fn set_color_edit_options(&self, flags: ColorEditFlags)

Initializes current color editor/picker options (generally on application startup) if you want to select a default format, picker type, etc. Users will be able to change many settings, unless you use .options(false) in your widget builders.

impl<'ui> Ui<'ui>

Convenience functions

pub fn begin_combo( &self, label: impl AsRef<str>, preview_value: impl AsRef<str> ) -> Option<ComboBoxToken<'ui>>

Creates a combo box which can be appended to with Selectable::new.

If you do not want to provide a preview, use begin_combo_no_preview. If you want to pass flags, use begin_combo_with_flags.

Returns None if the combo box is not open and no content should be rendered.

pub fn begin_combo_with_flags( &self, label: impl AsRef<str>, preview_value: impl AsRef<str>, flags: ComboBoxFlags ) -> Option<ComboBoxToken<'ui>>

Creates a combo box which can be appended to with Selectable::new.

If you do not want to provide a preview, use begin_combo_no_preview. Returns Some(ComboBoxToken) if the combo box is open. After content has been rendered, the token must be ended by calling .end().

Returns None if the combo box is not open and no content should be rendered.

pub fn begin_combo_no_preview( &self, label: impl AsRef<str> ) -> Option<ComboBoxToken<'ui>>

Creates a combo box which can be appended to with Selectable::new.

If you want to provide a preview, use begin_combo. If you want to pass flags, use begin_combo_no_preview_with_flags.

Returns Some(ComboBoxToken) if the combo box is open. After content has been rendered, the token must be ended by calling .end().

Returns None if the combo box is not open and no content should be rendered.

pub fn begin_combo_no_preview_with_flags( &self, label: impl AsRef<str>, flags: ComboBoxFlags ) -> Option<ComboBoxToken<'ui>>

Creates a combo box which can be appended to with Selectable::new.

If you do not want to provide a preview, use begin_combo_no_preview. Returns Some(ComboBoxToken) if the combo box is open. After content has been rendered, the token must be ended by calling .end().

Returns None if the combo box is not open and no content should be rendered.

pub fn combo<V, L>( &self, label: impl AsRef<str>, current_item: &mut usize, items: &[V], label_fn: L ) -> bool

where L: for<'b> Fn(&'b V) -> Cow<'b, str>,

Builds a simple combo box for choosing from a slice of values

pub fn combo_simple_string( &self, label: impl AsRef<str>, current_item: &mut usize, items: &[impl AsRef<str>] ) -> bool

Builds a simple combo box for choosing from a slice of values

impl<'ui> Ui<'ui>

Widgets: Menus

pub fn begin_main_menu_bar(&self) -> Option<MainMenuBarToken<'ui>>

Creates and starts appending to a full-screen menu bar.

Returns Some(MainMenuBarToken) if the menu bar is visible. After content has been rendered, the token must be ended by calling .end().

Returns None if the menu bar is not visible and no content should be rendered.

pub fn main_menu_bar<F>(&self, f: F)

where F: FnOnce(),

Creates a full-screen main menu bar and runs a closure to construct the contents.

Note: the closure is not called if the menu bar is not visible.

pub fn begin_menu_bar(&self) -> Option<MenuBarToken<'_>>

Creates and starts appending to the menu bar of the current window.

Returns Some(MenuBarToken) if the menu bar is visible. After content has been rendered, the token must be ended by calling .end().

Returns None if the menu bar is not visible and no content should be rendered.

pub fn menu_bar<F>(&self, f: F)

where F: FnOnce(),

Creates a menu bar in the current window and runs a closure to construct the contents.

Note: the closure is not called if the menu bar is not visible.

pub fn begin_menu(&self, label: impl AsRef<str>) -> Option<MenuToken<'_>>

Creates and starts appending to a sub-menu entry.

Returns Some(MenuToken) if the menu is visible. After content has been rendered, the token must be ended by calling .end().

Returns None if the menu is not visible and no content should be rendered.

This is the equivalent of begin_menu_with_enabled with enabled set to true.

pub fn begin_menu_with_enabled( &self, label: impl AsRef<str>, enabled: bool ) -> Option<MenuToken<'_>>

Creates and starts appending to a sub-menu entry.

Returns Some(MenuToken) if the menu is visible. After content has been rendered, the token must be ended by calling .end().

Returns None if the menu is not visible and no content should be rendered.

pub fn menu<F>(&self, label: impl AsRef<str>, f: F)

where F: FnOnce(),

Creates a menu and runs a closure to construct the contents.

Note: the closure is not called if the menu is not visible.

This is the equivalent of menu_with_enabled with enabled set to true.

pub fn menu_with_enabled<F>(&self, label: impl AsRef<str>, enabled: bool, f: F)

where F: FnOnce(),

Creates a menu and runs a closure to construct the contents.

Note: the closure is not called if the menu is not visible.

impl<'ui> Ui<'ui>

Widgets: Miscellaneous

pub fn button(&self, label: impl AsRef<str>) -> bool

Renders a clickable button.

Returns true if this button was clicked.

This is the equivalent of button_with_size with size set to [0.0, 0.0], which will size the button to the label’s width in the current style. the current style.

pub fn button_with_size(&self, label: impl AsRef<str>, size: [f32; 2]) -> bool

Renders a clickable button.

Returns true if this button was clicked.

Setting size as [0.0, 0.0] will size the button to the label’s width in the current style.

pub fn small_button(&self, label: impl AsRef<str>) -> bool

Renders a small clickable button that is easy to embed in text.

Returns true if this button was clicked.

pub fn invisible_button(&self, id: impl AsRef<str>, size: [f32; 2]) -> bool

Renders a widget with button behaviour without the visual look.

Returns true if this button was clicked.

pub fn invisible_button_flags( &self, id: impl AsRef<str>, size: [f32; 2], flags: ButtonFlags ) -> bool

Renders a widget with button behaviour without the visual look.

Returns true if this button was clicked.

pub fn arrow_button(&self, id: impl AsRef<str>, direction: Direction) -> bool

Renders a square button with an arrow shape.

Returns true if this button was clicked.

pub fn checkbox(&self, label: impl AsRef<str>, value: &mut bool) -> bool

Renders a simple checkbox.

Returns true if this checkbox was clicked.

pub fn checkbox_flags<T>( &self, label: impl AsRef<str>, flags: &mut T, mask: T ) -> bool

where T: Copy + PartialEq + BitOrAssign + BitAndAssign + BitAnd<Output = T> + Not<Output = T>,

Renders a checkbox suitable for toggling bit flags using a mask.

Returns true if this checkbox was clicked.

pub fn radio_button_bool(&self, label: impl AsRef<str>, active: bool) -> bool

Renders a simple radio button.

Returns true if this radio button was clicked.

pub fn radio_button<T>( &self, label: impl AsRef<str>, value: &mut T, button_value: T ) -> bool

where T: Copy + PartialEq,

Renders a radio button suitable for choosing an arbitrary value.

Returns true if this radio button was clicked.

pub fn bullet(&self)

Renders a small circle and keeps the cursor on the same line

impl Ui<'_>

pub fn tab_bar(&self, id: impl AsRef<str>) -> Option<TabBarToken<'_>>

Creates a tab bar and returns a tab bar token, allowing you to append Tab items afterwards. This passes no flags. To pass flags explicitly, use tab_bar_with_flags.

pub fn tab_bar_with_flags( &self, id: impl AsRef<str>, flags: TabBarFlags ) -> Option<TabBarToken<'_>>

Creates a tab bar and returns a tab bar token, allowing you to append Tab items afterwards.

pub fn tab_item(&self, label: impl AsRef<str>) -> Option<TabItemToken<'_>>

Creates a new tab item and returns a token if its contents are visible.

By default, this doesn’t pass an opened bool nor any flags. See tab_item_with_opened and tab_item_with_flags for more.

pub fn tab_item_with_opened( &self, label: impl AsRef<str>, opened: &mut bool ) -> Option<TabItemToken<'_>>

Creates a new tab item and returns a token if its contents are visible.

By default, this doesn’t pass any flags. See [tab_item_with_flags] for more.

pub fn tab_item_with_flags( &self, label: impl AsRef<str>, opened: Option<&mut bool>, flags: TabItemFlags ) -> Option<TabItemToken<'_>>

Creates a new tab item and returns a token if its contents are visible.

impl<'ui> Ui<'ui>

Widgets: Text

pub fn text<T>(&self, text: T)

where T: AsRef<str>,

Renders simple text

pub fn text_colored<T>(&self, color: [f32; 4], text: T)

where T: AsRef<str>,

Renders simple text using the given text color

pub fn text_disabled<T>(&self, text: T)

where T: AsRef<str>,

Renders simple text using StyleColor::TextDisabled color

pub fn text_wrapped(&self, text: impl AsRef<str>)

Renders text wrapped to the end of window (or column)

pub fn label_text(&self, label: impl AsRef<str>, text: impl AsRef<str>)

Render a text + label combination aligned the same way as value+label widgets

pub fn bullet_text(&self, text: impl AsRef<str>)

Renders text with a little bullet aligned to the typical tree node

impl Ui<'_>

pub fn collapsing_header( &self, label: impl AsRef<str>, flags: TreeNodeFlags ) -> bool

Constructs a new collapsing header

pub fn collapsing_header_with_close_button( &self, label: impl AsRef<str>, flags: TreeNodeFlags, opened: &mut bool ) -> bool

Constructs a new collapsing header

impl<'ui> Ui<'ui>

Content region

pub fn content_region_max(&self) -> [f32; 2]

Returns the current content boundaries (in window coordinates)

pub fn content_region_avail(&self) -> [f32; 2]

Equal to ui.content_region_max() - ui.cursor_pos()

pub fn window_content_region_min(&self) -> [f32; 2]

Content boundaries min (in window coordinates).

Roughly equal to [0.0, 0.0] - scroll.

pub fn window_content_region_max(&self) -> [f32; 2]

Content boundaries max (in window coordinates).

Roughly equal to [0.0, 0.0] + size - scroll.

pub fn window_content_region_width(&self) -> f32

impl<'ui> Ui<'ui>

Window scrolling

pub fn scroll_x(&self) -> f32

Returns the horizontal scrolling position.

Value is between 0.0 and self.scroll_max_x().

pub fn scroll_y(&self) -> f32

Returns the vertical scrolling position.

Value is between 0.0 and self.scroll_max_y().

pub fn scroll_max_x(&self) -> f32

Returns the maximum horizontal scrolling position.

Roughly equal to content size X - window size X.

pub fn scroll_max_y(&self) -> f32

Returns the maximum vertical scrolling position.

Roughly equal to content size Y - window size Y.

pub fn set_scroll_x(&self, scroll_x: f32)

Sets the horizontal scrolling position

pub fn set_scroll_y(&self, scroll_y: f32)

Sets the vertical scroll position

pub fn set_scroll_here_x(&self)

Adjusts the horizontal scroll position to make the current cursor position visible.

This is the same as set_scroll_here_x_with_ratio but with ratio at 0.5.

pub fn set_scroll_here_x_with_ratio(&self, center_x_ratio: f32)

Adjusts the horizontal scroll position to make the current cursor position visible.

center_x_ratio:

• 0.0: left
• 0.5: center
• 1.0: right

pub fn set_scroll_here_y(&self)

Adjusts the vertical scroll position to make the current cursor position visible

This is the same as set_scroll_here_y_with_ratio but with ratio at 0.5.

pub fn set_scroll_here_y_with_ratio(&self, center_y_ratio: f32)

Adjusts the vertical scroll position to make the current cursor position visible.

center_y_ratio:

• 0.0: top
• 0.5: center
• 1.0: bottom

pub fn set_scroll_from_pos_x(&self, local_x: f32)

Adjusts the horizontal scroll position to make the given position visible

This is the same as set_scroll_from_pos_x_with_ratio but with ratio at 0.5.

pub fn set_scroll_from_pos_x_with_ratio( &self, local_x: f32, center_x_ratio: f32 )

Adjusts the horizontal scroll position to make the given position visible.

center_x_ratio:

• 0.0: left
• 0.5: center
• 1.0: right

pub fn set_scroll_from_pos_y(&self, local_y: f32)

Adjusts the vertical scroll position to make the given position visible

This is the same as set_scroll_from_pos_y_with_ratio but with ratio at 0.5.

pub fn set_scroll_from_pos_y_with_ratio( &self, local_y: f32, center_y_ratio: f32 )

Adjusts the vertical scroll position to make the given position visible.

center_y_ratio:

• 0.0: top
• 0.5: center
• 1.0: bottom

impl<'ui> Ui<'ui>

Window utilities

pub fn is_window_appearing(&self) -> bool

Returns true if the current window appeared during this frame

pub fn is_window_collapsed(&self) -> bool

Returns true if the current window is in collapsed state (= only the title bar is visible)

pub fn is_window_focused(&self) -> bool

Returns true if the current window is focused

pub fn is_window_focused_with_flags(&self, flags: WindowFocusedFlags) -> bool

Returns true if the current window is focused based on the given flags

pub fn is_window_hovered(&self) -> bool

Returns true if the current window is hovered

pub fn is_window_hovered_with_flags(&self, flags: WindowHoveredFlags) -> bool

Returns true if the current window is hovered based on the given flags

pub fn window_pos(&self) -> [f32; 2]

Returns the position of the current window (in screen space)

pub fn window_size(&self) -> [f32; 2]

Returns the size of the current window

impl<'ui> Ui<'ui>

pub fn from_ctx(ctx: &'ui Context) -> Ui<'ui>

Creates an Ui object with a given context

pub fn io(&self) -> &Io

Returns an immutable reference to the inputs/outputs object

pub fn fonts(&self) -> FontAtlasRef<'_>

Returns an immutable reference to the font atlas

pub fn clone_style(&self) -> Style

Returns a clone of the user interface style

pub fn render(self) -> &'ui DrawData

Renders the frame and returns a reference to the resulting draw data

impl<'ui> Ui<'ui>

Demo, debug, information

pub fn show_demo_window(&self, opened: &mut bool)

Renders a demo window (previously called a test window), which demonstrates most Dear Imgui features.

pub fn show_about_window(&self, opened: &mut bool)

Renders an about window.

Displays the Dear ImGui version/credits, and build/system information.

pub fn show_metrics_window(&self, opened: &mut bool)

Renders a metrics/debug window.

Displays Dear ImGui internals: draw commands (with individual draw calls and vertices), window list, basic internal state, etc.

pub fn show_style_editor(&self, style: &mut Style)

Renders a style editor block (not a window) for the given Style structure

pub fn show_default_style_editor(&self)

Renders a style editor block (not a window) for the currently active style

pub fn show_user_guide(&self)

Renders a basic help/info block (not a window)

impl<'ui> Ui<'ui>

pub fn input_text<'p, L>( &'ui self, label: L, buf: &'p mut String ) -> InputText<'ui, 'p, L>

where L: AsRef<str>,

pub fn input_text_multiline<'p, L>( &'ui self, label: L, buf: &'p mut String, size: [f32; 2] ) -> InputTextMultiline<'ui, 'p, L>

where L: AsRef<str>,

pub fn input_float<'p, L>( &'ui self, label: L, value: &'p mut f32 ) -> InputFloat<'ui, 'p, L>

where L: AsRef<str>,

pub fn input_float2<'p, L>( &'ui self, label: L, value: &'p mut [f32; 2] ) -> InputFloat2<'ui, 'p, L>

where L: AsRef<str>,

pub fn input_float3<'p, L>( &'ui self, label: L, value: &'p mut [f32; 3] ) -> InputFloat3<'ui, 'p, L>

where L: AsRef<str>,

pub fn input_float4<'p, L>( &'ui self, label: L, value: &'p mut [f32; 4] ) -> InputFloat4<'ui, 'p, L>

where L: AsRef<str>,

pub fn input_int<'p, L>( &'ui self, label: L, value: &'p mut i32 ) -> InputInt<'ui, 'p, L>

where L: AsRef<str>,

pub fn input_int2<'p, L>( &'ui self, label: L, value: &'p mut [i32; 2] ) -> InputInt2<'ui, 'p, L>

where L: AsRef<str>,

pub fn input_int3<'p, L>( &'ui self, label: L, value: &'p mut [i32; 3] ) -> InputInt3<'ui, 'p, L>

where L: AsRef<str>,

pub fn input_int4<'p, L>( &'ui self, label: L, value: &'p mut [i32; 4] ) -> InputInt4<'ui, 'p, L>

where L: AsRef<str>,

impl<'ui> Ui<'ui>

Tooltips

pub fn tooltip<F>(&self, f: F)

where F: FnOnce(),

Construct a tooltip window that can have any kind of content.

Typically used with Ui::is_item_hovered() or some other conditional check.

Examples

fn user_interface(ui: &Ui) {
    ui.text("Hover over me");
    if ui.is_item_hovered() {
        ui.tooltip(|| {
            ui.text_colored([1.0, 0.0, 0.0, 1.0], im_str!("I'm red!"));
        });
    }
}

pub fn begin_tooltip(&self) -> TooltipToken<'_>

Construct a tooltip window that can have any kind of content.

Returns a TooltipToken that must be ended by calling .end()

pub fn tooltip_text<T>(&self, text: T)

where T: AsRef<str>,

Construct a tooltip window with simple text content.

Typically used with Ui::is_item_hovered() or some other conditional check.

Examples

fn user_interface(ui: &Ui) {
    ui.text("Hover over me");
    if ui.is_item_hovered() {
        ui.tooltip_text("I'm a tooltip!");
    }
}

impl<'ui> Ui<'ui>

pub fn list_box<'p, StringType>( &self, label: impl AsRef<str>, current_item: &mut i32, items: &'p [&'p StringType], height_in_items: i32 ) -> bool

where StringType: AsRef<str> + ?Sized,

impl<'ui> Ui<'ui>

pub fn plot_lines<'p, Label>( &'ui self, label: Label, values: &'p [f32] ) -> PlotLines<'ui, 'p, Label>

where Label: AsRef<str>,

impl<'ui> Ui<'ui>

pub fn plot_histogram<'p, Label>( &'ui self, label: Label, values: &'p [f32] ) -> PlotHistogram<'ui, 'p, Label>

where Label: AsRef<str>,

impl<'ui> Ui<'ui>

pub fn calc_text_size<T>(&self, text: T) -> [f32; 2]

where T: AsRef<str>,

Calculate the size required for a given text string.

This is the same as calc_text_size_with_opts with hide_text_after_double_hash set to false and wrap_width set to -1.0.

pub fn calc_text_size_with_opts<T>( &self, text: T, hide_text_after_double_hash: bool, wrap_width: f32 ) -> [f32; 2]

where T: AsRef<str>,

Calculate the size required for a given text string.

hide_text_after_double_hash allows the user to insert comments into their text, using a double hash-tag prefix. This is a feature of imgui.

wrap_width allows you to request a width at which to wrap the text to a newline for the calculation.

impl<'ui> Ui<'ui>

Draw list for custom drawing

pub fn get_window_draw_list(&'ui self) -> DrawListMut<'ui>

Get access to drawing API

Examples

fn custom_draw(ui: &Ui) {
    let draw_list = ui.get_window_draw_list();
    // Draw a line
    const WHITE: [f32; 3] = [1.0, 1.0, 1.0];
    draw_list.add_line([100.0, 100.0], [200.0, 200.0], WHITE).build();
    // Continue drawing ...
}

This function will panic if several instances of DrawListMut coexist. Before a new instance is got, a previous instance should be dropped.

fn custom_draw(ui: &Ui) {
    let draw_list = ui.get_window_draw_list();
    // Draw something...

    // This second call will panic!
    let draw_list = ui.get_window_draw_list();
}

pub fn get_background_draw_list(&'ui self) -> DrawListMut<'ui>

pub fn get_foreground_draw_list(&'ui self) -> DrawListMut<'ui>

Trait Implementations

impl<'ui> Debug for Ui<'ui>

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

Formats the value using the given formatter.

impl<'a> Drop for Ui<'a>

fn drop(&mut self)

Executes the destructor for this type.