Dear ImGui: Difference between revisions

From GiderosMobile
wip
DONE
 
(11 intermediate revisions by the same user not shown)
Line 9: Line 9:
Dear ImGui is licensed under the '''MIT License''', see '''https://github.com/ocornut/imgui/blob/master/LICENSE.txt''' for more information.
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:
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 37: Line 37:


==== Widgets ====
==== Widgets ====
'''Widgets: Color Editor/Picker'''
'''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 51: 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 71: Line 71:
</div>
</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>
<!--introduction documentation (c++): https://pixtur.github.io/mkdocs-for-imgui/site/-->
<!--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-->
<!--Dear ImGui demo (c++): https://pthom.github.io/imgui_manual_online/manual/imgui_manual.html-->
Line 222: Line 216:
<!--GIDEROSMTD:ImGui.colorConvertHEXtoHSV(hex) h, s, v = ImGui.colorConvertHEXtoHSV(hex)-->
<!--GIDEROSMTD:ImGui.colorConvertHEXtoHSV(hex) h, s, v = ImGui.colorConvertHEXtoHSV(hex)-->
<!--GIDEROSMTD:ImGui.colorConvertHSVtoHEX(h, s, v) hex = ImGui.colorConvertHSVtoHEX(h, s, v)-->
<!--GIDEROSMTD:ImGui.colorConvertHSVtoHEX(h, s, v) hex = ImGui.colorConvertHSVtoHEX(h, s, v)-->
<!--GIDEROSMTD:ImGui:getIO() local IO = ImGui:getIO()-->
<!--GIDEROSMTD:IO:setFontDefault(font)-->
<!--GIDEROSMTD:IO:setFontDefault(font)-->
<!--GIDEROSMTD:IO:getConfigFlags() local ImGuiConfigFlag = IO:getConfigFlags()-->
<!--GIDEROSMTD:IO:getConfigFlags() local ImGuiConfigFlag = IO:getConfigFlags()-->
Line 309: Line 293:
<!--GIDEROSMTD:IO:addMouseWheelEvent(x, y)-->
<!--GIDEROSMTD:IO:addMouseWheelEvent(x, y)-->
<!--GIDEROSMTD:IO:setAppAcceptingEvents([accepting_events = true])-->
<!--GIDEROSMTD:IO:setAppAcceptingEvents([accepting_events = true])-->
 
<!--GIDEROSMTD:ImGui:getHoveredWindow() string OR nil = ImGui:getHoveredWindow()-->
 
<!--GIDEROSMTD:ImGui:getHoveredWindowRoot() string OR nil = ImGui:getHoveredWindowRoot()-->
 
<!--GIDEROSMTD:ImGui:getHoveredWindowUnderMovingWindow() string OR nil = ImGui:getHoveredWindowUnderMovingWindow()-->
 
<!--GIDEROSMTD:ImGui:getMovingWindow() string OR nil = ImGui:getMovingWindow()-->
 
<!--GIDEROSMTD:ImGui:getActiveIdWindow() string OR nil = ImGui:getActiveIdWindow()-->
 
<!--GIDEROSMTD:ImGui:getActiveId() id = ImGui:getActiveId()-->
 
<!--GIDEROSMTD:ImGui:getActiveIdPreviousFrame() id = ImGui:getActiveIdPreviousFrame()-->
 
<!--GIDEROSMTD:ImGui:getActiveIdTimer() number = ImGui:getActiveIdTimer()-->
 
<!--GIDEROSMTD:ImGui:getActiveIdAllowOverlap() id = ImGui:getActiveIdAllowOverlap()-->
<!--GIDEROSMTD:imgui:getIO() IO = imgui:getIO()-->
<!--GIDEROSMTD:ImGui:getHoveredId() id = ImGui:getHoveredId()-->
<!--GIDEROSMTD:imgui:getIO() IO = imgui:getIO()-->
<!--GIDEROSMTD:ImGui:getHoveredIdPreviousFrame() id = ImGui:getHoveredIdPreviousFrame()-->
<!--GIDEROSMTD:imgui:getIO() IO = imgui:getIO()-->
<!--GIDEROSMTD:ImGui:getHoveredIdTimer() number = ImGui:getHoveredIdTimer()-->
<!--GIDEROSMTD:imgui:getIO() IO = imgui:getIO()-->
<!--GIDEROSMTD:ImGui:getHoveredIdAllowOverlap() id = ImGui:getHoveredIdAllowOverlap()-->
<!--GIDEROSMTD:imgui:getIO() IO = imgui:getIO()-->
<!--GIDEROSMTD:ImGui:getDragDropActive() bool = ImGui:getDragDropActive()-->
<!--
<!--GIDEROSMTD:ImGui:getDragDropPayloadSourceId() id = ImGui:getDragDropPayloadSourceId()-->
<!--GIDEROSMTD:ImGui:getDragDropPayloadDataType() string = ImGui:getDragDropPayloadDataType()-->
<!--GIDEROSMTD:ImGui:getDragDropPayloadDataSize() number = ImGui:getDragDropPayloadDataSize()-->
<!--GIDEROSMTD:ImGui:beginWindow(label, p_open [, ImGui.WindowFlags = 0]) p_open, draw = ImGui:beginWindow(...)-->
<!--GIDEROSMTD:ImGui:beginWindow(label, nil [, ImGui.WindowFlags = 0]) draw = ImGui:beginWindow(...), do not show "X" button-->
<!--GIDEROSMTD:ImGui:beginFullScreenWindow(label, p_open [, ImGui.WindowFlags = 0]) p_open, draw = ImGui:beginFullScreenWindow(...), start a window with no borders, no paddings, no rounding and ImGui.WindowFlags_Fullscreen flag-->
<!--GIDEROSMTD:ImGui:beginFullScreenWindow(label, nil [,
<!--=== Events ===-->
<!--=== Events ===-->
<!--GIDEROSEVT:ImGui.KeyChar-->
<!--GIDEROSEVT:ImGui.KeyChar-->
Line 442: 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 578: 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 589: 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 835: 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 851: 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 876: 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