<sub>(This library is available under a free and permissive license, but needs financial support to sustain its continued improvements. In addition to maintenance and stability there are many desirable features yet to be added. If your company is using dear imgui, please consider reaching out. If you are an individual using dear imgui, please consider supporting the project via Patreon or PayPal.)</sub>
<sub>(This library is available under a free and permissive license, but needs financial support to sustain its continued improvements. In addition to maintenance and stability there are many desirable features yet to be added. If your company is using dear imgui, please consider reaching out. If you are an individual using dear imgui, please consider supporting the project via Patreon or PayPal.)</sub>
@ -29,23 +29,15 @@ Dear ImGui is particularly suited to integration in games engine (for tooling),
### Usage
### Usage
Dear ImGui is self-contained within a few files that you can easily copy and compile into your application/engine:
**The core of Dear ImGui is self-contained within a few platform-agnostic files** which you can easily copy and compile into your application/engine. They are all the files in the root folder of the repository (imgui.cpp, imgui.h, imgui_demo.cpp, imgui_draw.cpp etc.).
- imgui.cpp
- imgui.h
- imgui_demo.cpp
- imgui_draw.cpp
- imgui_widgets.cpp
- imgui_internal.h
- imconfig.h (empty by default, user-editable)
- imstb_rectpack.h
- imstb_textedit.h
- imstb_truetype.h
No specific build process is required. You can add the .cpp files to your project or #include them from an existing file.
**No specific build process is required**. You can add the .cpp files to your existing project.
Backends for a variety of graphics api and rendering platforms along with example applications are provided in the [examples/](https://github.com/ocornut/imgui/tree/master/examples) folder.
You will need a backend to integrate Dear ImGui in your app. The backend passes mouse/keyboard/gamepad inputs and variety of settings to Dear ImGui, and is in charge of rendering the resulting vertices.
The backend passes mouse/keyboard/gamepad inputs and variety of settings to Dear ImGui, and is in charge of rendering the resulting vertices. After Dear ImGui is setup in your application, you can use it from \_anywhere\_ in your program loop:
**Backends for a variety of graphics api and rendering platforms** are provided in the [examples/](https://github.com/ocornut/imgui/tree/master/examples) folder, along with example applications. See the [Integration](#integration) section of this document for details. You may also create your own backend. Anywhere where you can render textured triangles, you can render Dear ImGui.
After Dear ImGui is setup in your application, you can use it from \_anywhere\_ in your program loop:
// Old API feature: we could pass the initial window size as a parameter. This was misleading because it only had an effect if the window didn't have data in the .ini file.
window->DC.CurrLineTextBaseOffset=ImMax(window->DC.PrevLineTextBaseOffset,group_data.BackupCurrLineTextBaseOffset);// FIXME: Incorrect, we should grab the base offset from the *first line* of the group but it is hard to obtain now.
window->DC.CurrLineTextBaseOffset=ImMax(window->DC.PrevLineTextBaseOffset,group_data.BackupCurrLineTextBaseOffset);// FIXME: Incorrect, we should grab the base offset from the *first line* of the group but it is hard to obtain now.
ItemSize(group_bb.GetSize(), 0.0f);
ItemSize(group_bb.GetSize());
ItemAdd(group_bb,0);
ItemAdd(group_bb,0);
// If the current ActiveId was declared within the boundary of our group, we copy it to LastItemId so IsItemActive(), IsItemDeactivated() etc. will be functional on the entire group.
// If the current ActiveId was declared within the boundary of our group, we copy it to LastItemId so IsItemActive(), IsItemDeactivated() etc. will be functional on the entire group.
// Each context create its own ImFontAtlas by default. You may instance one yourself and pass it to CreateContext() to share a font atlas between imgui contexts.
// Each context create its own ImFontAtlas by default. You may instance one yourself and pass it to CreateContext() to share a font atlas between imgui contexts.
// All those functions are not reliant on the current context.
// None of those functions is reliant on the current context.
// - Use child windows to begin into a self-contained independent scrolling/clipping regions within a host window. Child windows can embed their own child.
// - 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. ImVec2(0,400).
// - 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. 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.
// - 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 EndChild() for each BeginChild() call, regardless of its return value [this is due to legacy reason and is inconsistent with most other functions such as BeginMenu/EndMenu, BeginPopup/EndPopup, etc. where the EndXXX call should only be called if the corresponding BeginXXX function returned true.]
// Always call a matching EndChild() for each BeginChild() call, regardless of its return value [as with Begin: this is due to legacy reason and inconsistent with most BeginXXX functions apart from the regular Begin() which behaves like BeginChild().]
// - "current window" = the window we are appending into while inside a Begin()/End() block. "next window" = next window we will Begin() into.
// - 'current window' = the window we are appending into while inside a Begin()/End() block. 'next window' = next window we will Begin() into.
IMGUI_APIboolIsWindowAppearing();
IMGUI_APIboolIsWindowAppearing();
IMGUI_APIboolIsWindowCollapsed();
IMGUI_APIboolIsWindowCollapsed();
IMGUI_APIboolIsWindowFocused(ImGuiFocusedFlagsflags=0);// is current window focused? or its root/child, depending on flags. see flags for options.
IMGUI_APIboolIsWindowFocused(ImGuiFocusedFlagsflags=0);// is current window focused? or its root/child, depending on flags. see flags for options.
@ -354,6 +356,7 @@ namespace ImGui
// Cursor / Layout
// Cursor / Layout
// - By "cursor" we mean the current output position.
// - 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.
// - The typical widget behavior is to output themselves at the current cursor position, then move the cursor one line down.
// - You can call SameLine() between widgets to undo the last carriage return and output at the right of the preceeding widget.
IMGUI_APIvoidSeparator();// separator, generally horizontal. inside a menu bar or in horizontal layout mode, this becomes a vertical separator.
IMGUI_APIvoidSeparator();// separator, generally horizontal. inside a menu bar or in horizontal layout mode, this becomes a vertical separator.
IMGUI_APIvoidSameLine(floatoffset_from_start_x=0.0f,floatspacing=-1.0f);// call between widgets or groups to layout them horizontally. X position given in window coordinates.
IMGUI_APIvoidSameLine(floatoffset_from_start_x=0.0f,floatspacing=-1.0f);// call between widgets or groups to layout them horizontally. X position given in window coordinates.
IMGUI_APIvoidNewLine();// undo a SameLine() or force a new line when in an horizontal-layout context.
IMGUI_APIvoidNewLine();// undo a SameLine() or force a new line when in an horizontal-layout context.
@ -396,7 +399,7 @@ namespace ImGui
// Widgets: Text
// Widgets: Text
IMGUI_APIvoidTextUnformatted(constchar*text,constchar*text_end=NULL);// raw text without formatting. Roughly equivalent to 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.
IMGUI_APIvoidTextUnformatted(constchar*text,constchar*text_end=NULL);// raw text without formatting. Roughly equivalent to 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.
IMGUI_APIvoidText(constchar*fmt,...)IM_FMTARGS(1);// simple formatted text
IMGUI_APIvoidText(constchar*fmt,...)IM_FMTARGS(1);// formatted text
IMGUI_APIboolSmallButton(constchar*label);// button with FramePadding=(0,0) to easily embed within text
IMGUI_APIboolSmallButton(constchar*label);// button with FramePadding=(0,0) to easily embed within text
IMGUI_APIboolInvisibleButton(constchar*str_id,constImVec2&size);// button behavior without the visuals, frequently useful to build custom behaviors using the public api (along with IsItemActive, IsItemHovered, etc.)
IMGUI_APIboolInvisibleButton(constchar*str_id,constImVec2&size);// button behavior without the visuals, frequently useful to build custom behaviors using the public api (along with IsItemActive, IsItemHovered, etc.)
@ -425,7 +429,7 @@ namespace ImGui
IMGUI_APIvoidBullet();// draw a small circle and keep the cursor on the same line. advance cursor x position by GetTreeNodeToLabelSpacing(), same distance that TreeNode() uses
IMGUI_APIvoidBullet();// draw a small circle and keep the cursor on the same line. advance cursor x position by GetTreeNodeToLabelSpacing(), same distance that TreeNode() uses
// Widgets: Combo Box
// Widgets: Combo Box
// - The new BeginCombo()/EndCombo() api allows you to manage your contents and selection state however you want it, by creating e.g. Selectable() items.
// - The BeginCombo()/EndCombo() api 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 BeginCombo()/EndCombo() which are kept available for convenience purpose.
// - The old Combo() api are helpers over BeginCombo()/EndCombo() which are kept available for convenience purpose.
IMGUI_APIvoidEndCombo();// only call EndCombo() if BeginCombo() returns true!
IMGUI_APIvoidEndCombo();// only call EndCombo() if BeginCombo() returns true!
@ -521,7 +525,7 @@ namespace ImGui
// Widgets: Selectables
// Widgets: Selectables
// - A selectable highlights when hovered, and can display another color when selected.
// - 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.
// - Neighbors selectable extend their highlight bounds in order to leave no gap between them. This is so a series of selected Selectable appear contiguous.
IMGUI_APIboolSelectable(constchar*label,boolselected=false,ImGuiSelectableFlagsflags=0,constImVec2&size=ImVec2(0,0));// "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
IMGUI_APIboolSelectable(constchar*label,boolselected=false,ImGuiSelectableFlagsflags=0,constImVec2&size=ImVec2(0,0));// "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
IMGUI_APIboolSelectable(constchar*label,bool*p_selected,ImGuiSelectableFlagsflags=0,constImVec2&size=ImVec2(0,0));// "bool* p_selected" point to the selection state (read-write), as a convenient helper.
IMGUI_APIboolSelectable(constchar*label,bool*p_selected,ImGuiSelectableFlagsflags=0,constImVec2&size=ImVec2(0,0));// "bool* p_selected" point to the selection state (read-write), as a convenient helper.
IMGUI_APIboolBeginMainMenuBar();// create and append to a full screen menu-bar.
// - Use BeginMenuBar() on a window ImGuiWindowFlags_MenuBar to append to its menu bar.
IMGUI_APIvoidEndMainMenuBar();// only call EndMainMenuBar() if BeginMainMenuBar() returns true!
// - Use BeginMainMenuBar() to create a menu bar at the top of the screen.
IMGUI_APIboolBeginMenuBar();// append to menu-bar of current window (requires ImGuiWindowFlags_MenuBar flag set on parent window).
IMGUI_APIboolBeginMenuBar();// append to menu-bar of current window (requires ImGuiWindowFlags_MenuBar flag set on parent window).
IMGUI_APIvoidEndMenuBar();// only call EndMenuBar() if BeginMenuBar() returns true!
IMGUI_APIvoidEndMenuBar();// only call EndMenuBar() if BeginMenuBar() returns true!
IMGUI_APIboolBeginMainMenuBar();// create and append to a full screen menu-bar.
IMGUI_APIvoidEndMainMenuBar();// only call EndMainMenuBar() if BeginMainMenuBar() returns true!
IMGUI_APIboolBeginMenu(constchar*label,boolenabled=true);// create a sub-menu entry. only call EndMenu() if this returns true!
IMGUI_APIboolBeginMenu(constchar*label,boolenabled=true);// create a sub-menu entry. only call EndMenu() if this returns true!
IMGUI_APIvoidEndMenu();// only call EndMenu() if BeginMenu() returns true!
IMGUI_APIvoidEndMenu();// only call EndMenu() if BeginMenu() returns true!
IMGUI_APIboolMenuItem(constchar*label,constchar*shortcut=NULL,boolselected=false,boolenabled=true);// return true when activated. shortcuts are displayed for convenience but not processed by ImGui at the moment
IMGUI_APIboolMenuItem(constchar*label,constchar*shortcut=NULL,boolselected=false,boolenabled=true);// return true when activated. shortcuts are displayed for convenience but not processed by ImGui at the moment
IMGUI_APIboolMenuItem(constchar*label,constchar*shortcut,bool*p_selected,boolenabled=true);// return true when activated + toggle (*p_selected) if p_selected != NULL
IMGUI_APIboolMenuItem(constchar*label,constchar*shortcut,bool*p_selected,boolenabled=true);// return true when activated + toggle (*p_selected) if p_selected != NULL
// Tooltips
// Tooltips
// - Tooltip are windows following the mouse which do not take focus away.
IMGUI_APIvoidBeginTooltip();// begin/append a tooltip window. to create full-featured tooltip (with any kind of items).
IMGUI_APIvoidBeginTooltip();// begin/append a tooltip window. to create full-featured tooltip (with any kind of items).
IMGUI_APIvoidEndTooltip();
IMGUI_APIvoidEndTooltip();
IMGUI_APIvoidSetTooltip(constchar*fmt,...)IM_FMTARGS(1);// set a text-only tooltip, typically use with ImGui::IsItemHovered(). override any previous call to SetTooltip().
IMGUI_APIvoidSetTooltip(constchar*fmt,...)IM_FMTARGS(1);// set a text-only tooltip, typically use with ImGui::IsItemHovered(). override any previous call to SetTooltip().
@ -568,7 +575,7 @@ namespace ImGui
// - Unless modal, they can be closed by clicking anywhere outside them, or by pressing ESCAPE.
// - Unless modal, they can be closed by clicking anywhere outside them, or by pressing ESCAPE.
// - Their visibility state (~bool) is held internally by imgui instead of being held by the programmer as we are used to with regular Begin() calls.
// - Their visibility state (~bool) is held internally by imgui instead of being held by the programmer as we are used to with regular Begin() calls.
// User can manipulate the visibility state by calling OpenPopup().
// User can manipulate the visibility state by calling OpenPopup().
// (*) One can use IsItemHovered(ImGuiHoveredFlags_AllowWhenBlockedByPopup) to bypass it and detect hovering even when normally blocked by a popup.
// (*) You can use IsItemHovered(ImGuiHoveredFlags_AllowWhenBlockedByPopup) to bypass it and detect hovering even when normally blocked by a popup.
// Those three properties are connected. The library needs to hold their visibility state because it can close popups at any time.
// Those three properties are connected. The library needs to hold their visibility state because it can close popups at any time.
IMGUI_APIvoidOpenPopup(constchar*str_id);// call to mark popup as open (don't call every frame!). popups are closed when user click outside, or if CloseCurrentPopup() is called within a BeginPopup()/EndPopup() block. By default, Selectable()/MenuItem() are calling CloseCurrentPopup(). Popup identifiers are relative to the current ID-stack (so OpenPopup and BeginPopup needs to be at the same level).
IMGUI_APIvoidOpenPopup(constchar*str_id);// call to mark popup as open (don't call every frame!). popups are closed when user click outside, or if CloseCurrentPopup() is called within a BeginPopup()/EndPopup() block. By default, Selectable()/MenuItem() are calling CloseCurrentPopup(). Popup identifiers are relative to the current ID-stack (so OpenPopup and BeginPopup needs to be at the same level).
IMGUI_APIboolBeginPopup(constchar*str_id,ImGuiWindowFlagsflags=0);// return true if the popup is open, and you can start outputting to it. only call EndPopup() if BeginPopup() returns true!
IMGUI_APIboolBeginPopup(constchar*str_id,ImGuiWindowFlagsflags=0);// return true if the popup is open, and you can start outputting to it. only call EndPopup() if BeginPopup() returns true!
@ -584,6 +591,7 @@ namespace ImGui
// Columns
// Columns
// - You can also use SameLine(pos_x) to mimic simplified columns.
// - You can also use SameLine(pos_x) to mimic simplified columns.
// - The columns API is work-in-progress and rather lacking (columns are arguably the worst part of dear imgui at the moment!)
// - The columns API is work-in-progress and rather lacking (columns are arguably the worst part of dear imgui at the moment!)
// - By end of the 2019 we will expose a new 'Table' api which will replace columns.
IMGUI_APIvoidAddRemapChar(ImWchardst,ImWcharsrc,booloverwrite_dst=true);// Makes 'dst' character/glyph points to 'src' character/glyph. Currently needs to be called AFTER fonts have been built.
IMGUI_APIvoidAddRemapChar(ImWchardst,ImWcharsrc,booloverwrite_dst=true);// Makes 'dst' character/glyph points to 'src' character/glyph. Currently needs to be called AFTER fonts have been built.
HelpMarker("Save/Revert in local non-persistent storage. Default Colors definition are not affected. Use \"Export Colors\" below to save them somewhere.");
HelpMarker("Save/Revert in local non-persistent storage. Default Colors definition are not affected. Use \"Export\" below to save them somewhere.");
// FIXME: Provided a rectangle perhaps e.g. a BeginMenuBarEx() could be used anywhere..
// FIXME: Provided a rectangle perhaps e.g. a BeginMenuBarEx() could be used anywhere..
// Currently the main responsibility of this function being to setup clip-rect + horizontal layout + menu navigation layer.
// Currently the main responsibility of this function being to setup clip-rect + horizontal layout + menu navigation layer.
// Ideally we also want this to be responsible for claiming space out of the main window scrolling rectangle, in which case ImGuiWindowFlags_MenuBar will become unnecessary.
// Ideally we also want this to be responsible for claiming space out of the main window scrolling rectangle, in which case ImGuiWindowFlags_MenuBar will become unnecessary.
@ -6113,6 +6078,42 @@ void ImGui::EndMenuBar()
window->DC.MenuBarAppending=false;
window->DC.MenuBarAppending=false;
}
}
// For the main menu bar, which cannot be moved, we honor g.Style.DisplaySafeAreaPadding to ensure text can be visible on a TV set.
omar
5 years ago