(work in progress)
Index
General Terms
Backends/Bindings: a piece of code that connects your OS/platform/windowing system, graphics API or programming language to Dear ImGui. In the examples/ folder we provide a bunch of imgui_impl_xxxx files which are backends for a variety of platforms and graphics API. Many other third-party bindings exist.
Demo: the demo code in imgui_demo.cpp, whose main entry point is the ImGui::ShowDemoWindow() function.
Docking: refers to the feature (currently available in the docking branch) where multiple windows can be combined with each other, used to create tab bars, or laid out next to each other.
Draw command, ImDrawCmd: refers to one item within an ImDrawList. One draw command generally maps to one draw call in the underlying graphics API. Some draw commands hold callbacks or special functions that don't necessarily map to an actual draw call in the graphics API.
Draw list, ImDrawList: refers to the low-level rendering API which you can use to submit shapes (such as rectangles, lines, circles or text elements). The ImGui API uses the ImDrawList API to draw elements. You can easily access the drawlist of the current ImGui window using ImGui::GetWindowDrawList() or access special drawlists such as ImGui::GetBackgroundDrawList() (drawn before all ImGui windows) or ImGui::GetForegroundDrawList() (drawn after all ImGui windows). A draw list is generally comprised of multiple draw commands.
Examples: the example applications in the sub-folders of examples/. An example application generally combines one or two backends + dear imgui code + a main.cpp file to form a running application.
Font atlas: a font atlas manage multiple fonts, which for performance reasons are generally rasterized and packed together into a single graphics texture. The font atlas also contains other graphics data that is used by ImGui and ImDrawList.
Item: (same as Widget): a single ImGui element (e.g. a ImGui::Button() or ImGui::Text() call).
Navigation: refer to the subsystem in charge of allowing full control of the UI using Gamepad or Keyboard inputs. Initially Dear ImGui mostly used mouse inputs, and the "navigation" feature allows directional navigation within a set of widgets.
Metrics: refers to the confusingly named Dear ImGui Metrics window, whose main entry point is the ImGui::ShowMetricsWindow() function. The Metrics window exposes lots of internal information about the state of your Dear ImGui context. Using it can help you debug and understand many problems you may have with Dear ImGui. It may also help you better understand how Dear ImGui works.
Multi-Viewports: refers to the feature (currently available in the docking branch) where Dear ImGui windows can easily be moved outside the boundaries of your main application window. The multi-viewports feature provides an interface to interact with bindings in order to create its own application windows to host the floating Dear ImGui windows.
Root Window: a top-level window created with Begin(). Child windows created with BeginChild() tend to share the same Root Window.
Widget: (same as Item): a single ImGui element (e.g. a ImGui::Button() or ImGui::Text() call).
Widget Status Terms
Hovered: Mouse is hovering the window hosting the widget + mouse position is the widget's bounding box. Some windows (popups/modals) frequently disable hovering on windows behind them. When keyboard or gamepad are being used, many widgets have IsItemHovered() return true when Focused. Only one widget can be Hovered at a given time.
Active: Widget is being clicked on, edited, activated, dragged. Only one widget can be Active at a given time (generally set for a short amount of time while manipulating a widget).
Focused: Widget is the last that been clicked on, or has been navigated to using keyboard or gamepad. Only one widget can be focused at a given time.
Visible: Widget is within view: parent window is not collapsed, not tabbed out, and widget is within the visible scrolling region.
Edited: Widget just changed the underlying value (generally set for 1 frame).
Activated: Widget was just made active (action started) (generally set for 1 frame).
Deactivated: Widget was just made inactive (action stopped) (generally set for 1 frame).
DeactivatedAfterEdit: Widget was just made inactive and was in Edited state at least once during its Active state. (generally set for 1 frame).
Docking Terms
Central Node: a specific node inside in Dockspace which: stay visible when empty, use leftover space instead of claiming space, can be made transparent (with the "PassthruCentralNode" flag). This is the node often perceived as an "empty node". It only gets initially created when a node is created with the "DockSpace" flag.
Docking (noun): refers to the Docking subsystem as a whole.
Docking (verb): refers to the action of combining one Window or Dock Node into another Window or Dock Node. A docking operation can be a "Split" (split the target window/node into two sections) or an "Merge" (add into the existing target window/node).
Docking Decorations: Tab Bar and Close Buttons (when managed by a dock node), Resizing Separators.
Dock Node: carries a Tab Bar + zero or more Windows or child dock nodes. A Dock Node can be either a Floating Dock Node or a Dockspace.
Dock Node Hierarchy: a dock node and all its child dock nodes.
Dockspace: a dock node whose Host Window has been created by the user. This implies that the position and size of the dock node is not controlled by the Docking system. It also implies that the lifetime of the dock node is not controlled by the Docking system.
Floating Dock Node: a dock node whose Host Window is automatically created and managed by the Docking system. They are generally freely moveable.
Root Dock Node: a dock node that has no parent dock node.
Leaf Dock Node: a dock node that that no child dock nodes.
Host Window: the Window used to display Docking Decorations. In a Dock Node Hierarchy sitting over a Dockspace, the Host Window is always the window where the Dockspace was submitted. In a Dock Node Hierarchy sitting over a Floating Window, the Host Window is created by the Docking system.
Multi-Viewports Terms
Note: when talking about issues related to the multi-viewports feature, always try to remove ambiguity by specifying if an item is controlled by Dear ImGui or the host system - e.g. "Dear ImGui Window" vs "Platform Window".
Desktop: the area managed by the Operating System or Window Manager that covers all Platform Monitors.
Platform: refers to the low-level system used to interface with native windows: it could be an Operating System library (Win32) or a cross-platform library (such as SDL, GLFW, Allegro).
Platform Backend: refers to the piece of glue code used to have Dear ImGui interact with a given platform (e.g. the imgui_impl_glfw.cpp file). This code typically creates and destroy Platform Windows associated with each Viewport, and sets up the Platform Decorations based on the Viewport flags.
Platform Decoration: refers to the frame and title bar managed and displayed by the Operating System or Window Manager.
Platform Monitor: refers to the representation of a monitor. On a modern OS, each monitor is associated with a non-overlapping set of coordinates (position, size), a work area (main area minus OS task bar) and a DPI scaling factor. Dear ImGui takes advantage of Platform Monitor knowledge for certain tasks (for example, tooltip windows get clamped to fit within a single Platform Monitor and not straddle multiple monitors, new popups try not to overlap the OS task-bar).
Platform Window: a window managed by the Operating System. This is typically associated with a framebuffer, a swap chain and the machinery to perform 3D rendering via some graphics API.
ImGui Decoration: refers to the frame, title bar, collapse and close buttons managed and displayed by ImGui Windows.
ImGui Window: a window managed by Dear ImGui. For the purposes of multi-viewports, we often use "ImGui Window" to refer to a top-level ImGui Window only, not child or docked windows.
Host Viewport: A Host Viewport can contains multiple ImGui Windows. Currently the Main Viewport is always a Host Viewport. In the future we would like to allow application to create zero, one or more Host Viewports. When a Host Viewport is moved, all the ImGui Windows it contains get moved along with it. By default, any ImGui Window overlapping a Host Viewport will be merged into it. Setting io.ConfigViewportsNoAutoMerge disables that behavior, causing every ImGui Window to be hosted by their own unique Single-Window Viewport.
Single-Window Viewport, Owned Viewport: a Viewport owned by a single ImGui Window. In the typical setup, dragging a ImGui Window outside the boundaries of a Host Viewport will create a Single-Window Viewport for the purpose of allowing the ImGui Window to be displayed anywhere on the Desktop.
Main Viewport: Due to common usage and backward compatibility reasons, the system currently enforces the creation of one Main Viewport which is typically the main application window of the user application. The Main Viewport is also a Host Viewport. In most traditional applications, the Main Viewport has Platform Decorations enabled when not maximized, and has Platform Decorations disabled when fullscreen. In the future we would like to completely remove the concept of a "Main Viewport" and instead allow the application to freely create zero, one or more Host Viewports. Most games applications will create one of them, whereas most desktop applications are expected to create none. Under this scheme, an application creating no Host Viewport would have every ImGui Window using an individual Platform Window with Platform Decorations disabled. It would become the application's responsibility to shutdown when all the windows are closed.
Viewport: The Dear ImGui representation of a Platform Window. When a Viewport is active, the Platform Backend creates a Platform Window for it. Whether the Platform Window has Platform Decorations enabled currently depends on io.ConfigViewportsNoDecoration flag which gets turned into a ImGuiViewportFlags_NoDecoration for the Platform Backend to honor.