|
| 1 | +<h1 align="center">imnodes</h1> |
| 2 | + |
| 3 | +<p align="center">A small, dependency-free node editor extension for <a href="https://github.com/ocornut/imgui">dear imgui</a>.</p> |
| 4 | + |
| 5 | +<p align="center"> |
| 6 | + <img src="https://raw.githubusercontent.com/Nelarius/imnodes/master/img/imnodes.gif?token=ADH_jEpqbBrw0nH-BUmOip490dyO2CnRks5cVZllwA%3D%3D"> |
| 7 | +</p> |
| 8 | + |
| 9 | +[](https://github.com/nelarius/imnodes/actions?workflow=Build) |
| 10 | + |
| 11 | +Features: |
| 12 | + |
| 13 | +* Create nodes, links, and pins in an immediate-mode style |
| 14 | +* Single header and source file, just copy-paste `imnodes.h` and `imnodes.cpp` into your project. The only dependency is `dear imgui` itself! |
| 15 | +* Written in the same style of C++ as `dear imgui` itself -- no modern C++ used |
| 16 | +* Use regular `dear imgui` widgets inside the nodes |
| 17 | +* Multiple node and link selection with a box selector |
| 18 | +* Nodes, links, and pins are fully customizable, from color style to layout |
| 19 | +* Default themes match `dear imgui`'s default themes |
| 20 | + |
| 21 | +Scroll down for a brief tour, known issues, and further information! |
| 22 | + |
| 23 | +## Build the examples |
| 24 | + |
| 25 | +This repository includes a few example files, under `example/`. You can copy-paste them into your own imgui project, or you can build them here, in this repository. To build here: |
| 26 | +* SDL2 needs to be installed |
| 27 | +* premake5 is used to generate the build files |
| 28 | + |
| 29 | +```bash |
| 30 | +# Assuming you've installed SDL2 via vcpkg, for instance |
| 31 | +$ premake5 gmake \ |
| 32 | + --sdl-include-path=/Users/nelarius/vcpkg/installed/x64-osx/include/SDL2 \ |
| 33 | + --sdl-link-path=/Users/nelarius/vcpkg/installed/x64-osx/lib |
| 34 | + |
| 35 | +# Or alternatively, if you are on MacOS and have the SDL2 framework installed |
| 36 | +$ premake5 gmake --use-sdl-framework |
| 37 | + |
| 38 | +$ make all -j |
| 39 | +``` |
| 40 | + |
| 41 | +## A brief tour |
| 42 | + |
| 43 | +Here is a small overview of how the extension is used. For more information on example usage, scroll to the bottom of the README. |
| 44 | + |
| 45 | +Before anything can be done, the library must be initialized. This can be done at the same time as `dear imgui` initialization. |
| 46 | + |
| 47 | +```cpp |
| 48 | +ImGui::CreateContext(); |
| 49 | +imnodes::Initialize(); |
| 50 | + |
| 51 | +// elsewhere in the code... |
| 52 | +imnodes::Shutdown(); |
| 53 | +ImGui::DestroyContext(); |
| 54 | +``` |
| 55 | + |
| 56 | +The node editor is a workspace which contains nodes. The node editor must be instantiated within a window, like any other UI element. |
| 57 | + |
| 58 | +```cpp |
| 59 | +ImGui::Begin("node editor"); |
| 60 | + |
| 61 | +imnodes::BeginNodeEditor(); |
| 62 | +imnodes::EndNodeEditor(); |
| 63 | + |
| 64 | +ImGui::End(); |
| 65 | +``` |
| 66 | +
|
| 67 | +Now you should have a workspace with a grid visible in the window. An empty node can now be instantiated: |
| 68 | +
|
| 69 | +```cpp |
| 70 | +const int hardcoded_node_id = 1; |
| 71 | +
|
| 72 | +imnodes::BeginNodeEditor(); |
| 73 | +
|
| 74 | +imnodes::BeginNode(hardcoded_node_id); |
| 75 | +ImGui::Dummy(ImVec2(80.0f, 45.0f)); |
| 76 | +imnodes::EndNode(); |
| 77 | +
|
| 78 | +imnode::EndNodeEditor(); |
| 79 | +``` |
| 80 | + |
| 81 | +Nodes, like windows in `dear imgui` must be uniquely identified. But we can't use the node titles for identification, because it should be possible to have many nodes of the same name in the workspace. Instead, you just use integers for identification. |
| 82 | + |
| 83 | +Attributes are the UI content of the node. An attribute will have a pin (the little circle) on either side of the node. There are two types of attributes: input, and output attributes. Input attribute pins are on the left side of the node, and output attribute pins are on the right. Like nodes, pins must be uniquely identified. |
| 84 | + |
| 85 | +```cpp |
| 86 | +imnodes::BeginNode(hardcoded_node_id); |
| 87 | + |
| 88 | +const int output_attr_id = 2; |
| 89 | +imnodes::BeginOutputAttribute(output_attr_id); |
| 90 | +// in between Begin|EndAttribute calls, you can call ImGui |
| 91 | +// UI functions |
| 92 | +ImGui::Text("output pin"); |
| 93 | +imnodes::EndOutputAttribute(); |
| 94 | + |
| 95 | +imnodes::EndNode(); |
| 96 | +``` |
| 97 | +
|
| 98 | +The extension doesn't really care what is in the attribute. It just renders the pin for the attribute, and allows the user to create links between pins. |
| 99 | +
|
| 100 | +A title bar can be added to the node using `BeginNodeTitleBar` and `EndNodeTitleBar`. Like attributes, you place your title bar's content between the function calls. Note that these functions have to be called before adding attributes or other `dear imgui` UI elements to the node, since the node's layout is built in order, top-to-bottom. |
| 101 | +
|
| 102 | +```cpp |
| 103 | +imnodes::BeginNode(hardcoded_node_id); |
| 104 | +
|
| 105 | +imnodes::BeginNodeTitleBar(); |
| 106 | +ImGui::TextUnformatted("output node"); |
| 107 | +imnodes::EndNodeTitleBar(); |
| 108 | +
|
| 109 | +// pins and other node UI content omitted... |
| 110 | +
|
| 111 | +imnodes::EndNode(); |
| 112 | +``` |
| 113 | + |
| 114 | +The user has to render their own links between nodes as well. A link is a curve which connects two attributes. A link is just a pair of attribute ids. And like nodes and attributes, links too have to be identified by unique integer values: |
| 115 | + |
| 116 | +```cpp |
| 117 | +std::vector<std::pair<int, int>> links; |
| 118 | +// elsewhere in the code... |
| 119 | +for (int i = 0; i < links.size(); ++i) |
| 120 | +{ |
| 121 | + const std::pair<int, int> p = links[i]; |
| 122 | + // in this case, we just use the array index of the link |
| 123 | + // as the unique identifier |
| 124 | + imnodes::Link(i, p.first, p.second); |
| 125 | +} |
| 126 | +``` |
| 127 | + |
| 128 | +After `EndNodeEditor` has been called, you can check if a link was created during the frame with the function call `IsLinkCreated`: |
| 129 | + |
| 130 | +```cpp |
| 131 | +int start_attr, end_attr; |
| 132 | +if (imnodes::IsLinkCreated(&start_attr, &end_attr)) |
| 133 | +{ |
| 134 | + links.push_back(std::make_pair(start_attr, end_attr)); |
| 135 | +} |
| 136 | +``` |
| 137 | + |
| 138 | +In addition to checking for new links, you can also check whether UI elements are being hovered over by the mouse cursor: |
| 139 | + |
| 140 | +```cpp |
| 141 | +int node_id; |
| 142 | +if (imnodes::IsNodeHovered(&node_id)) |
| 143 | +{ |
| 144 | + node_hovered = node_id; |
| 145 | +} |
| 146 | +``` |
| 147 | + |
| 148 | +You can also check to see if any node has been selected. Nodes can be clicked on, or they can be selected by clicking and dragging the box selector over them. |
| 149 | + |
| 150 | +```cpp |
| 151 | +// Note that since many nodes can be selected at once, we first need to query the number of |
| 152 | +// selected nodes before getting them. |
| 153 | +const int num_selected_nodes = imnodes::NumSelectedNodes(); |
| 154 | +if (num_selected_nodes > 0) |
| 155 | +{ |
| 156 | + std::vector<int> selected_nodes; |
| 157 | + selected_nodes.resize(num_selected_nodes); |
| 158 | + imnodes::GetSelectedNodes(selected_nodes.data()); |
| 159 | +} |
| 160 | +``` |
| 161 | + |
| 162 | +See `imnodes.h` for more UI event-related functions. |
| 163 | + |
| 164 | +Like `dear imgui`, the style of the UI can be changed. You can set the color style of individual nodes, pins, and links mid-frame by calling `imnodes::PushColorStyle` and `imnodes::PopColorStyle`. |
| 165 | + |
| 166 | +```cpp |
| 167 | +// set the titlebar color of an individual node |
| 168 | +imnodes::PushColorStyle( |
| 169 | + imnodes::ColorStyle_TitleBar, IM_COL32(11, 109, 191, 255)); |
| 170 | +imnodes::PushColorStyle( |
| 171 | + imnodes::ColorStyle_TitleBarSelected, IM_COL32(81, 148, 204, 255)); |
| 172 | + |
| 173 | +imnodes::BeginNode(hardcoded_node_id); |
| 174 | +// node internals here... |
| 175 | +imnodes::EndNode(); |
| 176 | + |
| 177 | +imnodes::PopColorStyle(); |
| 178 | +imnodes::PopColorStyle(); |
| 179 | +``` |
| 180 | +
|
| 181 | +If the style is not being set mid-frame, `imnodes::GetStyle` can be called instead, and the values can be set into the style array directly. |
| 182 | +
|
| 183 | +```cpp |
| 184 | +// set the titlebar color for all nodes |
| 185 | +imnodes::Style& style = imnodes::GetStyle(); |
| 186 | +style.colors[imnodes::ColorStyle_TitleBar] = IM_COL32(232, 27, 86, 255); |
| 187 | +style.colors[imnodes::ColorStyle_TitleBarSelected] = IM_COL32(241, 108, 146, 255); |
| 188 | +``` |
| 189 | + |
| 190 | +## Known issues |
| 191 | + |
| 192 | +* `ImGui::Separator()` spans the current window span. As a result, using a separator inside a node will result in the separator spilling out of the node into the node editor grid. |
| 193 | + |
| 194 | +## Further information |
| 195 | + |
| 196 | +See the `examples/` directory to see library usage in greater detail. |
| 197 | + |
| 198 | +* simple.cpp is a simple hello-world style program which displays two nodes |
| 199 | +* save_load.cpp is enables you to add and remove nodes and links, and serializes/deserializes them, so that the program state is retained between restarting the program |
| 200 | +* color_node_editor.cpp is a more complete example, which shows how a simple node editor is implemented with a graph. |
0 commit comments