Dear ImGui: Difference between revisions

From GiderosMobile
wip
DONE
 
(17 intermediate revisions by the same user not shown)
Line 7: Line 7:
This is an implementation of the '''Dear ImGui''' library: '''https://github.com/ocornut/imgui'''.
This is an implementation of the '''Dear ImGui''' library: '''https://github.com/ocornut/imgui'''.


To use Dear ImGui in your project you need to add the ImGui plugin and call require like so:
Dear ImGui is licensed under the '''MIT License''', see '''https://github.com/ocornut/imgui/blob/master/LICENSE.txt''' for more information.
 
To use Dear ImGui in your project you need to add the ImGui plugin and call ''require'' like so:
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
require "ImGui"
require "ImGui"
Line 14: Line 16:
Current Gideros Dear ImGui version: '''1.89.6'''.
Current Gideros Dear ImGui version: '''1.89.6'''.


See introduction documentation here: https://pixtur.github.io/mkdocs-for-imgui/site/
=== User Guide ===
 
* Double-click on title bar to collapse window
and the full Dear ImGui demo here: https://pthom.github.io/imgui_manual_online/manual/imgui_manual.html
* Click and drag on lower corner to resize window (double-click to auto fit window to its contents)
 
* CTRL+Click on a slider or drag box to input value as text
= Dear ImGui =
* TAB/SHIFT+TAB to cycle through keyboard editable fields
Dear ImGui is a '''bloat-free graphical user interface library for C++'''. It outputs optimized vertex buffers that you can render anytime in your 3D-pipeline-enabled application. It is fast, portable, renderer agnostic, and self-contained (no external dependencies).
* CTRL+Tab to select a window
 
* CTRL+Mouse Wheel to zoom window contents if ''io.FontAllowUserScaling'' is enabled
Dear ImGui is designed to '''enable fast iterations''' and to '''empower programmers''' to create '''content creation tools and visualization / debug tools''' (as opposed to UI for the average end-user). It favors simplicity and productivity toward this goal and lacks certain features commonly found in more high-level libraries. Among other things, full internationalization (right-to-left text, bidirectional text, text shaping etc.) and accessibility features are not supported.
* While inputing text:
 
** CTRL+Left/Right to word jump
Dear ImGui is particularly suited to integration in game engines (for tooling), real-time 3D applications, fullscreen applications, embedded applications, or any applications on console platforms where operating system features are non-standard.
** CTRL+A or double-click to select all
 
** CTRL+X/C/V to use clipboard cut/copy/paste
Code sample (Lua):
** CTRL+Z,CTRL+Y to undo/redo
<syntaxhighlight lang="lua">
** ESCAPE to revert
imgui:text("Hello World!")
* With keyboard navigation enabled:
if imgui:button("button 01", 64, 16) then
** Arrow keys to navigate
print("button 01 clicked")
** Space to activate a widget
end
** Return to input text into a widget
text, isChanged = imgui:inputText("text", text, 128, 0)
** Escape to deactivate a widget, close popup, exit child window
value, isChanged = imgui:sliderFloat("slider", value, 0, 30, "%.3f", 0)
** Alt to jump to the menu layer of a window
</syntaxhighlight>


== License ==
==== Widgets ====
Dear ImGui is licensed under the '''MIT License''', see https://github.com/ocornut/imgui/blob/master/LICENSE.txt for more information.
'''Widgets: Color Editor/Picker'''
 
== Widgets ==
'''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
  * 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


'''Widgets: Input with Keyboard'''
'''Widgets: Input with Keyboard'''
  * If you want to use InputText() with std::string or any custom dynamic string type, see misc/cpp/imgui_stdlib.h and comments in imgui_demo.cpp.
  * If you want to use InputText() with std::string or any custom dynamic string type, see misc/cpp/imgui_stdlib.h and comments in imgui_demo.cpp.
  * Most of the ImGuiInputTextFlags flags are only useful for InputText() and not for InputFloatX, InputIntX, InputDouble etc.
  * Most of the ImGuiInputTextFlags flags are only useful for InputText() and not for InputFloatX, InputIntX, InputDouble etc.


'''Widgets: Regular Sliders'''
'''Widgets: Regular Sliders'''
  * CTRL+Click on any slider to turn them into an input box. Manually input values aren't clamped and can go off-bounds.
  * CTRL+Click on any slider to turn them into an input box. Manually input values aren't clamped and can go off-bounds.
  * 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.
  * 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.
Line 53: Line 51:
  If you get a warning converting a float to ImGuiSliderFlags, read https://github.com/ocornut/imgui/issues/3361
  If you get a warning converting a float to ImGuiSliderFlags, read https://github.com/ocornut/imgui/issues/3361


'''Widgets: Drag Sliders'''
'''Widgets: Drag Sliders'''
  * CTRL+Click on any drag box to turn them into an input box. Manually input values aren't clamped and can go off-bounds.
  * CTRL+Click on any drag box to turn them into an input box. Manually input values aren't clamped and can go off-bounds.
  * 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
  * 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
Line 63: Line 61:
  * 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.
  * 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.


 
=== Gideros Dear ImGui Documentation ===
----
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
*'''[[Dear ImGui FAQ]]'''
*'''[[Dear ImGui FAQ]]'''
Line 71: Line 68:
*'''[[Dear ImGui Enums]]'''
*'''[[Dear ImGui Enums]]'''
*'''[[Dear ImGui Flags]]'''
*'''[[Dear ImGui Flags]]'''
*'''[[ImGui_Examples|Dear ImGui Examples]]'''
*'''[[Dear ImGui Examples]]'''
</div>
 
===== '''OLD DOC TO BE MERGED SOMEHOW''' =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
'''[[ImGui|ImGui.Core (ImGui)]]'''<br/><!--GIDEROSOBJ:ImGui-->
'''[[ImGui.DrawList]]'''<br/><!--GIDEROSOBJ:ImGui.DrawList-->
'''[[ImGui.Style]]'''<br/><!--GIDEROSOBJ:ImGui.Style-->
</div>
</div>


<!--introduction documentation (c++): https://pixtur.github.io/mkdocs-for-imgui/site/-->
<!--Dear ImGui demo (c++): https://pthom.github.io/imgui_manual_online/manual/imgui_manual.html-->
<!--=== Methods ===-->
<!--=== Methods ===-->
<!--GIDEROSMTD:ImGui.new() initializes ImGui-->
<!--GIDEROSMTD:ImGui.new([font_atlas = nil, mouse_listeners = true, keyboard_listeners = true, touch_listeners = false]) initializes ImGui-->
<!--GIDEROSMTD:ImGui:arrowButton(stringID, direction) displays an ImGui arrow button-->
<!--GIDEROSMTD:ImGui:showLog(title, p_open [, ImGui.WindowFlags = 0]) draw log window, p_open = ImGui:showLog(...)-->
<!--GIDEROSMTD:ImGui:beginDisabled(disabledFlag) starts a stack that can be disabled-->
<!--GIDEROSMTD:ImGui:ImGui:writeLog(text)-->
<!--GIDEROSMTD:ImGui:beginWindow(name, p_open, flags) pushes a Window to the stack and starts appending to it-->
<!--GIDEROSMTD:ImGui:setTouchGesturesEnabled(bool)-->
<!--GIDEROSMTD:ImGui
<!--GIDEROSMTD:ImGui:isTouchGesturesEnabled() bool = ImGui:isTouchGesturesEnabled()-->
<!--GIDEROSMTD:Imgui:getIO() local IO = Imgui:getIO()-->
<!--GIDEROSMTD:IO:getFonts() local FontAtlas = IO:getFonts()-->
<!--GIDEROSMTD:FontAtlas:addFont(ttf_font_path, font_size [, options]) local Font = FontAtlas:addFont(...)-->
<!--GIDEROSMTD:FontAtlas:addFonts(fontsDescription)-->
<!--GIDEROSMTD:FontAtlas:getFont([index]) local Font = FontAtlas:getFont(...) gets font by index (if index is 0 or nil get default font instance)-->
<!--GIDEROSMTD:FontAtlas:build() call after multiple FontAtlas:addFont(...) calls to update ImGui font atlas-->
<!--GIDEROSMTD:FontAtlas:clearInputData()-->
<!--GIDEROSMTD:FontAtlas:clearTexData()-->
<!--GIDEROSMTD:FontAtlas:clearFonts()-->
<!--GIDEROSMTD:FontAtlas:clear()-->
<!--GIDEROSMTD:FontAtlas:getFonts() table = FontAtlas:getFonts() returns a table with all fonts (included default)-->
<!--GIDEROSMTD:FontAtlas:isBuilt() flag = FontAtlas:isBuilt()-->
<!--GIDEROSMTD:FontAtlas:addCustomRectRegular(width, height) number = FontAtlas:addCustomRectRegular(...)-->
<!--GIDEROSMTD:FontAtlas:addCustomRectFontGlyph(font, id, width, height, advance_x [, offset_x, offset_y]) number = FontAtlas:addCustomRectFontGlyph(...)-->
<!--GIDEROSMTD:FontAtlas:getCustomRectByIndex(index) w, h, x, y, glyph_id, offset_x, offset_y, font, is_packed_flag = FontAtlas:getCustomRectByIndex(...)-->
<!--GIDEROSMTD:ImGui:pushFont(font) font (table): object returned by FontAtlas:addFont(...) or FontAtlas:getFont([index])-->
<!--GIDEROSMTD:ImGui:popFont()-->
<!--GIDEROSMTD:Font:getSize() number = Font:getSize()-->
<!--GIDEROSMTD:Font:getContainerAtlas() FontAtlas = Font:getContainerAtlas()-->
<!--GIDEROSMTD:Font:setScale(number)-->
<!--GIDEROSMTD:Font:getScale() number = Font:getScale()-->
<!--GIDEROSMTD:Font:getAscent() number = Font:getAscent()-->
<!--GIDEROSMTD:Font:getDescent() number = Font:getDescent()-->
<!--GIDEROSMTD:Font:isLoaded() bool = Font:isLoaded()-->
<!--GIDEROSMTD:Font:getDebugName() string = Font:getDebugName()-->
<!--
<!--=== Events ===-->
<!--=== Events ===-->
<!--GIDEROSEVT:ImGui.KeyChar-->
<!--GIDEROSEVT:ImGui.KeyChar-->
Line 193: Line 840:
<!--GIDEROSEVT:ImGui.MouseWheel-->
<!--GIDEROSEVT:ImGui.MouseWheel-->
<!--GIDEROSEVT:ImGui.TouchBegin-->
<!--GIDEROSEVT:ImGui.TouchBegin-->
<!--GIDEROSEVT:ImGui.TouchCancel-->
<!--GIDEROSEVT:ImGui.TouchEnd-->
<!--GIDEROSEVT:ImGui.TouchEnd-->
<!--GIDEROSEVT:ImGui.TouchCancel-->
<!--GIDEROSEVT:ImGui.TouchMove-->
<!--GIDEROSEVT:ImGui.TouchMove-->
<!--=== Constants ===-->
<!--=== Constants ===-->
Line 329: Line 976:
<!--GIDEROSCST:ImGui.Dir_Left-->
<!--GIDEROSCST:ImGui.Dir_Left-->
<!--GIDEROSCST:ImGui.Dir_Right-->
<!--GIDEROSCST:ImGui.Dir_Right-->
<!--GIDEROSCST:ImGui.Dir_Up -->
<!--GIDEROSCST:ImGui.Dir_Up-->
<!--GIDEROSCST:ImGui.DragDropFlags_None-->
<!--GIDEROSCST:ImGui.DragDropFlags_None-->
<!--GIDEROSCST:ImGui.DragDropFlags_AcceptBeforeDelivery-->
<!--GIDEROSCST:ImGui.DragDropFlags_AcceptBeforeDelivery-->
Line 340: Line 987:
<!--GIDEROSCST:ImGui.DragDropFlags_SourceNoDisableHover-->
<!--GIDEROSCST:ImGui.DragDropFlags_SourceNoDisableHover-->
<!--GIDEROSCST:ImGui.DragDropFlags_SourceNoHoldToOpenOthers-->
<!--GIDEROSCST:ImGui.DragDropFlags_SourceNoHoldToOpenOthers-->
<!--GIDEROSCST:ImGui.DragDropFlags_SourceNoPreviewTooltip -->
<!--GIDEROSCST:ImGui.DragDropFlags_SourceNoPreviewTooltip-->
<!--GIDEROSCST:ImGui.FocusedFlags_None-->
<!--GIDEROSCST:ImGui.FocusedFlags_None-->
<!--GIDEROSCST:ImGui.FocusedFlags_AnyWindow-->
<!--GIDEROSCST:ImGui.FocusedFlags_AnyWindow-->
Line 586: Line 1,233:
<!--GIDEROSCST:ImGui.TE_Punctuation-->
<!--GIDEROSCST:ImGui.TE_Punctuation-->
<!--GIDEROSCST:ImGui.TE_Selection-->
<!--GIDEROSCST:ImGui.TE_Selection-->
<!--GIDEROSCST:ImGui.TE_String -->
<!--GIDEROSCST:ImGui.TE_String-->
<!--GIDEROSCST:ImGui.TreeNodeFlags_None-->
<!--GIDEROSCST:ImGui.TreeNodeFlags_None-->
<!--GIDEROSCST:ImGui.TreeNodeFlags_AllowItemOverlap-->
<!--GIDEROSCST:ImGui.TreeNodeFlags_AllowItemOverlap-->
Line 602: Line 1,249:
<!--GIDEROSCST:ImGui.TreeNodeFlags_Selected-->
<!--GIDEROSCST:ImGui.TreeNodeFlags_Selected-->
<!--GIDEROSCST:ImGui.TreeNodeFlags_SpanAvailWidth-->
<!--GIDEROSCST:ImGui.TreeNodeFlags_SpanAvailWidth-->
<!--GIDEROSCST:ImGui.TreeNodeFlags_SpanFullWidth -->
<!--GIDEROSCST:ImGui.TreeNodeFlags_SpanFullWidth-->
<!--GIDEROSCST:ImGui.WindowFlags_None-->
<!--GIDEROSCST:ImGui.WindowFlags_None-->
<!--GIDEROSCST:ImGui.WindowFlags_AlwaysAutoResize-->
<!--GIDEROSCST:ImGui.WindowFlags_AlwaysAutoResize-->
Line 627: Line 1,274:
<!--GIDEROSCST:ImGui.WindowFlags_NoScrollWithMouse-->
<!--GIDEROSCST:ImGui.WindowFlags_NoScrollWithMouse-->
<!--GIDEROSCST:ImGui.WindowFlags_NoTitleBar-->
<!--GIDEROSCST:ImGui.WindowFlags_NoTitleBar-->
<!--GIDEROSCST:ImGui.WindowFlags_UnsavedDocument -->
<!--GIDEROSCST:ImGui.WindowFlags_UnsavedDocument-->


{{GIDEROS IMPORTANT LINKS}}
{{GIDEROS IMPORTANT LINKS}}

Latest revision as of 00:46, 11 October 2024

Supported platforms:
Available since: Gideros 2020.9

Description

This is an implementation of the Dear ImGui library: https://github.com/ocornut/imgui.

Dear ImGui is licensed under the MIT License, see https://github.com/ocornut/imgui/blob/master/LICENSE.txt for more information.

To use Dear ImGui in your project you need to add the ImGui plugin and call require like so:

require "ImGui"

Current Gideros Dear ImGui version: 1.89.6.

User Guide

  • Double-click on title bar to collapse window
  • Click and drag on lower corner to resize window (double-click to auto fit window to its contents)
  • CTRL+Click on a slider or drag box to input value as text
  • TAB/SHIFT+TAB to cycle through keyboard editable fields
  • CTRL+Tab to select a window
  • CTRL+Mouse Wheel to zoom window contents if io.FontAllowUserScaling is enabled
  • While inputing text:
    • CTRL+Left/Right to word jump
    • CTRL+A or double-click to select all
    • CTRL+X/C/V to use clipboard cut/copy/paste
    • CTRL+Z,CTRL+Y to undo/redo
    • ESCAPE to revert
  • With keyboard navigation enabled:
    • Arrow keys to navigate
    • Space to activate a widget
    • Return to input text into a widget
    • Escape to deactivate a widget, close popup, exit child window
    • Alt to jump to the menu layer of a window

Widgets

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

Widgets: Input with Keyboard

* If you want to use InputText() with std::string or any custom dynamic string type, see misc/cpp/imgui_stdlib.h and comments in imgui_demo.cpp.
* Most of the ImGuiInputTextFlags flags are only useful for InputText() and not for InputFloatX, InputIntX, InputDouble etc.

Widgets: Regular Sliders

* CTRL+Click on any slider to turn them into an input box. Manually input values aren't clamped and can go off-bounds.
* 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").

If you get a warning converting a float to ImGuiSliderFlags, read https://github.com/ocornut/imgui/issues/3361

Widgets: Drag Sliders

* CTRL+Click on any drag box to turn them into an input box. Manually input values aren't clamped and can go off-bounds.
* 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.
* 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.

Gideros Dear ImGui Documentation