Release v1.60 · ocornut/imgui

v1.60: Gamepad/Keyboard Navigation, Context Creation and a hundred other changes

See https://github.com/ocornut/imgui for the project homepage.
See https://github.com/ocornut/imgui/releases for earlier release notes.
See https://github.com/ocornut/imgui/wiki for language/framework bindings, links, 3rd parties helpers/extensions.
Scroll below for a gallery of screenshots.

Foreword

Hello 2018!

It looks like I held on too long again, and 1.60 is crammed with changes! If you have the patience and you are well acquainted with imgui, please try to read this Changelog. The information in there will be useful to you (either immediately, either in the future). I promise that 1.61 will have less changes!

The biggest change of this version is that I have merged the long pending Gamepad/Keyboard navigation branch. I had a first jab at Gamepad controls back in July 2016, under the initial impulse of Insomniac, and it ended up taking ten times the amount of time I first imagined it would take. It is finally merged in 1.60 as a Beta feature (needs to be explicitly enabled). I consider it unfinished but it's pretty usable especially on console systems with a gamepad. It will need more users and feedback to improve over time.

This release and ongoing work on dear imgui wouldn't have happened without everyone's monthly support on Patreon. Huge thanks to all of you, past and present patrons! It's been very helpful and meaningful to see this ongoing support, along with as the messages on twitter, e-mail, github.

Great news: Blizzard Entertainment has kindly committed to sponsor and support development of dear imgui, and has been for the past few months now. It will allow me to increasingly focus on dear imgui through the year, and lots of promising features will emerge from this sponsorship. Their wish list is mostly aligned with everyone's interest, with features like docking and multi-viewports (see a gif) but also hundreds of other improvements to the library, several of which already forming the bulk of this 1.60 release. Blizzard have been very supportive and understanding of the situation posed by the development of a shared free software and keeping an active community sane. Thank you Patrick, Marco, Van & others!

On the side, I've been trying to work to provide technical support for game studios using dear imgui. This has been helpful because I get feedback and user stories from different teams, each at different points in their project and adoption of imgui, and this feedback allows me to make better decisions when steering the ship.

Gamepad/Keyboard Navigation

With keyboard navigation you can use/activate most of dear imgui features from the keyboard:

ALT to access menus.
Arrow keys to move.
Space to activate buttons, tweak sliders/drag, tree node, enter into child nodes, etc.
Escape to close popups, exit a child window, clear selection.
Enter to input text.
CTRL-Tab (CTRL-Shift-Tab) to focus windows, etc.

Read Changelog below and imgui.cpp for details on how to enable it (io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard, io.ConfigFlags |= ImGuiConfigFlags_NavEnableGamepad)

Mapping for game controllers:

(Click to download PSD/PNG for all 3 major controllers)

Bonus link: a Emscripten+JavaScript+WebGL demo by @flyover, which supports gamepad navigation on the web: https://flyover.github.io/imgui-js/example (click Inputs, Navigation & Focus and enable gamepad there. Keyboard is conflicting a little too much with browser controls it seems?)

How to update

Note that this 1.60 update includes MANY things other than navigation, so even if you don't care for that feature, it is really recommended that you stay up to date.

Overwrite every file except imconfig.h (if you have modified it). Read the Breaking Changes section below, and the corresponding log in imgui.cpp. If you have a problem with a missing function/symbols, search for its name in the code, there will likely be a comment about it. Please report any issue to the GitHub page! (or on Twitter).

You can also enable IMGUI_DISABLE_OBSOLETE_FUNCTIONS in imconfig.h to forcefully disable legacy names and symbols. Doing it every once in a while is a good way to make sure you are not using obsolete stuff. Dear ImGui has resumed active development and API changes have a little more frequent lately. They are carefully documented and should not affect everyone. Keeping your copy of dear imgui updated is recommended!

Try to resist the temptation to modify imgui,cpp to not hinder your ability to update often and easily. When needed, you may include imgui_internal.h and implement functions in the ImGui namespace from the comfort of your own files. If you have or need modifications of imgui.cpp, by reaching out you may end up with suggestions for a workaround, or official support for a change.

Breaking Changes

The addition of ImGui::CreateContext() will affect everyone. Read below (or #1599 for more details).

Reorganized context handling to be more explicit: (#1599)
- YOU NOW NEED TO CALL ImGui::CreateContext() AT THE BEGINNING OF YOUR APP, AND CALL ImGui::DestroyContext() AT THE END.
- removed Shutdown() function, as DestroyContext() serve this purpose. If you are using an old back-end from the examples/ folder, remove the line that calls Shutdown().
- you may pass a ImFontAtlas* pointer to CreateContext() to share a font atlas between contexts. Otherwise CreateContext() will create its own font atlas instance.
- removed allocator parameters from CreateContext(), they are now setup with SetAllocatorFunctions(), and shared by all contexts.
- removed the default global context and font atlas instance, which made things more confusing for users of DLL reloading and users of multiple contexts.
Obsoleted the io.RenderDrawListsFn callback (will completely remove in a few versions), you can call your graphics engine render function after ImGui::Render(). e.g. with example back-ends, call ImDrawData* draw_data = ImGui::GetDrawData(); ImGui_ImplXXXX_RenderDrawData(draw_data).
Renamed ImGuiStyleVar_Count_ to ImGuiStyleVar_COUNT and ImGuiMouseCursor_Count_ to ImGuiMouseCursor_COUNT for consistency with other public enums.
Fonts: Moved sample TTF files from extra_fonts/ to misc/fonts/. If you loaded files directly from the imgui repo you may need to update your paths.
Fonts: changed ImFont::DisplayOffset.y to defaults to 0 instead of +1. Fixed vertical rounding of Ascent/Descent to match TrueType renderer. If you were adding or subtracting (not assigning) to ImFont::DisplayOffset check if your fonts are correctly aligned vertically. (#1619)
BeginDragDropSource(): temporarily removed the optional mouse_button=0 parameter because it is not really usable in many situations at the moment.
Obsoleted IsAnyWindowHovered() in favor of IsWindowHovered(ImGuiHoveredFlags_AnyWindow). Kept redirection function (will obsolete).
Obsoleted IsAnyWindowFocused() in favor of IsWindowFocused(ImGuiFocusedFlags_AnyWindow). Kept redirection function (will obsolete).
Renamed io.WantMoveMouse to io.WantSetMousePos for consistency and ease of understanding (was added in 1.52, not used by core, and honored by some binding ahead of merging the Nav branch).
Removed ImGuiCol_CloseButton, ImGuiCol_CloseButtonActive, ImGuiCol_CloseButtonHovered style colors as the closing cross uses regular button colors now.
Renamed ImGuiSizeConstraintCallback to ImGuiSizeCallback, ImGuiSizeConstraintCallbackData to ImGuiSizeCallbackData.
Removed CalcItemRectClosestPoint() which was weird and not really used by anyone except demo code. If you need it it's easy to replicate on your side.

All Changes

Doc: Added a Changelog.txt file in the repository to ease comparing versions (it goes back to dear imgui 1.48), until now it was only on GitHub.
Navigation: merged in the gamepad/keyboard navigation (about a million changes!). (#787, #323)
The initial focus was to support game controllers, but keyboard is becoming increasingly and decently usable.
To use Gamepad Navigation:
- User: Set io.ConfigFlags |= ImGuiConfigFlags_NavEnableGamepad to enable.
- Backend: Set io.BackendFlags |= ImGuiBackendFlags_HasGamepad + fill the io.NavInputs[] fields before calling NewFrame(). Read imgui.cpp for more details.
- See #1599 for recommended gamepad mapping or download PNG/PSD at http://goo.gl/9LgVZW
- See enum ImGuiNavInput_ in imgui.h for a description of inputs. Read imgui.cpp for more details.
To use Keyboard Navigation:
- Set io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard to enable. NewFrame() will automatically fill io.NavInputs[] based on your io.KeyDown[] + io.KeyMap[] arrays.
Basic controls: arrows to navigate, Space to activate and tweak items, ALT to enter menus, Enter to edit text, Escape to cancel/close, Ctrl-Tab to focus windows, etc.
- When keyboard navigation is active (io.NavActive + ImGuiConfigFlags_NavEnableKeyboard), the io.WantCaptureKeyboard flag will be set. For more advanced uses, you may want to read from io.NavActive or io.NavVisible. Read imgui.cpp for more details.
Navigation: SetItemDefaultFocus() sets the navigation position in addition to scrolling. (#787)
Navigation: Added IsItemFocused(), added IsAnyItemFocused(). (#787)
Navigation: Added window flags: ImGuiWindowFlags_NoNav (== ImGuiWindowFlags_NoNavInputs | ImGuiWindowFlags_NoNavFocus).
Navigation: Style: Added ImGuiCol_NavHighlight, ImGuiCol_NavWindowingHighlight colors. (#787)
Navigation: TreeNode: Added ImGuiTreeNodeFlags_NavLeftJumpsBackHere flag to allow Nav Left direction to jump back to parent tree node from any of its child. (#1079)
Navigation: IO: Added io.ConfigFlags (input), io.NavActive (output), io.NavVisible (output). (#787)
Context: Removed the default global context and font atlas instances, which caused various problems to users of multiple contexts and DLL users. (#1565, #1599). YOU NOW NEED TO CALL ImGui::CreateContext() AT THE BEGINNING OF YOUR APP, AND CALL ImGui::DestroyContext() AT THE END. Existing apps will assert/crash without it.
Context: Added SetAllocatorFunctions() to rewire memory allocators (as a replacement to previous parameters to CreateContext()). Allocators are shared by all contexts and imgui helpers. (#1565, #586, #992, #1007, #1558)
Context: You may pass a ImFontAtlas to CreateContext() to specify a font atlas to share. Shared font atlas are not owned by the context and not destroyed along with it. (#1599)
Context: Added IMGUI_DISABLE_DEFAULT_ALLOCATORS to disable linking with malloc/free. (#1565, #586, #992, #1007, #1558)
IO: Added io.ConfigFlags for user application to store settings for imgui and for the back-end:
- ImGuiConfigFlags_NavEnableKeyboard: Enable keyboard navigation.
- ImGuiConfigFlags_NavEnableGamepad: Enable gamepad navigation (provided ImGuiBackendFlags_HasGamepad is also set by back-end).
- ImGuiConfigFlags_NavEnableSetMousePos: Instruct navigation to move the mouse cursor. May be useful on TV/console systems where moving a virtual mouse is awkward.
- ImGuiConfigFlags_NoMouseCursorChange: Instruct back-end to not alter mouse cursor shape and visibility (by default the example back-end use mouse cursor API of the platform when available)
- ImGuiConfigFlags_NoMouse: Instruct imgui to clear mouse position/buttons in NewFrame(). This allows ignoring the mouse information passed by the back-end.
- ImGuiConfigFlags_IsSRGB, ImGuiConfigFlags_IsTouchScreen: Flags for general application use.
IO: Added io.BackendFlags for back-end to store its capabilities (currently: _HasGamepad, _HasMouseCursors, _HasSetMousePos). This will be used more in the next version.
IO: Added ImGuiKey_Insert, ImGuiKey_Space keys. Setup in all example bindings. (#1541)
IO: Added Horizontal Mouse Wheel support for horizontal scrolling. (#1463) [@tseeker]
IO: Added IsAnyMouseDown() helper which is helpful for bindings to handle mouse capturing.
Window: Clicking on a window with the ImGuiWIndowFlags_NoMove flags takes an ActiveId so we can't hover something else when dragging afterwards. (#1381, #1337)
Window: IsWindowHovered(): Added ImGuiHoveredFlags_AnyWindow, ImGuiFocusedFlags_AnyWindow flags (See Breaking Changes). Added to demo. (#1382)
Window: Added SetNextWindowBgAlpha() helper. Particularly helpul since the legacy 5-parameters version of Begin() has been marked as obsolete in 1.53. (#1567)
Window: Fixed SetNextWindowContentSize() with 0.0f on Y axis (or SetNextWindowContentWidth()) overwriting the contents size. Got broken on Dec 10 (1.53). (#1363)
ArrowButton: Added ArrowButton() given a cardinal direction (e.g. ImGuiDir_Left).
InputText: Added alternative clipboard shortcuts: Shift+Delete (cut), Ctrl+Insert (copy), Shift+Insert (paste). (#1541)
InputText: Fixed losing Cursor X position when clicking outside on an item that's submitted after the InputText(). It was only noticeable when restoring focus programmatically. (#1418, #1554)
InputText: Added ImGuiInputTextFlags_CharsScientific flag to also allow 'e'/'E' for input of values using scientific notation. Automatically used by InputFloat.
Style: Default style is now StyleColorsDark(), instead of the old StyleColorsClassic(). (#707)
Style: Enable window border by default. (#707)
Style: Exposed ImGuiStyleVar_WindowTitleAlign, ImGuiStyleVar_ScrollbarSize, ImGuiStyleVar_ScrollbarRounding, ImGuiStyleVar_GrabRounding + added an assert to reduce accidental breakage. (#1181)
Style: Added style.MouseCursorScale help when using the software mouse cursor facility. (#939).
Style: Close button nows display a cross before hovering. Fixed cross positioning being a little off. Uses button colors for highlight when hovering. (#707)
Popup: OpenPopup() Always reopen existing popup. (Removed imgui_internal.h's OpenPopupEx() which was used for this.) (#1497, #1533).
Popup: BeginPopupContextItem(), BeginPopupContextWindow(), BeginPopupContextVoid(), OpenPopupOnItemClick() all react on mouse release instead of mouse press. (~#439)
Popup: Better handling of user mistakenly calling OpenPopup() every frame (with reopen_existing option). The error will now be more visible and easier to understand. (#1497)
Popup: BeginPopup(): Exposed extra_flags parameter that are passed through to Begin(). (#1533)
Popup: BeginPopupModal: fixed the conditional test for SetNextWindowPos() which was polling the wrong window, which in practice made the test succeed all the time.
Tooltip: BeginTooltip() sets ImGuiWindowFlags_NoInputs flag.
Scrollbar: Fixed ScrollbarY enable test after ScrollbarX has been enabled being a little off (small regression from Nov 2017). (#1574)
Scrollbar: Fixed ScrollbarX enable test subtracting WindowPadding.x (this has been there since the addition of horizontal scroll bar!).
Columns: Clear offsets data when columns count changed. (#1525)
Columns: Fixed a memory leak of ImGuiColumnsSet's Columns vector. (#1529) [@unprompted]
Columns: Fixed resizing a window very small breaking some columns positioning (broken in 1.53).
Columns: The available column extent takes consideration of the right-most clipped pixel, so the right-most column may look a little wider but will contain the same amount of visible contents.
MenuBar: Fixed menu bar pushing a clipping rect outside of its allocated bound (usually unnoticeable).
TreeNode: nodes with the ImGuiTreeNodeFlags_Leaf flag correctly disable highlight when DragDrop is active. (#143, #581)
Drag and Drop: Increased payload type string to 32 characters instead of 8. (#143)
Drag and Drop: TreeNode as drop target displays rectangle over full frame. (#1597, #143)
DragFloat: Fix/workaround for backends which do not preserve a valid mouse position when dragged out of bounds. (#1559)
InputFloat: Allow inputing value using scientific notation e.g. "1e+10".
InputDouble: Added InputDouble() function. We use a format string instead of a decimal_precision parameter to also for "%e" and variants. (#1011)
Slider, Combo: Use ImGuiCol_FrameBgHovered color when hovered. (#1456) [@Stfx]
Combo: BeginCombo(): Added ImGuiComboFlags_NoArrowButton to disable the arrow button and only display the wide value preview box.
Combo: BeginCombo(): Added ImGuiComboFlags_NoPreview to disable the preview and only display a square arrow button.
Combo: Arrow button isn't displayed over frame background so its blended color matches other buttons. Left side of the button isn't rounded.
PlotLines: plot a flat line if scale_min==scale_max. (#1621)
Fonts: Changed ImFont::DisplayOffset.y to defaults to 0 instead of +1. Fixed rounding of Ascent/Descent to match TrueType renderer. If you were adding or subtracting (not assigning) to ImFont::DisplayOffset check if your fonts are correctly aligned vertically. (#1619)
Fonts: Updated stb_truetype from 1.14 to stb_truetype 1.19. (w/ include fix from some platforms #1622)
Fonts: Added optional FreeType rasterizer in misc/freetype. Moved from imgui_club repo. (#618) [@Vuhdo, @mikesart, @ocornut]
Fonts: Moved extra_fonts/ to misc/fonts/.
ImFontAtlas: Fixed cfg.MergeMode not reusing existing glyphs if available (always overwrote).
ImFontAtlas: Handle stb_truetype stbtt_InitFont() and stbtt_PackBegin() possible failures more gracefully, GetTexDataAsRGBA32() won't crash during conversion. (#1527)
ImFontAtlas: Moved mouse cursor data out of ImGuiContext, fix drawing them with multiple contexts. Also remove the last remaining undesirable dependency on ImGui in imgui_draw.cpp. (#939)
ImFontAtlas: Added ImFontAtlasFlags_NoPowerOfTwoHeight flag to disable padding font height to nearest power of two. (#1613)
ImFontAtlas: Added ImFontAtlasFlags_NoMouseCursors flag to disable baking software mouse cursors, mostly to save texture memory on very low end hardware. (#1613)
ImDrawList: Fixed AddRect() with anti-aliasing disabled (lower-right corner pixel was often missing, rounding looks a little better.) (#1646)
ImDrawList: Added ImDrawList::CloneOutput() helper to facilitate the cloning of ImDrawData or ImDrawList for multi-threaded rendering.
Misc: Functions passed to libc qsort are explicitly marked cdecl to support compiling with vectorcall as the default calling convention. (#1230, #1611) [@RandyGaul]
Misc: ImVec2: added [] operator. This is becoming desirable for some code working of either axes independently. Better adding it sooner than later.
Misc: NewFrame(): Added an assert to detect incorrect filling of the io.KeyMap[] array earlier. (#1555)
Misc: Added IM_OFFSETOF() helper in imgui.h (previously was in imgui_internal.h)
Misc: Added obsolete redirection function GetItemsLineHeightWithSpacing() (which redirects to GetFrameHeightWithSpacing()), as intended and stated in docs of 1.53.
Misc: Added misc/natvis/imgui.natvis for visual studio debugger users to easily visualize imgui internal types. Added to examples projects.
Misc: Added IMGUI_USER_CONFIG to define a custom configuration filename. (#255, #1573, #1144, #41)
Misc: Added IMGUI_STB_TRUETYPE_FILENAME and IMGUI_STB_RECT_PACK_FILENAME compile time directives to use another version of the stb_ files.
Misc: Updated stb_rect_pack from 0.10 to 0.11 (minor changes).
(Those flags are not used by ImGui itself, they only exists to make it easy for the engine/back-end to pass information to the application in a standard manner.)
Metrics: Added display of Columns state.
Demo: Improved Selectable() examples. Improved BeginCombo() examples. (#1528)
Demo: Tweaked the Child demos, added a menu bar to the second child to test some navigation functions.
Demo: Console: Using ImGuiCol_Text to be more friendly to color changes.
Demo: Using IM_COL32() instead of ImColor() in ImDrawList centric contexts. Trying to phase out use of the ImColor helper whenever possible.
Examples: Files in examples/ now include their own changelog so it is easier to occasionally update your bindings if needed.
Examples: Using Dark theme by default. (#707). Tweaked demo code.
Examples: Added support for horizontal mouse wheel for API that allows it. (#1463) [@tseeker]
Examples: All examples now setup the io.BackendFlags to signify they can honor mouse cursors, gamepad, etc.
Examples: DirectX12: Added DirectX 12 example. (#301) [@jdm3]
Examples: OpenGL3+GLFW,SDL: Changed GLSL shader version from 330 to 150. (#1466, #1504)
Examples: OpenGL3+GLFW,SDL: Added a way to override the GLSL version string in the Init function. (#1466, #1504).
Examples: OpenGL3+GLFW,SDL: Creating VAO in the render function so it can be more easily used by multiple shared OpenGL contexts. (#1217)
Examples: OpenGL3+GLFW: Using 3.2 context instead of 3.3. (#1466)
Examples: OpenGL: Setting up glPixelStorei() explicitly before uploading texture.
Examples: OpenGL: Calls to glPolygonMode() are casting parameters as GLEnum to not fail with more strict bindings. (#1628) [@ilia-glushchenko]
Examples: Win32 (DirectX9,10,11,12): Added support for mouse cursor shapes. (#1495)
Examples: Win32 (DirectX9,10,11,12: Support for windows using the CS_DBLCLKS class flag by handling the double-click messages (WM_LBUTTONDBLCLK etc.). (#1538, #754) [@ndandoulakis]
Examples: Win32 (DirectX9,10,11,12): Made the Win32 proc handlers not assert if there is no active context yet, to be more flexible with creation order. (#1565)
Examples: GLFW: Added support for mouse cursor shapes (the diagonal resize cursors are unfortunately not supported by GLFW at the moment. (#1495)
Examples: GLFW: Don't attempt to change the mouse cursor input mode if it is set to GLFW_CURSOR_DISABLED by the application. (#1202) [@PhilCK]
Examples: SDL: Added support for mouse cursor shapes. (#1626) [@olls]
Examples: SDL: Using SDL_CaptureMouse() to retrieve coordinates outside of client area when dragging (SDL 2.0.4+ only, otherwise using SDL_WINDOW_INPUT_FOCUS instead of previously SDL_WINDOW_MOUSE_FOCUS). (#1559)
Examples: SDL: Enabled vsync by default so people don't come at us with demoes running at 2000 FPS burning a cpu core.
Examples: SDL: Using SDL_GetPerformanceCounter() / SDL_GetPerformanceFrequency() to handle framerate over 1000 FPS properly. (#996)
Examples: SDL: Using scancode exclusively instead of a confusing mixture of scancodes and keycodes.
Examples: SDL: Visual Studio: Added .vcxproj file. Using %SDL2_DIR% in the default .vcxproj and build files instead of %SDL_DIR%, the earlier being more standard.
Examples: Vulkan: Visual Studio: Added .vcxproj file.
Examples: Apple: Fixed filenames in OSX xcode project. Various other Mac friendly fixes. [@gerryhernandez etc.]
Examples: Visual Studio: Disabled extraneous function-level check in Release build.
Various fixes, tweaks, internal refactoring, optimizations, comments.

Roadmap

Some of the features hopefully coming in 2018..

Polish/improve the gamepad and keyboard controls. (#787)
Finish and merge work on multi-viewports and platform windows. (#1542)
Finish and merge work an official implementation of docking, tabs. (#351)
Better/easier support for hi-dpi and multiple simultaneous dpi for the multi-viewports features.
Refactor the example back-end and applications along with how they are built.
Make columns/tables better (they are currently pretty terrible).
Start adding a testing suite to imgui (perhaps in a separate repository) (

Gallery

Some screenshots submitted since 1.53. Please submit pictures or video of your games/applications using dear imgui! See more pictures here > #1607
Also see: Software-using-dear-imgui.

VectorayGen by @jangalomph (https://jangafx.com)