Node Editor in ImGui

This is the fork used by Dear ImGui Bundle. It can be used without it. See what this fork adds: popups, combos and multiline text inside nodes, node width, fixes, automated tests.

The imgui_bundle branch is rebased when upstream moves (its history is rewritten): pin a tag (bundle_YYYYMMDD) or a commit rather than tracking the branch.

About

An implementation of node editor with ImGui-like API.

Project purpose is to serve as a basis for more complex solutions like blueprint editors.

Node Editor is build around an idea "draw your content, we do the rest", which mean interactions are handled by editor, content rendering is handled by user. Editor will take care of:

• placing your node in the word
• dragging nodes
• zoom and scrolling
• selection
• various interaction that can be queried by API (creation, deletion, selection changes, etc.)

Here are some highlights:

• Node movement and selection is handled internally

• Node and pin contents are fully customizable

• Fully styled, default theme is modeled after UE4 blueprints

  • Flexible enough to produce such nodes:

    

  • Customizable links based on Bézier curves:

    

• Automatic highlights for nodes, pins and links:

  

• Smooth navigation and selection

• Node state can be saved in user context, so layout will not break

• Selection rectangles and group dragging

• Context menu support

• Basic shortcuts support (cut/copy/paste/delete)

• ImGui style API

Editor is used to implement blueprint editor in Spark CE engine, it proved itself there by allowing to do everything we needed. Therefore it is now slowly moving into stable state from beeing a prototype.

Note: Project recently was restructured to mimic ImGui layout.

Please report issues or questions if something isn't clear.

Default Bindings

The editor reacts to the following mouse and keyboard inputs out of the box. Mouse buttons are configurable via Config::DragButtonIndex, SelectButtonIndex, NavigateButtonIndex and ContextMenuButtonIndex (defaults: left button for drag/select, right button for navigate/context). Keyboard shortcuts only fire when AreShortcutsEnabled() returns true.

Mouse

Input	Action
Left click on background	Clear selection
Left click on node or link	Select that object (replaces selection)
Ctrl + left click	Toggle the clicked object in or out of the selection
Left drag on background	Rubber-band select nodes
Shift + left drag on background	Rubber-band select Group nodes
Alt + left drag on background	Rubber-band select links
Ctrl + left drag (rubber band)	Keep the previous selection while lassoing
Left drag on a node	Move the node (and members of any selected Group)
Shift + left drag on a node	Move only the directly-selected nodes
Right drag	Pan the canvas
Right click	Open the context menu
Mouse wheel	Zoom in or out (smooth zoom controlled by Config::EnableSmoothZoom)
Double-click on a link / background	Forwarded to the user via the link/background double-click queries

Keyboard

Input	Action
F over a node, pin or Group	Center that object
F with a non-empty selection	Center selection
F over the empty background	Center all content
Shift + F	Same as F, but zooms the targeted object or selection
Space	Open the context menu at the mouse position
Ctrl + X / C / V / D	Cut / Copy / Paste / Duplicate (forwarded as actions to the user)

Dependencies

• Dear ImGui 1.80 or newer, tested up to 1.93.0 WIP
• C++14

Dependencies for examples:

• thedmd/imgui feature/layout-external (Dear ImGui 1.93.0 WIP with Stack Layout, used in blueprints sample)
• stb, and GLFW on macOS, Linux, and Windows with the GLFW backend

CMake fetches all of them at revisions pinned in examples/cmake. An installed GLFW package is used when found.

Optional extension you can pull into your local copy of ImGui node editor can take advantage of:

• https://github.com/thedmd/imgui/tree/feature/draw-list-fringe-scale (for sharp rendering, while zooming) It is part of ImGui since 1.80 release
• https://github.com/thedmd/imgui/tree/feature/extra-keys (for extra shortcuts)

Building / Installing

Node Editor sources are located in root project directory. To use it, simply copy&paste sources into your project. Exactly like you can do with ImGui.

Examples

Examples can be built with CMake 3.24 or newer:

cmake -S examples -B build
cmake --build build --config Release

CMake uses the platform's default generator; -G Ninja or -G Xcode picks another. The executables are in build/bin. They find their data next to them, so they can be started from any directory.

On Windows the examples use Win32 and DirectX 11. -DIMGUI_NODE_EDITOR_EXAMPLES_BACKEND=glfw -DIMGUI_NODE_EDITOR_EXAMPLES_RENDERER=opengl3 builds them with GLFW and OpenGL instead.

On Linux, GLFW needs the X11, Wayland and OpenGL development packages, for example on Ubuntu:

sudo apt-get install libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libxext-dev libwayland-dev libxkbcommon-dev libgl1-mesa-dev

On macOS, the Xcode command line tools are enough.

To build offline or against a local checkout of a dependency, point FetchContent at it, for example -DFETCHCONTENT_SOURCE_DIR_IMGUI=<path>. FETCHCONTENT_SOURCE_DIR_STB and FETCHCONTENT_SOURCE_DIR_GLFW work the same way.

Tests

The headless test suite runs with CTest:

cmake -S tests -B build-tests
cmake --build build-tests --config Debug
ctest --test-dir build-tests -C Debug

-DIMGUI_DIR=<path> tests against another copy of Dear ImGui. The suite needs 1.89 or newer; with an older one only a compatibility test is built, which drives the editor with any Dear ImGui from 1.80. -DIMGUI_NODE_EDITOR_TESTS_SANITIZE=ON builds with AddressSanitizer and adds the tests that detect memory errors. Tests of open issues are expected to fail until the issue is fixed.

python tests/imgui_walk.py --imgui-repo <clone of Dear ImGui> --work <directory> runs the tests against every Dear ImGui release from 1.80 on, and accepts -strict and docking variants of revisions.

Quick Start

Main node editor header is located in imgui_node_editor.h.

Minimal example of one node can be found in simple-example.cpp. Press 'F' in editor to focus on editor content if you see only grid.

# include <imgui.h>
# include <imgui_node_editor.h>
# include <application.h>

namespace ed = ax::NodeEditor;

struct Example:
    public Application
{
    using Application::Application;

    void OnStart() override
    {
        m_SettingsFile = ResolvePath("Simple.json");

        ed::Config config;
        config.SettingsFile = m_SettingsFile.c_str();
        m_Context = ed::CreateEditor(&config);
    }

    void OnStop() override
    {
        ed::DestroyEditor(m_Context);
    }

    void OnFrame(float deltaTime) override
    {
        IM_UNUSED(deltaTime);

        auto& io = ImGui::GetIO();

        ImGui::Text("FPS: %.2f (%.2gms)", io.Framerate, io.Framerate ? 1000.0f / io.Framerate : 0.0f);

        ImGui::Separator();

        ed::SetCurrentEditor(m_Context);
        ed::Begin("My Editor", ImVec2(0.0, 0.0f));
        int uniqueId = 1;
        // Start drawing nodes.
        ed::BeginNode(uniqueId++);
            ImGui::Text("Node A");
            ed::BeginPin(uniqueId++, ed::PinKind::Input);
                ImGui::Text("-> In");
            ed::EndPin();
            ImGui::SameLine();
            ed::BeginPin(uniqueId++, ed::PinKind::Output);
                ImGui::Text("Out ->");
            ed::EndPin();
        ed::EndNode();
        ed::End();
        ed::SetCurrentEditor(nullptr);

        //ImGui::ShowMetricsWindow();
    }

    std::string        m_SettingsFile;
    ed::EditorContext* m_Context = nullptr;
};

int Main(int argc, char** argv)
{
    Example example("Simple", argc, argv);

    if (example.Create())
        return example.Run();

    return 1;
}

Result:

For more details please visit examples folder.

Blueprints Example

Here is Node Editor at work in Spark CE