Dear ImGui end-user API functions#
(Note that ImGui:: being a namespace, you can add extra ImGui:: functions in your own separate file. Please don't modify imgui source files!)
Context creation and access#
- Each context create its own
ImGui::ImFontAtlasby default. You may instance one yourself and pass it toImGui.create_contextto share a font atlas between contexts. - DLL users: heaps and globals are not shared across DLL boundaries! You will need to call
ImGui.set_current_context+ImGui.set_allocator_functionsfor each static/DLL boundary you are calling from. Read "Context and Memory Allocators" section of imgui.cpp for details.
NULL = destroy current context
Main#
access the IO structure (mouse/keyboard/gamepad inputs, time, various configuration options/flags)
access the Style structure (colors, sizes). Always use PushStyleCol(), PushStyleVar() to modify style mid-frame!
start a new Dear ImGui frame, you can submit any command from this point until ImGui.render/ImGui.end_frame.
ends the Dear ImGui frame. automatically called by ImGui.render. If you don't need to render data (skipping rendering) you may call ImGui.end_frame without ImGui.render... but you'll have wasted CPU already! If you don't need to render, better to not create any windows and not call ImGui.new_frame at all!
ends the Dear ImGui frame, finalize the draw data. You can then get call ImGui.get_draw_data.
valid after ImGui.render and until the next call to ImGui.new_frame. this is what you have to render.
Demo, Debug, Information#
create Demo window. demonstrate most ImGui features. call this to learn about the library! try to make it always available in your application!
create Metrics/Debugger window. display Dear ImGui internals: windows, draw commands, various internal state, etc.
create Debug Log window. display a simplified log of important dear imgui events.
create Stack Tool window. hover items with mouse to query information about the source of their unique ID.
create About window. display Dear ImGui version, credits and build/system information.
add style editor block (not a window). you can pass in a reference ImGui::ImGuiStyle structure to compare to, revert to and save to (else it uses the default style)
add style selector block (not a window), essentially a combo listing the default styles.
add font selector block (not a window), essentially a combo listing the loaded fonts.
add basic help/info block (not a window): how to manipulate ImGui as a end-user (mouse/keyboard controls).
get the compiled version string e.g. "1.80 WIP" (essentially the value for IMGUI_VERSION from the compiled version of imgui.cpp)
Styles#
new, recommended style (default)
best used with borders and a custom, thicker font
classic imgui style
Windows#
ImGui.begin= push window to the stack and start appending to it.ImGui.end= pop window from the stack.- Passing 'bool* p_open != NULL' shows a window-closing widget in the upper-right corner of the window, which clicking will set the boolean to false when clicked.
- You may append multiple times to the same window during the same frame by calling
ImGui.begin/ImGui.endpairs multiple times. Some information such as 'flags' or 'p_open' will only be considered by the first call toImGui.begin. ImGui.beginreturn false to indicate the window is collapsed or fully clipped, so you may early out and omit submitting anything to the window. Always call a matchingImGui.endfor eachImGui.begincall, regardless of its return value! [Important: due to legacy reason, this is inconsistent with most other functions such asImGui.begin_menu/ImGui.end_menu,ImGui.begin_popup/ImGui.end_popup, etc. where the EndXXX call should only be called if the corresponding BeginXXX function returned true.ImGui.beginand BeginChild are the only odd ones out. Will be fixed in a future update.]- Note that the bottom of window stack always contains a window called "Debug".
.begin(name : String, p_open : Pointer(Bool) = Pointer(Bool).null, flags : ImGuiWindowFlags = ImGuiWindowFlags.new(0)) : Bool#
Child Windows#
- Use child windows to begin into a self-contained independent scrolling/clipping regions within a host window. Child windows can embed their own child.
- For each independent axis of 'size': ==0.0f: use remaining host window size / >0.0f: fixed size / <0.0f: use remaining window size minus abs(size) / Each axis can use a different mode, e.g.
ImGui::ImVec2(0,400). - BeginChild() returns false to indicate the window is collapsed or fully clipped, so you may early out and omit submitting anything to the window.
Always call a matching
ImGui.end_childfor each BeginChild() call, regardless of its return value. [Important: due to legacy reason, this is inconsistent with most other functions such asImGui.begin_menu/ImGui.end_menu,ImGui.begin_popup/ImGui.end_popup, etc. where the EndXXX call should only be called if the corresponding BeginXXX function returned true.ImGui.beginand BeginChild are the only odd ones out. Will be fixed in a future update.]
.begin_child(str_id : String, size : ImVec2 = ImVec2.new(0, 0), border : Bool = false, flags : ImGuiWindowFlags = ImGuiWindowFlags.new(0)) : Bool#
.begin_child(str_id : String, size : ImVec2 = ImVec2.new(0, 0), border : Bool = false, flags : ImGuiWindowFlags = ImGuiWindowFlags.new(0)) : Bool#
Windows Utilities#
- 'current window' = the window we are appending into while inside a
ImGui.begin/ImGui.endblock. 'next window' = next window we willImGui.begininto.
is current window focused? or its root/child, depending on flags. see flags for options.
is current window hovered (and typically: not blocked by a popup/modal)? see flags for options. NB: If you are trying to check whether your mouse should be dispatched to imgui or to your app, you should use the 'io.WantCaptureMouse' boolean for that! Please read the FAQ!
get draw list associated to the current window, to append your own drawing primitives
get current window position in screen space (useful if you want to do your own drawing via the DrawList API)
get current window size
get current window width (shortcut for ImGui.get_window_size.x)
get current window height (shortcut for ImGui.get_window_size.y)
Window manipulation#
- Prefer using SetNextXXX functions (before
ImGui.begin) rather that SetXXX functions (afterImGui.begin).
.set_next_window_pos(pos : ImVec2, cond : ImGuiCond = ImGuiCond.new(0), pivot : ImVec2 = ImVec2.new(0, 0)) : Void#
set next window position. call before ImGui.begin. use pivot=(0.5f,0.5f) to center on given point, etc.
set next window size. set axis to 0.0f to force an auto-fit on this axis. call before ImGui.begin
.set_next_window_size_constraints(size_min : ImVec2, size_max : ImVec2, custom_callback : ImGuiSizeCallback? = nil, custom_callback_data : Pointer(Void) = Pointer(Void).null) : Void#
set next window size limits. use -1,-1 on either X/Y axis to preserve the current size. Sizes will be rounded down. Use callback to apply non-trivial programmatic constraints.
set next window content size (~ scrollable client area, which enforce the range of scrollbars). Not including window decorations (title bar, menu bar, etc.) nor WindowPadding. set an axis to 0.0f to leave it automatic. call before ImGui.begin
.set_next_window_collapsed(collapsed : Bool, cond : ImGuiCond = ImGuiCond.new(0)) : Void#
set next window collapsed state. call before ImGui.begin
set next window to be focused / top-most. call before ImGui.begin
set next window background color alpha. helper to easily override the Alpha component of ImGuiCol_WindowBg/ChildBg/PopupBg. you may also use ImGuiWindowFlags_NoBackground.
(not recommended) set current window position - call within ImGui.begin/ImGui.end. prefer using ImGui.set_next_window_pos, as this may incur tearing and side-effects.
(not recommended) set current window size - call within ImGui.begin/ImGui.end. set to ImGui::ImVec2(0, 0) to force an auto-fit. prefer using ImGui.set_next_window_size, as this may incur tearing and minor side-effects.
(not recommended) set current window collapsed state. prefer using ImGui.set_next_window_collapsed.
(not recommended) set current window to be focused / top-most. prefer using ImGui.set_next_window_focus.
[OBSOLETE] set font scale. Adjust IO.FontGlobalScale if you want to scale all windows. This is an old API! For correct scaling, prefer to reload font + rebuild ImGui::ImFontAtlas + call style.ScaleAllSizes().
set named window position.
set named window size. set axis to 0.0f to force an auto-fit on this axis.
set named window collapsed state
set named window to be focused / top-most. use NULL to remove focus.
Content region#
- Retrieve available space from a given point.
ImGui.get_content_region_availis frequently useful. - Those functions are bound to be redesigned (they are confusing, incomplete and the Min/Max return values are in local window coordinates which increases confusion)
== ImGui.get_content_region_max - ImGui.get_cursor_pos
current content boundaries (typically window boundaries including scrolling, or current column boundaries), in windows coordinates
content boundaries min for the full window (roughly (0,0)-Scroll), in window coordinates
content boundaries max for the full window (roughly (0,0)+Size-Scroll) where Size can be override with ImGui.set_next_window_content_size, in window coordinates
Windows Scrolling#
get scrolling amount [0 .. ImGui.get_scroll_max_x]
get scrolling amount [0 .. ImGui.get_scroll_max_y]
set scrolling amount [0 .. ImGui.get_scroll_max_x]
set scrolling amount [0 .. ImGui.get_scroll_max_y]
get maximum scrolling amount ~~ ContentSize.x - WindowSize.x - DecorationsSize.x
get maximum scrolling amount ~~ ContentSize.y - WindowSize.y - DecorationsSize.y
adjust scrolling amount to make current cursor position visible. center_x_ratio=0.0: left, 0.5: center, 1.0: right. When using to make a "default/current item" visible, consider using ImGui.set_item_default_focus instead.
adjust scrolling amount to make current cursor position visible. center_y_ratio=0.0: top, 0.5: center, 1.0: bottom. When using to make a "default/current item" visible, consider using ImGui.set_item_default_focus instead.
adjust scrolling amount to make given position visible. Generally ImGui.get_cursor_start_pos + offset to compute a valid position.
adjust scrolling amount to make given position visible. Generally ImGui.get_cursor_start_pos + offset to compute a valid position.
Parameters stacks (shared)#
use NULL as a shortcut to push default font
modify a style color. always use this if you modify the style after ImGui.new_frame.
modify a style float variable. always use this if you modify the style after ImGui.new_frame.
modify a style ImGui::ImVec2 variable. always use this if you modify the style after ImGui.new_frame.
== tab stop enable. Allow focusing using TAB/Shift-TAB, enabled by default but you can disable it for certain widgets
in 'repeat' mode, ImGui.button*() functions return repeated true in a typematic manner (using io.KeyRepeatDelay/io.KeyRepeatRate setting). Note that you can call ImGui.is_item_active after any ImGui.button to tell if the button is held in the current frame.
Parameters stacks (current window)#
push width of items for common large "item+label" widgets. >0.0f: width in pixels, <0.0f align xx pixels to the right of window (so -FLT_MIN always align width to the right side).
set width of the next common large "item+label" widget. >0.0f: width in pixels, <0.0f align xx pixels to the right of window (so -FLT_MIN always align width to the right side)
width of item given pushed settings and current cursor position. NOT necessarily the width of last item unlike most 'Item' functions.
push word-wrapping position for ImGui.text*() commands. < 0.0f: no wrapping; 0.0f: wrap to end of window (or column); > 0.0f: wrap at 'wrap_pos_x' position in window local space
Style read access#
- Use the style editor (
ImGui.show_style_editorfunction) to interactively see what the colors are)
get current font
get current font size (= height in pixels) of current font with current scale applied
get UV coordinate for a while pixel, useful to draw custom shapes via the ImGui::ImDrawList API
retrieve given style color with style alpha applied and optional extra alpha multiplier, packed as a 32-bit value suitable for ImGui::ImDrawList
retrieve given color with style alpha applied, packed as a 32-bit value suitable for ImGui::ImDrawList
retrieve given color with style alpha applied, packed as a 32-bit value suitable for ImGui::ImDrawList
retrieve style color as stored in ImGui::ImGuiStyle structure. use to feed back into PushStyleColor(), otherwise use GetColorU32() to get style color with style alpha baked in.
Cursor / Layout#
- By "cursor" we mean the current output position.
- The typical widget behavior is to output themselves at the current cursor position, then move the cursor one line down.
- You can call
ImGui.same_linebetween widgets to undo the last carriage return and output at the right of the preceding widget. - Attention! We currently have inconsistencies between window-local and absolute positions we will aim to fix with future API:
Window-local coordinates:
ImGui.same_line,ImGui.get_cursor_pos,ImGui.set_cursor_pos,ImGui.get_cursor_start_pos,ImGui.get_content_region_max, GetWindowContentRegion*(),ImGui.push_text_wrap_posAbsolute coordinate:ImGui.get_cursor_screen_pos,ImGui.set_cursor_screen_pos, allImGui::ImDrawList:: functions.
separator, generally horizontal. inside a menu bar or in horizontal layout mode, this becomes a vertical separator.
call between widgets or groups to layout them horizontally. X position given in window coordinates.
undo a ImGui.same_line or force a new line when in an horizontal-layout context.
add vertical spacing.
add a dummy item of given size. unlike ImGui.invisible_button, ImGui.dummy won't take the mouse click or be navigable into.
move content position toward the right, by indent_w, or style.IndentSpacing if indent_w <= 0
move content position back to the left, by indent_w, or style.IndentSpacing if indent_w <= 0
lock horizontal starting position
unlock horizontal starting position + capture the whole group bounding box into one "item" (so you can use ImGui.is_item_hovered or layout primitives such as ImGui.same_line on whole group, etc.)
cursor position in window coordinates (relative to window position)
(some functions are using window-relative coordinates, such as: ImGui.get_cursor_pos, ImGui.get_cursor_start_pos, ImGui.get_content_region_max, GetWindowContentRegion* etc.
other functions such as [`ImGui.get_cursor_screen_pos`][] or everything in [`ImGui::ImDrawList`][]::
are using the main, absolute coordinate system.
[`ImGui.get_window_pos`][] + [`ImGui.get_cursor_pos`][] == [`ImGui.get_cursor_screen_pos`][] etc.)
initial cursor position in window coordinates
cursor position in absolute coordinates (useful to work with ImGui::ImDrawList API). generally top-left == ImGui.get_main_viewport->Pos == (0,0) in single viewport mode, and bottom-right == ImGui.get_main_viewport->Pos+Size == io.DisplaySize in single-viewport mode.
cursor position in absolute coordinates
vertically align upcoming text baseline to FramePadding.y so that it will align properly to regularly framed items (call if you have text on a line before a framed item)
~ FontSize
~ FontSize + style.ItemSpacing.y (distance in pixels between 2 consecutive lines of text)
~ FontSize + style.FramePadding.y * 2
~ FontSize + style.FramePadding.y * 2 + style.ItemSpacing.y (distance in pixels between 2 consecutive lines of framed widgets)
ID stack/scopes#
Read the FAQ (docs/FAQ.md or http://dearimgui.org/faq) for more details about how ID are handled in dear imgui.
- Those questions are answered and impacted by understanding of the ID stack system:
- "Q: Why is my widget not reacting when I click on it?"
- "Q: How can I have widgets with an empty label?"
- "Q: How can I have multiple widgets with the same label?"
- Short version: ID are hashes of the entire ID stack. If you are creating widgets in a loop you most likely want to push a unique identifier (e.g. object pointer, loop index) to uniquely differentiate them.
- You can also use the "Label##foobar" syntax within widget label to distinguish them from each others.
- In this header file we use the "label"/"name" terminology to denote a string that will be displayed + used as an ID, whereas "str_id" denote a string that is only used as an ID and not normally displayed.
push string into the ID stack (will hash string).
push string into the ID stack (will hash string).
push pointer into the ID stack (will hash pointer).
push integer into the ID stack (will hash integer).
pop from the ID stack.
calculate unique ID (hash of whole ID stack + given parameter). e.g. if you want to query into ImGui::ImGuiStorage yourself
Widgets: ImGui.text#
raw text without formatting. Roughly equivalent to ImGui.text("%s", text) but: A) doesn't require null terminated string if 'text_end' is specified, B) it's faster, no memory copy is done, no buffer size limits, recommended for long chunks of text.
formatted text
shortcut for PushStyleColor(ImGuiCol_Text, col); ImGui.text(fmt, ...); ImGui.pop_style_color;
shortcut for PushStyleColor(ImGuiCol_Text, style.Colors[ImGuiCol_TextDisabled]); ImGui.text(fmt, ...); ImGui.pop_style_color;
shortcut for ImGui.push_text_wrap_pos(0.0f); ImGui.text(fmt, ...); ImGui.pop_text_wrap_pos;. Note that this won't work on an auto-resizing window if there's no other widgets to extend the window width, yoy may need to set a size using ImGui.set_next_window_size.
display text+label aligned the same way as value+label widgets
shortcut for ImGui.bullet+ImGui.text
Widgets: Main#
- Most widgets return true when the value has been changed or when pressed/selected
- You may also use one of the many IsItemXXX functions (e.g.
ImGui.is_item_active,ImGui.is_item_hovered, etc.) to query widget state.
button
button with FramePadding=(0,0) to easily embed within text
.invisible_button(str_id : String, size : ImVec2, flags : ImGuiButtonFlags = ImGuiButtonFlags.new(0)) : Bool#
flexible button behavior without the visuals, frequently useful to build custom behaviors using the public api (along with ImGui.is_item_active, ImGui.is_item_hovered, etc.)
square button with an arrow shape
.image(user_texture_id : ImTextureID, size : ImVec2, uv0 : ImVec2 = ImVec2.new(0, 0), uv1 : ImVec2 = ImVec2.new(1, 1), tint_col : ImVec4 = ImVec4.new(1, 1, 1, 1), border_col : ImVec4 = ImVec4.new(0, 0, 0, 0)) : Void#
.image_button(user_texture_id : ImTextureID, size : ImVec2, uv0 : ImVec2 = ImVec2.new(0, 0), uv1 : ImVec2 = ImVec2.new(1, 1), frame_padding : Int32 = -1, bg_col : ImVec4 = ImVec4.new(0, 0, 0, 0), tint_col : ImVec4 = ImVec4.new(1, 1, 1, 1)) : Bool#
<0 frame_padding uses default frame padding settings. 0 for no padding
use with e.g. if (RadioButton("one", my_value==1)) { my_value = 1; }
shortcut to handle the above pattern when value is an integer
.progress_bar(fraction : Float32, size_arg : ImVec2 = ImVec2.new(-Float32::MIN_POSITIVE, 0), overlay : String? = nil) : Void#
draw a small circle + keep the cursor on the same line. advance cursor x position by ImGui.get_tree_node_to_label_spacing, same distance that TreeNode() uses
Widgets: Combo Box#
- The
ImGui.begin_combo/ImGui.end_comboapi allows you to manage your contents and selection state however you want it, by creating e.g. Selectable() items. - The old Combo() api are helpers over
ImGui.begin_combo/ImGui.end_combowhich are kept available for convenience purpose. This is analogous to how ListBox are created.
.begin_combo(label : String, preview_value : String, flags : ImGuiComboFlags = ImGuiComboFlags.new(0)) : Bool#
only call ImGui.end_combo if ImGui.begin_combo returns true!
.combo(label : String, preview_value : String, flags : ImGuiComboFlags = ImGuiComboFlags.new(0), &) : Nil#
Calls begin_combo, conditionally yields to the block, then conditionally calls end_combo.
.combo(label : String, preview_value : String, flags : ImGuiComboFlags = ImGuiComboFlags.new(0), &) : Nil#
Calls begin_combo, conditionally yields to the block, then conditionally calls end_combo.
Separate items with \0 within a string, end item-list with \0\0. e.g. "One\0Two\0Three\0"
.combo(label : String, preview_value : String, flags : ImGuiComboFlags = ImGuiComboFlags.new(0), &) : Nil#
Calls begin_combo, conditionally yields to the block, then conditionally calls end_combo.
Widgets: Drag Sliders#
- CTRL+Click on any drag box to turn them into an input box. Manually input values aren't clamped by default and can go off-bounds. Use ImGuiSliderFlags_AlwaysClamp to always clamp.
- For all the Float2/Float3/Float4/Int2/Int3/Int4 versions of every functions, note that a 'float v[X]' function argument is the same as 'float* v', the array syntax is just a way to document the number of elements that are expected to be accessible. You can pass address of your first element out of a contiguous set, e.g. &myvector.x
- Adjust format string to decorate the value with a prefix, a suffix, or adapt the editing and display precision e.g. "%.3f" -> 1.234; "%5.2f secs" -> 01.23 secs; "Biscuit: %.0f" -> Biscuit: 1; etc.
- Format string may also be set to NULL or use the default format ("%f" or "%d").
- Speed are per-pixel of mouse movement (v_speed=0.2f: mouse needs to move by 5 pixels to increase value by 1). For gamepad/keyboard navigation, minimum speed is Max(v_speed, minimum_step_at_given_precision).
- Use v_min < v_max to clamp edits to given limits. Note that CTRL+Click manual input can override those limits if ImGuiSliderFlags_AlwaysClamp is not used.
- Use v_max = FLT_MAX / INT_MAX etc to avoid clamping to a maximum, same with v_min = -FLT_MAX / INT_MIN to avoid clamping to a minimum.
- We use the same sets of flags for DragXXX() and SliderXXX() functions as the features are the same and it makes it easier to swap them.
- Legacy: Pre-1.78 there are DragXXX() function signatures that takes a final
float power=1.0f' argument instead of theImGui::ImGuiSliderFlagsflags=0' argument. If you get a warning converting a float toImGui::ImGuiSliderFlags, read https://github.com/ocornut/imgui/issues/3361
.drag_float(label : String, v : Pointer(Float32), v_speed : Float32 = 1.0, v_min : Float32 = 0.0, v_max : Float32 = 0.0, format : String = "%.3f", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
If v_min >= v_max we have no bound
.drag_float2(label : String, v : Pointer(ImVec2) | Indexable(Float32) | Pointer(Float32), v_speed : Float32 = 1.0, v_min : Float32 = 0.0, v_max : Float32 = 0.0, format : String = "%.3f", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.drag_float3(label : String, v : Indexable(Float32) | Pointer(Float32), v_speed : Float32 = 1.0, v_min : Float32 = 0.0, v_max : Float32 = 0.0, format : String = "%.3f", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.drag_float4(label : String, v : Pointer(ImVec4) | Indexable(Float32) | Pointer(Float32), v_speed : Float32 = 1.0, v_min : Float32 = 0.0, v_max : Float32 = 0.0, format : String = "%.3f", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.drag_float_range2(label : String, v_current_min : Pointer(Float32), v_current_max : Pointer(Float32), v_speed : Float32 = 1.0, v_min : Float32 = 0.0, v_max : Float32 = 0.0, format : String = "%.3f", format_max : String? = nil, flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.drag_int(label : String, v : Pointer(Int32), v_speed : Float32 = 1.0, v_min : Int32 = 0, v_max : Int32 = 0, format : String = "%d", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
If v_min >= v_max we have no bound
.drag_int2(label : String, v : Indexable(Int32) | Pointer(Int32), v_speed : Float32 = 1.0, v_min : Int32 = 0, v_max : Int32 = 0, format : String = "%d", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.drag_int3(label : String, v : Indexable(Int32) | Pointer(Int32), v_speed : Float32 = 1.0, v_min : Int32 = 0, v_max : Int32 = 0, format : String = "%d", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.drag_int4(label : String, v : Indexable(Int32) | Pointer(Int32), v_speed : Float32 = 1.0, v_min : Int32 = 0, v_max : Int32 = 0, format : String = "%d", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.drag_int_range2(label : String, v_current_min : Pointer(Int32), v_current_max : Pointer(Int32), v_speed : Float32 = 1.0, v_min : Int32 = 0, v_max : Int32 = 0, format : String = "%d", format_max : String? = nil, flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.drag_scalar(label : String, p_data : Pointer(Int8), v_speed : Float32 = 1.0, p_min : Int8? = nil, p_max : Int8? = nil, format : String? = nil, flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.drag_scalar_n(label : String, p_data : Pointer(Int8), components : Int32, v_speed : Float32 = 1.0, p_min : Pointer(Int8) = Pointer(Int8).null, p_max : Pointer(Int8) = Pointer(Int8).null, format : String? = nil, flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
Widgets: Regular Sliders#
- CTRL+Click on any slider to turn them into an input box. Manually input values aren't clamped by default and can go off-bounds. Use ImGuiSliderFlags_AlwaysClamp to always clamp.
- Adjust format string to decorate the value with a prefix, a suffix, or adapt the editing and display precision e.g. "%.3f" -> 1.234; "%5.2f secs" -> 01.23 secs; "Biscuit: %.0f" -> Biscuit: 1; etc.
- Format string may also be set to NULL or use the default format ("%f" or "%d").
- Legacy: Pre-1.78 there are SliderXXX() function signatures that takes a final
float power=1.0f' argument instead of theImGui::ImGuiSliderFlagsflags=0' argument. If you get a warning converting a float toImGui::ImGuiSliderFlags, read https://github.com/ocornut/imgui/issues/3361
.slider_float(label : String, v : Pointer(Float32), v_min : Float32, v_max : Float32, format : String = "%.3f", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
adjust format to decorate the value with a prefix or a suffix for in-slider labels or unit display.
.slider_float2(label : String, v : Pointer(ImVec2) | Indexable(Float32) | Pointer(Float32), v_min : Float32, v_max : Float32, format : String = "%.3f", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.slider_float3(label : String, v : Indexable(Float32) | Pointer(Float32), v_min : Float32, v_max : Float32, format : String = "%.3f", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.slider_float4(label : String, v : Pointer(ImVec4) | Indexable(Float32) | Pointer(Float32), v_min : Float32, v_max : Float32, format : String = "%.3f", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.slider_angle(label : String, v_rad : Pointer(Float32), v_degrees_min : Float32 = -360.0, v_degrees_max : Float32 = +360.0, format : String = "%.0 deg", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.slider_int(label : String, v : Pointer(Int32), v_min : Int32, v_max : Int32, format : String = "%d", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.slider_int2(label : String, v : Indexable(Int32) | Pointer(Int32), v_min : Int32, v_max : Int32, format : String = "%d", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.slider_int3(label : String, v : Indexable(Int32) | Pointer(Int32), v_min : Int32, v_max : Int32, format : String = "%d", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.slider_int4(label : String, v : Indexable(Int32) | Pointer(Int32), v_min : Int32, v_max : Int32, format : String = "%d", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.slider_scalar(label : String, p_data : Pointer(Int8), p_min : Int8, p_max : Int8, format : String? = nil, flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.slider_scalar_n(label : String, p_data : Pointer(Int8), components : Int32, p_min : Pointer(Int8), p_max : Pointer(Int8), format : String? = nil, flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.v_slider_float(label : String, size : ImVec2, v : Pointer(Float32), v_min : Float32, v_max : Float32, format : String = "%.3f", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.v_slider_int(label : String, size : ImVec2, v : Pointer(Int32), v_min : Int32, v_max : Int32, format : String = "%d", flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
.v_slider_scalar(label : String, size : ImVec2, p_data : Pointer(Int8), p_min : Int8, p_max : Int8, format : String? = nil, flags : ImGuiSliderFlags = ImGuiSliderFlags.new(0)) : Bool#
Widgets: Input with Keyboard#
- If you want to use
ImGui.input_textwith std::string or any custom dynamic string type, see misc/cpp/imgui_stdlib.h and comments in imgui_demo.cpp. - Most of the
ImGui::ImGuiInputTextFlagsflags are only useful forImGui.input_textand not for InputFloatX, InputIntX,ImGui.input_doubleetc.
.input_text(label : String, buf : Bytes, flags : ImGuiInputTextFlags = ImGuiInputTextFlags.new(0), callback : ImGuiInputTextCallback? = nil, user_data : Pointer(Void) = Pointer(Void).null) : Bool#
.input_text_multiline(label : String, buf : Bytes, size : ImVec2 = ImVec2.new(0, 0), flags : ImGuiInputTextFlags = ImGuiInputTextFlags.new(0), callback : ImGuiInputTextCallback? = nil, user_data : Pointer(Void) = Pointer(Void).null) : Bool#
.input_text_with_hint(label : String, hint : String, buf : Bytes, flags : ImGuiInputTextFlags = ImGuiInputTextFlags.new(0), callback : ImGuiInputTextCallback? = nil, user_data : Pointer(Void) = Pointer(Void).null) : Bool#
.input_float(label : String, v : Pointer(Float32), step : Float32 = 0.0, step_fast : Float32 = 0.0, format : String = "%.3f", flags : ImGuiInputTextFlags = ImGuiInputTextFlags.new(0)) : Bool#
.input_float2(label : String, v : Pointer(ImVec2) | Indexable(Float32) | Pointer(Float32), format : String = "%.3f", flags : ImGuiInputTextFlags = ImGuiInputTextFlags.new(0)) : Bool#
.input_float3(label : String, v : Indexable(Float32) | Pointer(Float32), format : String = "%.3f", flags : ImGuiInputTextFlags = ImGuiInputTextFlags.new(0)) : Bool#
.input_float4(label : String, v : Pointer(ImVec4) | Indexable(Float32) | Pointer(Float32), format : String = "%.3f", flags : ImGuiInputTextFlags = ImGuiInputTextFlags.new(0)) : Bool#
.input_int(label : String, v : Pointer(Int32), step : Int32 = 1, step_fast : Int32 = 100, flags : ImGuiInputTextFlags = ImGuiInputTextFlags.new(0)) : Bool#
.input_int2(label : String, v : Indexable(Int32) | Pointer(Int32), flags : ImGuiInputTextFlags = ImGuiInputTextFlags.new(0)) : Bool#
.input_int3(label : String, v : Indexable(Int32) | Pointer(Int32), flags : ImGuiInputTextFlags = ImGuiInputTextFlags.new(0)) : Bool#
.input_int4(label : String, v : Indexable(Int32) | Pointer(Int32), flags : ImGuiInputTextFlags = ImGuiInputTextFlags.new(0)) : Bool#
.input_double(label : String, v : Pointer(Float64), step : Float64 = 0.0, step_fast : Float64 = 0.0, format : String = "%.6f", flags : ImGuiInputTextFlags = ImGuiInputTextFlags.new(0)) : Bool#
.input_scalar(label : String, p_data : Pointer(Int8), p_step : Int8? = nil, p_step_fast : Int8? = nil, format : String? = nil, flags : ImGuiInputTextFlags = ImGuiInputTextFlags.new(0)) : Bool#
.input_scalar_n(label : String, p_data : Pointer(Int8), components : Int32, p_step : Pointer(Int8) = Pointer(Int8).null, p_step_fast : Pointer(Int8) = Pointer(Int8).null, format : String? = nil, flags : ImGuiInputTextFlags = ImGuiInputTextFlags.new(0)) : Bool#
Widgets: Color Editor/Picker (tip: the ColorEdit* functions have a little color square that can be left-clicked to open a picker, and right-clicked to open an option menu.)
- Note that in C++ a 'float v[X]' function argument is the same as 'float* v', the array syntax is just a way to document the number of elements that are expected to be accessible.
- You can pass the address of a first float element out of a contiguous structure, e.g. &myvector.x
.color_edit3(label : String, col : Pointer(ImVec4) | Indexable(Float32) | Pointer(Float32), flags : ImGuiColorEditFlags = ImGuiColorEditFlags.new(0)) : Bool#
.color_edit4(label : String, col : Pointer(ImVec4) | Indexable(Float32) | Pointer(Float32), flags : ImGuiColorEditFlags = ImGuiColorEditFlags.new(0)) : Bool#
.color_picker3(label : String, col : Pointer(ImVec4) | Indexable(Float32) | Pointer(Float32), flags : ImGuiColorEditFlags = ImGuiColorEditFlags.new(0)) : Bool#
.color_picker4(label : String, col : Pointer(ImVec4) | Indexable(Float32) | Pointer(Float32), flags : ImGuiColorEditFlags = ImGuiColorEditFlags.new(0), ref_col : Pointer(Float32) = Pointer(Float32).null) : Bool#
.color_button(desc_id : String, col : ImVec4, flags : ImGuiColorEditFlags = ImGuiColorEditFlags.new(0), size : ImVec2 = ImVec2.new(0, 0)) : Bool#
display a color square/button, hover for details, return true when pressed.
initialize current options (generally on application startup) if you want to select a default format, picker type, etc. User will be able to change many settings, unless you pass the _NoOptions flag to your calls.
Widgets: Trees#
- TreeNode functions return true when the node is open, in which case you need to also call
ImGui.tree_popwhen you are finished displaying the tree node contents.
helper variation to easily decorelate the id from the displayed string. Read the FAQ about why and how to use ID. to align arbitrary text at the same level as a TreeNode() you can use ImGui.bullet.
"
~ ImGui.indent+PushId(). Already called by TreeNode() when returning true, but you can call TreePush/ImGui.tree_pop yourself if desired.
"
~ ImGui.unindent+PopId()
horizontal distance preceding label when using TreeNode() or ImGui.bullet == (g.FontSize + style.FramePadding.x2) for a regular unframed TreeNode
.collapsing_header(label : String, flags : ImGuiTreeNodeFlags = ImGuiTreeNodeFlags.new(0)) : Bool#
if returning 'true' the header is open. doesn't indent nor push on ID stack. user doesn't have to call ImGui.tree_pop.
.collapsing_header(label : String, flags : ImGuiTreeNodeFlags = ImGuiTreeNodeFlags.new(0)) : Bool#
when 'p_visible != NULL': if 'p_visible==true' display an additional small close button on upper right of the header which will set the bool to false when clicked, if 'p_visible==false' don't display the header.
set next TreeNode/CollapsingHeader open state.
Widgets: Selectables#
- A selectable highlights when hovered, and can display another color when selected.
- Neighbors selectable extend their highlight bounds in order to leave no gap between them. This is so a series of selected Selectable appear contiguous.
.selectable(label : String, selected : Bool = false, flags : ImGuiSelectableFlags = ImGuiSelectableFlags.new(0), size : ImVec2 = ImVec2.new(0, 0)) : Bool#
"bool selected" carry the selection state (read-only). Selectable() is clicked is returns true so you can modify your selection state. size.x==0.0: use remaining width, size.x>0.0: specify width. size.y==0.0: use label height, size.y>0.0: specify height
.selectable(label : String, selected : Bool = false, flags : ImGuiSelectableFlags = ImGuiSelectableFlags.new(0), size : ImVec2 = ImVec2.new(0, 0)) : Bool#
"bool* p_selected" point to the selection state (read-write), as a convenient helper.
Widgets: List Boxes#
- This is essentially a thin wrapper to using BeginChild/
ImGui.end_childwith some stylistic changes. - The
ImGui.begin_list_box/ImGui.end_list_boxapi allows you to manage your contents and selection state however you want it, by creating e.g. Selectable() or any items. - The simplified/old ListBox() api are helpers over
ImGui.begin_list_box/ImGui.end_list_boxwhich are kept available for convenience purpose. This is analoguous to how Combos are created. - Choose frame width: size.x > 0.0f: custom / size.x < 0.0f or -FLT_MIN: right-align / size.x = 0.0f (default): use current ItemWidth
- Choose frame height: size.y > 0.0f: custom / size.y < 0.0f or -FLT_MIN: bottom-align / size.y = 0.0f (default): arbitrary default height which can fit ~7 items
open a framed scrolling region
only call ImGui.end_list_box if ImGui.begin_list_box returned true!
.list_box(label : String, current_item : Pointer(Int32) | Pointer, items_count : Int32, height_in_items : Int32 = -1, &block : Int32 -> Slice(UInt8) | String | Nil) : Bool#
.list_box(label : String, current_item : Pointer(Int32) | Pointer, items_count : Int32, height_in_items : Int32 = -1, &block : Int32 -> Slice(UInt8) | String | Nil) : Bool#
Widgets: Data Plotting#
- Consider using ImPlot (https://github.com/epezent/implot) which is much better!
.plot_lines(label : String, values : Indexable(Float32), values_offset : Int32 = 0, overlay_text : String? = nil, scale_min : Float32 = Float32::MAX, scale_max : Float32 = Float32::MAX, graph_size : ImVec2 = ImVec2.new(0, 0), stride : Int32 = sizeof(Float32)) : Void#
.plot_lines(label : String, values : Indexable(Float32), values_offset : Int32 = 0, overlay_text : String? = nil, scale_min : Float32 = Float32::MAX, scale_max : Float32 = Float32::MAX, graph_size : ImVec2 = ImVec2.new(0, 0), stride : Int32 = sizeof(Float32)) : Void#
.plot_histogram(label : String, values : Indexable(Float32), values_offset : Int32 = 0, overlay_text : String? = nil, scale_min : Float32 = Float32::MAX, scale_max : Float32 = Float32::MAX, graph_size : ImVec2 = ImVec2.new(0, 0), stride : Int32 = sizeof(Float32)) : Void#
.plot_histogram(label : String, values : Indexable(Float32), values_offset : Int32 = 0, overlay_text : String? = nil, scale_min : Float32 = Float32::MAX, scale_max : Float32 = Float32::MAX, graph_size : ImVec2 = ImVec2.new(0, 0), stride : Int32 = sizeof(Float32)) : Void#
Widgets: Value() Helpers.
- Those are merely shortcut to calling
ImGui.textwith a format string. Output single value in "name: value" format (tip: freely declare more in your code to handle your types. you can add functions to the ImGui namespace)
Widgets: Menus#
- Use
ImGui.begin_menu_baron a window ImGuiWindowFlags_MenuBar to append to its menu bar. - Use
ImGui.begin_main_menu_barto create a menu bar at the top of the screen and append to it. - Use
ImGui.begin_menuto create a menu. You can callImGui.begin_menumultiple time with the same identifier to append more items to it. - Not that MenuItem() keyboardshortcuts are displayed as a convenience but not processed by Dear ImGui at the moment.
append to menu-bar of current window (requires ImGuiWindowFlags_MenuBar flag set on parent window).
only call ImGui.end_menu_bar if ImGui.begin_menu_bar returns true!
create and append to a full screen menu-bar.
only call ImGui.end_main_menu_bar if ImGui.begin_main_menu_bar returns true!
create a sub-menu entry. only call ImGui.end_menu if this returns true!
only call ImGui.end_menu if ImGui.begin_menu returns true!
.menu_item(label : String, shortcut : String? = nil, selected : Bool = false, enabled : Bool = true) : Bool#
return true when activated.
.menu_item(label : String, shortcut : String? = nil, selected : Bool = false, enabled : Bool = true) : Bool#
return true when activated + toggle (*p_selected) if p_selected != NULL
Tooltips#
- Tooltip are windows following the mouse. They do not take focus away.
begin/append a tooltip window. to create full-featured tooltip (with any kind of items).
set a text-only tooltip, typically use with ImGui.is_item_hovered. override any previous call to ImGui.set_tooltip.
Popups, Modals#
- They block normal mouse hovering detection (and therefore most mouse interactions) behind them.
- If not modal: they can be closed by clicking anywhere outside them, or by pressing ESCAPE.
- Their visibility state (~bool) is held internally instead of being held by the programmer as we are used to with regular
ImGui.begin*() calls. - The 3 properties above are related: we need to retain popup visibility state in the library because popups may be closed as any time.
- You can bypass the hovering restriction by using ImGuiHoveredFlags_AllowWhenBlockedByPopup when calling
ImGui.is_item_hoveredorImGui.is_window_hovered. -
Important
Popup identifiers are relative to the current ID stack, so OpenPopup and
ImGui.begin_popupgenerally needs to be at the same level of the stack. This is sometimes leading to confusing mistakes. May rework this in the future.
Popups: begin/end functions#
ImGui.begin_popup: query popup state, if open start appending into the window. CallImGui.end_popupafterwards.ImGui::ImGuiWindowFlagsare forwarded to the window.ImGui.begin_popup_modal: block every interactions behind the window, cannot be closed by user, add a dimming background, has a title bar.
.begin_popup(str_id : String, flags : ImGuiWindowFlags = ImGuiWindowFlags.new(0)) : Bool#
return true if the popup is open, and you can start outputting to it.
.begin_popup_modal(name : String, p_open : Pointer(Bool) = Pointer(Bool).null, flags : ImGuiWindowFlags = ImGuiWindowFlags.new(0)) : Bool#
return true if the modal is open, and you can start outputting to it.
only call ImGui.end_popup if BeginPopupXXX() returns true!
Popups: open/close functions#
- OpenPopup(): set popup state to open.
ImGui::ImGuiPopupFlagsare available for opening options. - If not modal: they can be closed by clicking anywhere outside them, or by pressing ESCAPE.
ImGui.close_current_popup: use inside theImGui.begin_popup/ImGui.end_popupscope to close manually.ImGui.close_current_popupis called by default by Selectable()/MenuItem() when activated (FIXME: need some options).- Use ImGuiPopupFlags_NoOpenOverExistingPopup to avoid opening a popup if there's already one at the same level. This is equivalent to e.g. testing for !IsAnyPopupOpen() prior to OpenPopup().
- Use
ImGui.is_window_appearingafterImGui.begin_popupto tell if a window just opened. -
Important
Notice that for
ImGui.open_popup_on_item_clickwe exceptionally default flags to 1 (== ImGuiPopupFlags_MouseButtonRight) for backward compatibility with older API taking 'int mouse_button = 1' parameter
.open_popup(str_id : String, popup_flags : ImGuiPopupFlags = ImGuiPopupFlags.new(0)) : Void#
call to mark popup as open (don't call every frame!).
.open_popup(str_id : String, popup_flags : ImGuiPopupFlags = ImGuiPopupFlags.new(0)) : Void#
id overload to facilitate calling from nested stacks
.open_popup_on_item_click(str_id : String? = nil, popup_flags : ImGuiPopupFlags = ImGuiPopupFlags.new(1)) : Void#
helper to open popup when clicked on last item. Default to ImGuiPopupFlags_MouseButtonRight == 1. (note: actually triggers on the mouse released event to be consistent with popup behaviors)
manually close the popup we have begin-ed into.
Popups: open+begin combined functions helpers#
- Helpers to do OpenPopup+
ImGui.begin_popupwhere the Open action is triggered by e.g. hovering an item and right-clicking. - They are convenient to easily create context menus, hence the name.
-
Important
Notice that BeginPopupContextXXX takes
ImGui::ImGuiPopupFlagsjust like OpenPopup() and unlikeImGui.begin_popup. For full consistency, we may addImGui::ImGuiWindowFlagsto the BeginPopupContextXXX functions in the future. -
Important
Notice that we exceptionally default their flags to 1 (== ImGuiPopupFlags_MouseButtonRight) for backward compatibility with older API taking 'int mouse_button = 1' parameter, so if you add other flags remember to re-add the ImGuiPopupFlags_MouseButtonRight.
.begin_popup_context_item(str_id : String? = nil, popup_flags : ImGuiPopupFlags = ImGuiPopupFlags.new(1)) : Bool#
open+begin popup when clicked on last item. Use str_id==NULL to associate the popup to previous item. If you want to use that on a non-interactive item such as ImGui.text you need to pass in an explicit ID here. read comments in .cpp!
.begin_popup_context_window(str_id : String? = nil, popup_flags : ImGuiPopupFlags = ImGuiPopupFlags.new(1)) : Bool#
.begin_popup_context_void(str_id : String? = nil, popup_flags : ImGuiPopupFlags = ImGuiPopupFlags.new(1)) : Bool#
open+begin popup when clicked in void (where there are no windows).
Popups: query functions#
- IsPopupOpen(): return true if the popup is open at the current
ImGui.begin_popuplevel of the popup stack. - IsPopupOpen() with ImGuiPopupFlags_AnyPopupId: return true if any popup is open at the current
ImGui.begin_popuplevel of the popup stack. - IsPopupOpen() with ImGuiPopupFlags_AnyPopupId + ImGuiPopupFlags_AnyPopupLevel: return true if any popup is open.
.is_popup_open(str_id : String, flags : ImGuiPopupFlags = ImGuiPopupFlags.new(0)) : Bool#
return true if the popup is open.
Tables#
- Full-featured replacement for old
ImGui.columnsAPI. - See Demo->Tables for demo code. See top of imgui_tables.cpp for general commentary.
- See
ImGui::ImGuiTableFlagsandImGui::ImGuiTableColumnFlagsenums for a description of available flags.
The typical call flow is:
-
- Call
ImGui.begin_table, early out if returning false.
- Call
-
- Optionally call
ImGui.table_setup_columnto submit column name/flags/defaults.
- Optionally call
-
- Optionally call
ImGui.table_setup_scroll_freezeto request scroll freezing of columns/rows.
- Optionally call
-
- Optionally call
ImGui.table_headers_rowto submit a header row. Names are pulled fromImGui.table_setup_columndata.
- Optionally call
-
- Populate contents:
- In most situations you can use
ImGui.table_next_row+ImGui.table_set_column_index(N) to start appending into a column. - If you are using tables as a sort of grid, where every columns is holding the same type of contents,
you may prefer using
ImGui.table_next_columninstead ofImGui.table_next_row+ImGui.table_set_column_index.ImGui.table_next_columnwill automatically wrap-around into the next row if needed. -
Important
Comparatively to the old
ImGui.columnsAPI, we need to callImGui.table_next_columnfor the first column! - Summary of possible call flow:
ImGui.table_next_row->ImGui.table_set_column_index(0) ->ImGui.text("Hello 0") ->ImGui.table_set_column_index(1) ->ImGui.text("Hello 1") // OKImGui.table_next_row->ImGui.table_next_column->ImGui.text("Hello 0") ->ImGui.table_next_column->ImGui.text("Hello 1") // OKImGui.table_next_column->ImGui.text("Hello 0") ->ImGui.table_next_column->ImGui.text("Hello 1") // OK:ImGui.table_next_columnautomatically gets to next row!ImGui.table_next_row->ImGui.text("Hello 0") // Not OK! MissingImGui.table_set_column_indexorImGui.table_next_column!ImGui.textwill not appear! -
- Call
ImGui.end_table
- Call
.begin_table(str_id : String, column : Int32, flags : ImGuiTableFlags = ImGuiTableFlags.new(0), outer_size : ImVec2 = ImVec2.new(0.0, 0.0), inner_width : Float32 = 0.0) : Bool#
only call ImGui.end_table if ImGui.begin_table returns true!
.table_next_row(row_flags : ImGuiTableRowFlags = ImGuiTableRowFlags.new(0), min_row_height : Float32 = 0.0) : Void#
append into the first cell of a new row.
append into the next column (or first column of next row if currently in last column). Return true when column is visible.
append into the specified column. Return true when column is visible.
Tables: Headers & ImGui.columns declaration#
- Use
ImGui.table_setup_columnto specify label, resizing policy, default width/weight, id, various other flags etc. - Use
ImGui.table_headers_rowto create a header row and automatically submit aImGui.table_headerfor each column. Headers are required to perform: reordering, sorting, and opening the context menu. The context menu can also be made available in columns body using ImGuiTableFlags_ContextMenuInBody. - You may manually submit headers using
ImGui.table_next_row+ImGui.table_headercalls, but this is only useful in some advanced use cases (e.g. adding custom widgets in header row). - Use
ImGui.table_setup_scroll_freezeto lock columns/rows so they stay visible when scrolled.
.table_setup_column(label : String, flags : ImGuiTableColumnFlags = ImGuiTableColumnFlags.new(0), init_width_or_weight : Float32 = 0.0, user_id : ImGuiID = 0) : Void#
lock columns/rows so they stay visible when scrolled.
submit all headers cells based on data provided to ImGui.table_setup_column + submit context menu
submit one header cell manually (rarely used)
Tables: Sorting & Miscellaneous functions#
- Sorting: call
ImGui.table_get_sort_specsto retrieve latest sort specs for the table. NULL when not sorting. When 'sort_specs->SpecsDirty == true' you should sort your data. It will be true when sorting specs have changed since last call, or the first time. Make sure to set 'SpecsDirty = false' after sorting, else you may wastefully sort your data every frame! - Functions args 'int column_n' treat the default value of -1 as the same as passing the current column index.
get latest sort specs for the table (NULL if not sorting). Lifetime: don't hold on this pointer over multiple frames or past any subsequent call to ImGui.begin_table.
return number of columns (value passed to ImGui.begin_table)
return current column index.
return current row index.
return "" if column didn't have a name declared by ImGui.table_setup_column. Pass -1 to use current column.
return column flags so you can query their Enabled/Visible/Sorted/Hovered status flags. Pass -1 to use current column.
.table_set_bg_color(target : ImGuiTableBgTarget, color : UInt32, column_n : Int32 = -1) : Void#
change the color of a cell, row, or column. See ImGui::ImGuiTableBgTarget flags for details.
Legacy ImGui.columns API (prefer using Tables!)#
- You can also use
ImGui.same_line(pos_x) to mimic simplified columns.
next column, defaults to current row or next row if the current row is finished
get current column index
get column width (in pixels). pass -1 to use current column
set column width (in pixels). pass -1 to use current column
get position of column line (in pixels, from the left side of the contents region). pass -1 to use current column, otherwise 0..ImGui.get_columns_count inclusive. column 0 is typically 0.0f
set position of column line (in pixels, from the left side of the contents region). pass -1 to use current column
Tab Bars, Tabs#
.begin_tab_bar(str_id : String, flags : ImGuiTabBarFlags = ImGuiTabBarFlags.new(0)) : Bool#
create and append into a TabBar
only call ImGui.end_tab_bar if ImGui.begin_tab_bar returns true!
.begin_tab_item(label : String, p_open : Pointer(Bool) = Pointer(Bool).null, flags : ImGuiTabItemFlags = ImGuiTabItemFlags.new(0)) : Bool#
create a Tab. Returns true if the Tab is selected.
only call ImGui.end_tab_item if ImGui.begin_tab_item returns true!
.tab_item_button(label : String, flags : ImGuiTabItemFlags = ImGuiTabItemFlags.new(0)) : Bool#
create a Tab behaving like a button. return true when clicked. cannot be selected in the tab bar.
notify TabBar or Docking system of a closed tab/window ahead (useful to reduce visual flicker on reorderable tab bars). For tab-bar: call after ImGui.begin_tab_bar and before Tab submissions. Otherwise call with a window name.
Logging/Capture#
- All text output from the interface can be captured into tty/file/clipboard. By default, tree nodes are automatically opened during logging.
start logging to tty (stdout)
start logging to file
start logging to OS clipboard
stop logging (close file, etc.)
helper to display buttons for logging to tty/file/clipboard
pass text data straight to log (without being displayed)
Drag and Drop#
- On source items, call
ImGui.begin_drag_drop_source, if it returns true also callImGui.set_drag_drop_payload+ImGui.end_drag_drop_source. - On target candidates, call
ImGui.begin_drag_drop_target, if it returns true also callImGui.accept_drag_drop_payload+ImGui.end_drag_drop_target. - If you stop calling
ImGui.begin_drag_drop_sourcethe payload is preserved however it won't have a preview tooltip (we currently display a fallback "..." tooltip, see #1725) - An item can be both drag source and drop target.
call after submitting an item which may be dragged. when this return true, you can call ImGui.set_drag_drop_payload + ImGui.end_drag_drop_source
.set_drag_drop_payload(type : String, data : Pointer(Void), sz : LibC::SizeT, cond : ImGuiCond = ImGuiCond.new(0)) : Bool#
type is a user defined string of maximum 32 characters. Strings starting with '_' are reserved for dear imgui internal types. Data is copied and held by imgui. Return true when payload has been accepted.
only call ImGui.end_drag_drop_source if ImGui.begin_drag_drop_source returns true!
call after submitting an item that may receive a payload. If this returns true, you can call ImGui.accept_drag_drop_payload + ImGui.end_drag_drop_target
.accept_drag_drop_payload(type : String, flags : ImGuiDragDropFlags = ImGuiDragDropFlags.new(0)) : ImGuiPayload?#
accept contents of a given type. If ImGuiDragDropFlags_AcceptBeforeDelivery is set you can peek into the payload before the mouse button is released.
only call ImGui.end_drag_drop_target if ImGui.begin_drag_drop_target returns true!
peek directly into the current payload from anywhere. may return NULL. use ImGui::ImGuiPayload::IsDataType() to test for the payload type.
Disabling [BETA API]#
- Disable all user interactions and dim items visuals (applying style.DisabledAlpha over current colors)
- Those can be nested but it cannot be used to enable an already disabled section (a single
ImGui.begin_disabled(true) in the stack is enough to keep everything disabled) ImGui.begin_disabled(false) essentially does nothing useful but is provided to facilitate use of boolean expressions. If you can avoid callingImGui.begin_disabled(False)/ImGui.end_disabledbest to avoid it.
Clipping#
- Mouse hovering is affected by
ImGui.push_clip_rectcalls, unlike direct calls toImGui::ImDrawList::ImGui.push_clip_rectwhich are render only.
.push_clip_rect(clip_rect_min : ImVec2, clip_rect_max : ImVec2, intersect_with_current_clip_rect : Bool) : Void#
Focus, Activation#
- Prefer using "
ImGui.set_item_default_focus" over "if (ImGui.is_window_appearing)ImGui.set_scroll_here_y" when applicable to signify "this is the default item"
make last item the default focused item of a window.
focus keyboard on the next widget. Use positive 'offset' to access sub components of a multiple component widget. Use -1 to access previous widget.
Item/Widgets Utilities and Query Functions#
- Most of the functions are referring to the previous Item that has been submitted.
- See Demo Window under "Widgets->Querying Status" for an interactive visualization of most of those functions.
is the last item hovered? (and usable, aka not blocked by a popup, etc.). See ImGui::ImGuiHoveredFlags for more options.
is the last item active? (e.g. button being held, text field being edited. This will continuously return true while holding mouse button on an item. Items that don't interact will always return false)
is the last item focused for keyboard/gamepad navigation?
is the last item hovered and mouse clicked on? () == ImGui.is_mouse_clicked(mouse_button) && ImGui.is_item_hoveredImportant. () this it NOT equivalent to the behavior of e.g. ImGui.button. Read comments in function definition.
is the last item visible? (items may be out of sight because of clipping/scrolling)
did the last item modify its underlying value this frame? or was pressed? This is generally the same as the "bool" return value of many widgets.
was the last item just made active (item was previously inactive).
was the last item just made inactive (item was previously active). Useful for Undo/Redo patterns with widgets that requires continuous editing.
was the last item just made inactive and made a value change when it was active? (e.g. Slider/Drag moved). Useful for Undo/Redo patterns with widgets that requires continuous editing. Note that you may get false positives (some widgets such as Combo()/ListBox()/Selectable() will return true even when clicking an already selected item).
was the last item open state toggled? set by TreeNode().
is any item hovered?
is any item active?
is any item focused?
get upper-left bounding rectangle of the last item (screen space)
get lower-right bounding rectangle of the last item (screen space)
get size of last item
allow last item to be overlapped by a subsequent item. sometimes useful with invisible buttons, selectables, etc. to catch unused area.
Viewports#
- Currently represents the Platform Window created by the application which is hosting our Dear ImGui windows.
- In 'docking' branch with multi-viewport enabled, we extend this concept to have multiple active viewports.
- In the future we will extend this concept further to also represent Platform Monitor and support a "no main platform window" operation mode.
return primary/default viewport. This can never be NULL.
Background/Foreground Draw Lists#
this draw list will be the first rendered one. Useful to quickly draw shapes/text behind dear imgui contents.
this draw list will be the last rendered one. Useful to quickly draw shapes/text over dear imgui contents.
Miscellaneous Utilities#
test if rectangle (of given size, starting from cursor position) is visible / not clipped.
test if rectangle (in screen space) is visible / not clipped. to perform coarse clipping on user's side.
get global imgui time. incremented by io.DeltaTime every frame.
get global imgui frame count. incremented by 1 every frame.
you may use this when creating your own ImGui::ImDrawList instances.
get a string corresponding to the enum value (for display, saving, etc.).
replace current window storage with our own (if you want to manipulate it yourself, typically clear subsection of it)
.begin_child_frame(id : ImGuiID, size : ImVec2, flags : ImGuiWindowFlags = ImGuiWindowFlags.new(0)) : Bool#
helper to create a child window / scrolling region that looks like a normal widget frame
always call ImGui.end_child_frame regardless of ImGui.begin_child_frame return values (which indicates a collapsed/clipped window)
ImGui.text Utilities#
.calc_text_size(text : Bytes | String, hide_text_after_double_hash : Bool = false, wrap_width : Float32 = -1.0) : ImGui::ImVec2#
Color Utilities#
.color_convert_rgb_to_hsv(r : Float32, g : Float32, b : Float32) : Tuple(LibC::Float, LibC::Float, LibC::Float)#
.color_convert_hsv_to_rgb(h : Float32, s : Float32, v : Float32) : Tuple(LibC::Float, LibC::Float, LibC::Float)#
Inputs Utilities: Keyboard#
Without IMGUI_DISABLE_OBSOLETE_KEYIO: (legacy support)
- For '[`ImGui::ImGuiKey`][] key' you can still use your legacy native/user indices according to how your backend/engine stored them in io.KeysDown[].
With IMGUI_DISABLE_OBSOLETE_KEYIO: (this is the way forward)
- Any use of '[`ImGui::ImGuiKey`][]' will assert when key < 512 will be passed, previously reserved as native/user keys indices
- [`ImGui.get_key_index`][] is pass-through and therefore deprecated (gone if IMGUI_DISABLE_OBSOLETE_KEYIO is defined)
is key being held.
was key pressed (went from !Down to Down)? if repeat=true, uses io.KeyRepeatDelay / KeyRepeatRate
was key released (went from Down to !Down)?
.get_key_pressed_amount(key : ImGuiKey, repeat_delay : Float32, rate : Float32) : Int32#
uses provided repeat rate/delay. return a count, most often 0 or 1 but might be >1 if RepeatRate is small enough that DeltaTime > RepeatRate
[DEBUG] returns English name of the key. Those names a provided for debugging purpose and are not meant to be saved persistently not compared.
Override io.WantCaptureKeyboard flag next frame (said flag is left for your application to handle, typically when true it instructs your app to ignore inputs). e.g. force capture keyboard when your widget is being hovered. This is equivalent to setting "io.WantCaptureKeyboard = want_capture_keyboard"; after the next ImGui.new_frame call.
Inputs Utilities: Mouse#
- To refer to a mouse button, you may use named enums in your code e.g. ImGuiMouseButton_Left, ImGuiMouseButton_Right.
- You can also use regular integer: it is forever guaranteed that 0=Left, 1=Right, 2=Middle.
- Dragging operations are only reported after mouse has moved a certain distance away from the initial clicking position (see 'lock_threshold' and 'io.MouseDraggingThreshold')
is mouse button held?
did mouse button clicked? (went from !Down to Down). Same as ImGui.get_mouse_clicked_count == 1.
did mouse button released? (went from Down to !Down)
did mouse button double-clicked? Same as ImGui.get_mouse_clicked_count == 2. (note that a double-click will also report ImGui.is_mouse_clicked == true)
return the number of successive mouse-clicks at the time where a click happen (otherwise 0).
by convention we use (-FLT_MAX,-FLT_MAX) to denote that there is no mouse available
[WILL OBSOLETE] is any mouse button held? This was designed for backends, but prefer having backend maintain a mask of held mouse buttons, because upcoming input queue system will make this invalid.
shortcut to ImGui.get_io.MousePos provided by user, to be consistent with other calls
retrieve mouse position at the time of opening popup we have ImGui.begin_popup into (helper to avoid user backing that value themselves)
is mouse dragging? (if lock_threshold < -1.0f, uses io.MouseDraggingThreshold)
.get_mouse_drag_delta(button : ImGuiMouseButton = ImGuiMouseButton.new(0), lock_threshold : Float32 = -1.0) : ImGui::ImVec2#
return the delta from the initial clicking position while the mouse button is pressed or was just released. This is locked and return 0.0f until the mouse moves past a distance threshold at least once (if lock_threshold < -1.0f, uses io.MouseDraggingThreshold)
get desired cursor type, reset in ImGui.new_frame, this is updated during the frame. valid before ImGui.render. If you use software rendering by setting io.MouseDrawCursor ImGui will render those for you
set desired cursor type
Override io.WantCaptureMouse flag next frame (said flag is left for your application to handle, typical when true it instucts your app to ignore inputs). This is equivalent to setting "io.WantCaptureMouse = want_capture_mouse;" after the next ImGui.new_frame call.
Clipboard Utilities#
- Also see the
ImGui.log_to_clipboardfunction to capture GUI into clipboard, or easily output text data to the clipboard.
Settings/.Ini Utilities
- The disk functions are automatically called if io.IniFilename != NULL (default is "imgui.ini").
- Set io.IniFilename to NULL to load/save manually. Read io.WantSaveIniSettings description about handling .ini saving manually.
- Important: default value "imgui.ini" is relative to current working dir! Most apps will want to lock this to an absolute path (e.g. same path as executables).
call after ImGui.create_context and before the first call to ImGui.new_frame. ImGui.new_frame automatically calls ImGui.load_ini_settings_from_disk(io.IniFilename).
call after ImGui.create_context and before the first call to ImGui.new_frame to provide .ini data from your own data source.
this is automatically called (if io.IniFilename is not empty) a few seconds after any modification that should be reflected in the .ini file (and also by ImGui.destroy_context).
return a zero-terminated string with the .ini data which you can save by your own mean. call when io.WantSaveIniSettings is set, then save data by your own mean and clear io.WantSaveIniSettings.
Debug Utilities#
.debug_check_version_and_data_layout(version_str : String, sz_io : LibC::SizeT, sz_style : LibC::SizeT, sz_vec2 : LibC::SizeT, sz_vec4 : LibC::SizeT, sz_drawvert : LibC::SizeT, sz_drawidx : LibC::SizeT) : Bool#
This is called by IMGUI_CHECKVERSION() macro.
Memory Allocators#
- Those functions are not reliant on the current context.
- DLL users: heaps and globals are not shared across DLL boundaries! You will need to call
ImGui.set_current_context+ImGui.set_allocator_functionsfor each static/DLL boundary you are calling from. Read "Context and Memory Allocators" section of imgui.cpp for more details.
.set_allocator_functions(alloc_func : ImGuiMemAllocFunc, free_func : ImGuiMemFreeFunc, user_data : Pointer(Void) = Pointer(Void).null) : Void#
.get_allocator_functions(p_alloc_func : Pointer(ImGuiMemAllocFunc), p_free_func : Pointer(ImGuiMemFreeFunc), p_user_data : Pointer(Pointer(Void))) : Void#
namespace ImGui