Skip to content

Docking

Jump to bottom
omar edited this page Mar 30, 2021 · 17 revisions

this is a draft/skeleton article

Docked windows
Docked windows

Preamble

Where to find it?

Docking is currently available in the docking branch. This is a well maintained branch and most large teams have been using this branch for a while. It is safe and recommended to use that branch.

How can I enable docking?

ImGui::GetIO().ConfigFlags |= ImGuiConfigFlags_DockingEnable;

That's pretty much it. There are 4 additional docked related configuration flags in the io structure which you may toy with.

Why is not merged to master?

(Please note that the following paragraphs have been written by a overly cautious person)

Several advanced features, such as tight interaction with native multi-viewports, or the DockBuilder are still expecting api changes. I am also not particularly happy with how some aspects of the code are current implemented, and considering to maybe rewrite all of docking from scratch a third time!

However, you can benefit from a lot of docking features without being impacted by any of this. The largest amount of interactions you'll have with the docking system are at end-user level and do not require API calls. By just enabling the config flag above and calling 1-2 functions you can benefit from 90% of Docking features. Even the hypothetical full rewrite of Docking system is not expected to impact most users. API that are most at risk of changing are hidden in imgui_internal.h for this reason, and even so, if they do change, we'll make reasonable effort to document the reasoning the update path.

In addition, Docking will only move forward with feedback from users, so the more people using it, the closer we are to a reach mergeable version. TL;DR; is totally fine to use for most users.

Usage Guide

Also see our Glossary about Docking terminology.

Docking

Dock by dragging windows from their title tab or tab (hold SHIFT to disable docking)

  • Dock into an existing window or node

    capture_docking_wiki_gifs_0001

  • Split existing node

    capture_docking_wiki_gifs_0000

Undocking

  • Undock a window from a node

    capture_docking_wiki_gifs_0002

  • Undock a node (all windows) from a hierarchy

    capture_docking_wiki_gifs_0003

Other features

  • Tab bar may be hidden

    capture_docking_wiki_gifs_0004

Settings, Persistence model

  • Explain how/why the data persist

Dockspace

  • Explain dockspace (~~ node positioned within an existing window)
  • Explain central node

Dockbuider api

Debugging

  • Metrics window.
  • Enable IMGUI_DEBUG_LOG_DOCKING()

Legacy Third-Party Docking Extensions

Prior to the official adoption of the Docking branch, various third-party versions existed:

  • @nem0's one github
  • @paniq's one (based on @nem0's), github
  • @BentleyBlanks's one (based on @paniq's), github
  • @thennequin's ImWindow, with OS window managing, github, refactored in bgfx's imgui_wm github
  • @edin-purkovic's one, github
  • @flix01's one, github
  • @aoterodelaroza's one, github
Clone this wiki locally