diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json
index 555b1a2..a82ede6 100644
--- a/dev/.documenter-siteinfo.json
+++ b/dev/.documenter-siteinfo.json
@@ -1 +1 @@
-{"documenter":{"julia_version":"1.10.4","generation_timestamp":"2024-07-29T11:52:44","documenter_version":"1.5.0"}}
\ No newline at end of file
+{"documenter":{"julia_version":"1.10.4","generation_timestamp":"2024-08-02T22:07:45","documenter_version":"1.5.0"}}
\ No newline at end of file
diff --git a/dev/_changelog/index.html b/dev/_changelog/index.html
index 0590f0d..318cc16 100644
--- a/dev/_changelog/index.html
+++ b/dev/_changelog/index.html
@@ -1,2 +1,2 @@
-Changelog · CImGui.jl
CImGui.jl now uses semantic versioning to make development easier. This release is based on Dear ImGui 1.90.8.
Breaking: LibCImGui.jl has been merged into CImGui.lib, again for the sake of ease of development.
Breaking: The custom backends that we developed, ImGuiOpenGLBackend.jl and ImGuiGLFWBackend.jl, have been deprecated in favour of using ImGui's official backends. With this change we also dropped support for OpenGL 2, but purely out of laziness. If you need OpenGL 2 let us know and we can build and ship the official OpenGL 2 backend.
Breaking: The built-in renderloop is implemented using package extensions, which are only available on Julia 1.9+. Hence the new minimum required Julia version is 1.9.
CImGui.jl now uses semantic versioning to make development easier. This release is based on Dear ImGui 1.90.8.
Breaking: LibCImGui.jl has been merged into CImGui.lib, again for the sake of ease of development.
Breaking: The custom backends that we developed, ImGuiOpenGLBackend.jl and ImGuiGLFWBackend.jl, have been deprecated in favour of using ImGui's official backends. With this change we also dropped support for OpenGL 2, but purely out of laziness. If you need OpenGL 2 let us know and we can build and ship the official OpenGL 2 backend.
Breaking: The built-in renderloop is implemented using package extensions, which are only available on Julia 1.9+. Hence the new minimum required Julia version is 1.9.
This is useful if you need to forcefully create a new draw call (to allow for dependent rendering / blending). Otherwise primitives are merged into the same draw-call as much as possible.
Transfer ownership of 'ttfdata' to ImFontAtlas! Will be deleted after destruction of the atlas. Set `fontcfg.FontDataOwnedByAtlas=false` to keep ownership of your data and it won't be freed.
Vertically align upcoming text baseline to FramePadding.y so that it will align properly to regularly framed items (call if you have text on a line before a framed item).
Push window to the stack and start appending to it.
Usage
you may append multiple times to the same window during the same frame.
passing p_open != C_NULL shows a window-closing widget in the upper-right corner of the window, which clicking will set the boolean to false when clicked.
Begin return false to indicate the window is collapsed or fully clipped, so you may early out and omit submitting anything to the window.
Note
Always call a matching End for each Begin 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.
Use child windows to begin into a self-contained independent scrolling/clipping regions within a host window. Child windows can embed their own child.
Return false to indicate the window is collapsed or fully clipped, so you may early out and omit submitting anything to the window.
For each independent axis of size:
x == 0.0: use remaining host window size
x > 0.0: fixed size
x < 0.0: use remaining window size minus abs(size)
Each axis can use a different mode, e.g. ImVec2(0,400).
Note
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.
Lock horizontal starting position + capture group bounding box into one "item", so you can use IsItemHovered or layout primitives such as SameLine on whole group, etc.
Use if you want to reimplement ListBox will custom data or interactions. If the function return true, you can output elements then call EndListBox afterwards.
Helper to open and begin popup when clicked on last item. if you can pass a CNULL strid only if the previous item had an id. If you want to use that on a non-interactive item such as Text you need to pass in an explicit ID here.
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Use to simulate layers. By switching channels to can render out-of-order (e.g. submit foreground primitives before background primitives)
Use to minimize draw calls (e.g. if going back-and-forth between multiple non-overlapping clipping rectangles, prefer to append into separate channels then merge at the end)
Use to simulate layers. By switching channels to can render out-of-order (e.g. submit foreground primitives before background primitives)
Use to minimize draw calls (e.g. if going back-and-forth between multiple non-overlapping clipping rectangles, prefer to append into separate channels then merge at the end)
Use to simulate layers. By switching channels to can render out-of-order (e.g. submit foreground primitives before background primitives)
Use to minimize draw calls (e.g. if going back-and-forth between multiple non-overlapping clipping rectangles, prefer to append into separate channels then merge at the end)
If you are submitting lots of evenly spaced items and you have a random access to the list, you can perform coarse clipping based on visibility to save yourself from processing those items at all.
If you are submitting lots of evenly spaced items and you have a random access to the list, you can perform coarse clipping based on visibility to save yourself from processing those items at all.
The clipper calculates the range of visible items and advance the cursor to compensate for the non-visible items we have skipped. ImGui already clip items based on their bounds but it needs to measure text size to do so. Coarse clipping before submission makes this cost and your own data fetching/submission cost null.
This is useful if you need to forcefully create a new draw call (to allow for dependent rendering / blending). Otherwise primitives are merged into the same draw-call as much as possible.
Transfer ownership of 'ttfdata' to ImFontAtlas! Will be deleted after destruction of the atlas. Set `fontcfg.FontDataOwnedByAtlas=false` to keep ownership of your data and it won't be freed.
Vertically align upcoming text baseline to FramePadding.y so that it will align properly to regularly framed items (call if you have text on a line before a framed item).
Push window to the stack and start appending to it.
Usage
you may append multiple times to the same window during the same frame.
passing p_open != C_NULL shows a window-closing widget in the upper-right corner of the window, which clicking will set the boolean to false when clicked.
Begin return false to indicate the window is collapsed or fully clipped, so you may early out and omit submitting anything to the window.
Note
Always call a matching End for each Begin 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.
Use child windows to begin into a self-contained independent scrolling/clipping regions within a host window. Child windows can embed their own child.
Return false to indicate the window is collapsed or fully clipped, so you may early out and omit submitting anything to the window.
For each independent axis of size:
x == 0.0: use remaining host window size
x > 0.0: fixed size
x < 0.0: use remaining window size minus abs(size)
Each axis can use a different mode, e.g. ImVec2(0,400).
Note
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.
Lock horizontal starting position + capture group bounding box into one "item", so you can use IsItemHovered or layout primitives such as SameLine on whole group, etc.
Use if you want to reimplement ListBox will custom data or interactions. If the function return true, you can output elements then call EndListBox afterwards.
Helper to open and begin popup when clicked on last item. if you can pass a CNULL strid only if the previous item had an id. If you want to use that on a non-interactive item such as Text you need to pass in an explicit ID here.
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Use to simulate layers. By switching channels to can render out-of-order (e.g. submit foreground primitives before background primitives)
Use to minimize draw calls (e.g. if going back-and-forth between multiple non-overlapping clipping rectangles, prefer to append into separate channels then merge at the end)
Use to simulate layers. By switching channels to can render out-of-order (e.g. submit foreground primitives before background primitives)
Use to minimize draw calls (e.g. if going back-and-forth between multiple non-overlapping clipping rectangles, prefer to append into separate channels then merge at the end)
Use to simulate layers. By switching channels to can render out-of-order (e.g. submit foreground primitives before background primitives)
Use to minimize draw calls (e.g. if going back-and-forth between multiple non-overlapping clipping rectangles, prefer to append into separate channels then merge at the end)
If you are submitting lots of evenly spaced items and you have a random access to the list, you can perform coarse clipping based on visibility to save yourself from processing those items at all.
If you are submitting lots of evenly spaced items and you have a random access to the list, you can perform coarse clipping based on visibility to save yourself from processing those items at all.
The clipper calculates the range of visible items and advance the cursor to compensate for the non-visible items we have skipped. ImGui already clip items based on their bounds but it needs to measure text size to do so. Coarse clipping before submission makes this cost and your own data fetching/submission cost null.
Example
clipper = CImGui.Clipper()
Begin(clipper, 1000) # we have 1000 elements, evenly spaced.
while CImGui.Step()
dis_start = CImGui.Get(clipper, :DisplayStart)
dis_end = CImGui.Get(clipper, :DisplayEnd)-1
foreach(i->CImGui.Text("line number $i"), dis_start:dis_end)
-end
Step 0: the clipper let you process the first element, regardless of it being visible or not, so we can measure the element height (step skipped if we passed a known height as second arg to constructor).
Step 1: the clipper infer height from first element, calculate the actual range of elements to display, and position the cursor before the first element.
(Step 2: dummy step only required if an explicit items_height was passed to constructor or Begin and user call Step. Does nothing and switch to Step 3.)
Step 3: the clipper validate that we have reached the expected Y position (corresponding to element DisplayEnd), advance the cursor to the end of the list and then returns false to end the loop.
Arguments
items_count: use -1 to ignore (you can call Begin later). use INT_MAX if you don't know how many items you have (in which case the cursor won't be advanced in the final step).
items_height: use -1.0 to be calculated automatically on first step. otherwise pass in the distance between your items, typically GetTextLineHeightWithSpacing or GetFrameHeightWithSpacing. If you don't specify an items_height, you NEED to call Step. If you specify items_height you may call the old Begin/End api directly, but prefer calling Step.
You can also use SameLine(pos_x) for simplified columns. The columns API is work-in-progress and rather lacking (columns are arguably the worst part of dear imgui at the moment!)
Calling this function ends the ImGui frame. This function is automatically called by Render, so you likely don't need to call it yourself directly. If you don't need to render data (skipping rendering), you may call EndFrame but you'll have wasted CPU already! If you don't need to render, better to not create any imgui windows and not call NewFrame at all!
Step 0: the clipper let you process the first element, regardless of it being visible or not, so we can measure the element height (step skipped if we passed a known height as second arg to constructor).
Step 1: the clipper infer height from first element, calculate the actual range of elements to display, and position the cursor before the first element.
(Step 2: dummy step only required if an explicit items_height was passed to constructor or Begin and user call Step. Does nothing and switch to Step 3.)
Step 3: the clipper validate that we have reached the expected Y position (corresponding to element DisplayEnd), advance the cursor to the end of the list and then returns false to end the loop.
Arguments
items_count: use -1 to ignore (you can call Begin later). use INT_MAX if you don't know how many items you have (in which case the cursor won't be advanced in the final step).
items_height: use -1.0 to be calculated automatically on first step. otherwise pass in the distance between your items, typically GetTextLineHeightWithSpacing or GetFrameHeightWithSpacing. If you don't specify an items_height, you NEED to call Step. If you specify items_height you may call the old Begin/End api directly, but prefer calling Step.
You can also use SameLine(pos_x) for simplified columns. The columns API is work-in-progress and rather lacking (columns are arguably the worst part of dear imgui at the moment!)
Calling this function ends the ImGui frame. This function is automatically called by Render, so you likely don't need to call it yourself directly. If you don't need to render data (skipping rendering), you may call EndFrame but you'll have wasted CPU already! If you don't need to render, better to not create any imgui windows and not call NewFrame at all!
Get position of column line (in pixels, from the left side of the contents region). Pass -1 to use current column, otherwise 0..GetColumnsCount() inclusive. Column 0 is typically 0.0.
Get position of column line (in pixels, from the left side of the contents region). Pass -1 to use current column, otherwise 0..GetColumnsCount() inclusive. Column 0 is typically 0.0.
Return bounding rectangle of last item, in screen space. See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Return bounding rectangle of last item, in screen space. See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Return size of last item, in screen space. See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Get desired cursor type, reset in ImGui::NewFrame(), this is updated during the frame. valid before Render. If you use software rendering by setting io.MouseDrawCursor ImGui will render those for you.
Retrieve style color as stored in [ImGuiStyle] structure. Use to feed back into PushStyleColor, otherwise use GetColorU32 to get style color with style alpha baked in.
Return true when the value has been changed or when pressed/selected. Flexible button behavior without the visuals, frequently useful to build custom behaviors using the public api along with IsItemActive, IsItemHovered, etc.
Is the last item active? (e.g. button being held, text field being edited. This will continuously return true while holding mouse button on an item. Items that don't interact will always return false) See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Is the last item clicked? (e.g. button/node just clicked on) == IsMouseClicked(mouse_button) && IsItemHovered. See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Was the last item just made inactive (item was previously active). Useful for Undo/Redo patterns with widgets that requires continuous editing. See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Was the last item just made inactive and made a value change when it was active? (e.g. Slider/Drag moved). Useful for Undo/Redo patterns with widgets that requires continuous editing. Note that you may get false positives (some widgets such as Combo/ListBox/Selectable will return true even when clicking an already selected item). See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Did the last item modify its underlying value this frame? or was pressed? This is generally the same as the "bool" return value of many widgets. See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Is the last item focused for keyboard/gamepad navigation? See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Is the last item visible? (items may be out of sight because of clipping/scrolling). See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Is key being held. == io.KeysDown[userkeyindex]. note that imgui doesn't know the semantic of each entry of io.KeysDown[]. Use your own indices/enums according to how your backend/engine stored them into io.KeysDown[]!
Is mouse hovering given bounding rect (in screen space). Clipped by current clipping settings, but disregarding of other consideration of focus/window ordering/popup-block.
Return bounding rectangle of last item, in screen space. See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Return bounding rectangle of last item, in screen space. See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Return size of last item, in screen space. See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Get desired cursor type, reset in ImGui::NewFrame(), this is updated during the frame. valid before Render. If you use software rendering by setting io.MouseDrawCursor ImGui will render those for you.
Retrieve style color as stored in [ImGuiStyle] structure. Use to feed back into PushStyleColor, otherwise use GetColorU32 to get style color with style alpha baked in.
Return true when the value has been changed or when pressed/selected. Flexible button behavior without the visuals, frequently useful to build custom behaviors using the public api along with IsItemActive, IsItemHovered, etc.
Is the last item active? (e.g. button being held, text field being edited. This will continuously return true while holding mouse button on an item. Items that don't interact will always return false) See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Is the last item clicked? (e.g. button/node just clicked on) == IsMouseClicked(mouse_button) && IsItemHovered. See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Was the last item just made inactive (item was previously active). Useful for Undo/Redo patterns with widgets that requires continuous editing. See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Was the last item just made inactive and made a value change when it was active? (e.g. Slider/Drag moved). Useful for Undo/Redo patterns with widgets that requires continuous editing. Note that you may get false positives (some widgets such as Combo/ListBox/Selectable will return true even when clicking an already selected item). See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Did the last item modify its underlying value this frame? or was pressed? This is generally the same as the "bool" return value of many widgets. See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Is the last item focused for keyboard/gamepad navigation? See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Is the last item visible? (items may be out of sight because of clipping/scrolling). See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Is key being held. == io.KeysDown[userkeyindex]. note that imgui doesn't know the semantic of each entry of io.KeysDown[]. Use your own indices/enums according to how your backend/engine stored them into io.KeysDown[]!
Is mouse hovering given bounding rect (in screen space). Clipped by current clipping settings, but disregarding of other consideration of focus/window ordering/popup-block.
Is current window hovered (and typically: not blocked by a popup/modal)? See the output of CImGui.GetFlags(CImGui.ImGuiHoveredFlags_) for options:
using CImGui, Markdown
CImGui.ShowFlags(CImGui.ImGuiHoveredFlags_) |> Markdown.parse
Note
If you are trying to check whether your mouse should be dispatched to imgui or to your app, you should use the ImGuiIO.WantCaptureMouse boolean for that! Please read the FAQ!
FAQ
Q: How can I tell whether to dispatch mouse/keyboard to imgui or to my application?
A: You can read the ImGuiIO.WantCaptureMouse, ImGuiIO.WantCaptureKeyboard and ImGuiIO.WantTextInput flags from the ImGuiIO structure, for example:
if CImGui.Get_WantCaptureMouse(CImGui.GetIO())
# ...
-end
When ImGuiIO.WantCaptureMouse is set, imgui wants to use your mouse state, and you may want to discard/hide the inputs from the rest of your application.
When ImGuiIO.WantCaptureKeyboard is set, imgui wants to use your keyboard state, and you may want to discard/hide the inputs from the rest of your application.
When ImGuiIO.WantTextInput is set to may want to notify your OS to popup an on-screen keyboard, if available (e.g. on a mobile phone, or console OS).
Note
You should always pass your mouse/keyboard inputs to imgui, even when the ImGuiIO.WantCaptureXXX flag are set false. This is because imgui needs to detect that you clicked in the void to unfocus its own windows.
The ImGuiIO.WantCaptureMouse is more accurate that any attempt to "check if the mouse is hovering a window" (don't do that!). It handle mouse dragging correctly (both dragging that started over your application or over an imgui window) and handle e.g. modal windows blocking inputs. Those flags are updated by NewFrame. Preferably read the flags after calling NewFrame if you can afford it, but reading them before is also perfectly fine, as the bool toggle fairly rarely. If you have on a touch device, you might find use for an early call to UpdateHoveredWindowAndCaptureFlags().
Text input widget releases focus on "Return KeyDown", so the subsequent "Return KeyUp" event that your application receive will typically have ImGuiIO.WantCaptureKeyboard=false. Depending on your application logic it may or not be inconvenient. You might want to track which key-downs were targeted for Dear ImGui, e.g. with an array of bool, and filter out the corresponding key-ups.)
Display text+label aligned the same way as value+label widgets.
Limited support
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Call after CreateContext and before the first call to NewFrame. NewFrame automatically calls LoadIniSettingsFromDisk(ImGuiIO.IniFilename).
Tip
The disk functions are automatically called if ImGuiIO.IniFilename != CNULL (default is "imgui.ini"). Set ImGuiIO.IniFilename to CNULL to load/save manually. Read ImGuiIO.WantSaveIniSettings description about handling .ini saving manually.
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).
In "repeat" mode, Button*() functions return repeated true in a typematic manner (using ImGuiIO.KeyRepeatDelay/ImGuiIO.KeyRepeatRate setting). Note that you can call IsItemActive after any Button() to tell if the button is held in the current frame.
Render-level scissoring. This is passed down to your render function but not used for CPU-side coarse clipping. Prefer using higher-level PushClipRect to affect logic (hit-testing and widget culling).
When ImGuiIO.WantCaptureMouse is set, imgui wants to use your mouse state, and you may want to discard/hide the inputs from the rest of your application.
When ImGuiIO.WantCaptureKeyboard is set, imgui wants to use your keyboard state, and you may want to discard/hide the inputs from the rest of your application.
When ImGuiIO.WantTextInput is set to may want to notify your OS to popup an on-screen keyboard, if available (e.g. on a mobile phone, or console OS).
Note
You should always pass your mouse/keyboard inputs to imgui, even when the ImGuiIO.WantCaptureXXX flag are set false. This is because imgui needs to detect that you clicked in the void to unfocus its own windows.
The ImGuiIO.WantCaptureMouse is more accurate that any attempt to "check if the mouse is hovering a window" (don't do that!). It handle mouse dragging correctly (both dragging that started over your application or over an imgui window) and handle e.g. modal windows blocking inputs. Those flags are updated by NewFrame. Preferably read the flags after calling NewFrame if you can afford it, but reading them before is also perfectly fine, as the bool toggle fairly rarely. If you have on a touch device, you might find use for an early call to UpdateHoveredWindowAndCaptureFlags().
Text input widget releases focus on "Return KeyDown", so the subsequent "Return KeyUp" event that your application receive will typically have ImGuiIO.WantCaptureKeyboard=false. Depending on your application logic it may or not be inconvenient. You might want to track which key-downs were targeted for Dear ImGui, e.g. with an array of bool, and filter out the corresponding key-ups.)
Display text+label aligned the same way as value+label widgets.
Limited support
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Call after CreateContext and before the first call to NewFrame. NewFrame automatically calls LoadIniSettingsFromDisk(ImGuiIO.IniFilename).
Tip
The disk functions are automatically called if ImGuiIO.IniFilename != CNULL (default is "imgui.ini"). Set ImGuiIO.IniFilename to CNULL to load/save manually. Read ImGuiIO.WantSaveIniSettings description about handling .ini saving manually.
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).
In "repeat" mode, Button*() functions return repeated true in a typematic manner (using ImGuiIO.KeyRepeatDelay/ImGuiIO.KeyRepeatRate setting). Note that you can call IsItemActive after any Button() to tell if the button is held in the current frame.
Render-level scissoring. This is passed down to your render function but not used for CPU-side coarse clipping. Prefer using higher-level PushClipRect to affect logic (hit-testing and widget culling).
Push identifier into the ID stack. IDs are hash of the entire stack!
Note
Read the FAQ for more details about how ID are handled in dear imgui. If you are creating widgets in a loop you most likely want to push a unique identifier (e.g. object pointer, loop index) to uniquely differentiate them. You can also use the "##foobar" syntax within widget label to distinguish them from each others.
FAQ
Q: How can I have multiple widgets with the same label or without a label?
Q: I have multiple widgets with the same label, and only the first one works. Why is that?
A: A primer on labels and the ID Stack...
Dear ImGui internally need to uniquely identify UI elements. Elements that are typically not clickable (such as calls to the Text functions) don't need an ID. Interactive widgets (such as calls to Button buttons) need a unique ID. Unique ID are used internally to track active widgets and occasionally associate state to widgets. Unique ID are implicitly built from the hash of multiple elements that identify the "path" to the UI element.
Unique ID are often derived from a string label:
CImGui.Button("OK") # Label = "OK", ID = hash of (..., "OK")
@@ -58,20 +58,20 @@
if CImGui.TreeNode("node")
CImGui.Button("Click") # Label = "Click", ID = hash of (..., "node", "Click")
CImGui.TreePop()
-end
When working with trees, ID are used to preserve the open/close state of each tree node. Depending on your use cases you may want to use strings, indices or pointers as ID.
e.g. when following a single pointer that may change over time, using a static string as ID will preserve your node open/closed state when the targeted object change.
e.g. when displaying a list of objects, using indices or pointers as ID will preserve the node open/closed state differently. See what makes more sense in your situation!
When working with trees, ID are used to preserve the open/close state of each tree node. Depending on your use cases you may want to use strings, indices or pointers as ID.
e.g. when following a single pointer that may change over time, using a static string as ID will preserve your node open/closed state when the targeted object change.
e.g. when displaying a list of objects, using indices or pointers as ID will preserve the node open/closed state differently. See what makes more sense in your situation!
Return a zero-terminated string with the .ini data which you can save by your own mean. Call when ImGuiIO.WantSaveIniSettings is set, then save data by your own mean and clear ImGuiIO.WantSaveIniSettings.
Initialize current options (generally on application startup) if you want to select a default format, picker type, etc. User will be able to change many settings, unless you pass the _NoOptions flag to your calls.
type is a user defined string of maximum 32 characters. Strings starting with '_' are reserved for dear imgui internal types. Data is copied and held by imgui.
Allow last item to be overlapped by a subsequent item. Sometimes useful with invisible buttons, selectables, etc. to catch unused area. See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Manually override io.WantCaptureKeyboard flag next frame (said flag is entirely left for your application to handle). e.g. force capture keyboard when your widget is being hovered.
Set next window content size (~ enforce the range of scrollbars). Not including window decorations (title bar, menu bar, etc.). Set an axis to 0.0 to leave it automatic. Call before Begin.
Notify TabBar or Docking system of a closed tab/window ahead (useful to reduce visual flicker on reorderable tab bars). For tab-bar: call after BeginTabBar() and before Tab submissions. Otherwise call with a window name.
Set a text-only tooltip, typically use with IsItemHovered. Overidde any previous call to SetTooltip.
Limited support
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Add style editor block (not a window). You can pass in a reference ImGuiStyle structure to compare to, revert to and save to (else it uses the default style).
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Shortcut for PushStyleColor(ImGuiCol_Text, col); Text(text); PopStyleColor();.
Limited support
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Shortcut for PushStyleColor(ImGuiCol_Text, style.Colors[ImGuiCol_TextDisabled]); Text(text); PopStyleColor();.
Limited support
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Shortcut for PushTextWrapPos(0.0f); Text(text); PopTextWrapPos();. Note that this won't work on an auto-resizing window if there's no other widgets to extend the window width, yoy may need to set a size using SetNextWindowSize.
Limited support
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
TreeNode functions return true when the node is open, in which case you need to also call TreePop when you are finished displaying the tree node contents.
Helper variation to completely decorelate the id from the displayed string. Read the FAQ in PushID's' doc about why and how to use ID. To align arbitrary text at the same level as a TreeNode you can use Bullet.
Limited support
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Helper variation to completely decorelate the id from the displayed string. Read the FAQ in PushID's' doc about why and how to use ID. To align arbitrary text at the same level as a TreeNode you can use Bullet.
Limited support
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Return a zero-terminated string with the .ini data which you can save by your own mean. Call when ImGuiIO.WantSaveIniSettings is set, then save data by your own mean and clear ImGuiIO.WantSaveIniSettings.
Initialize current options (generally on application startup) if you want to select a default format, picker type, etc. User will be able to change many settings, unless you pass the _NoOptions flag to your calls.
type is a user defined string of maximum 32 characters. Strings starting with '_' are reserved for dear imgui internal types. Data is copied and held by imgui.
Allow last item to be overlapped by a subsequent item. Sometimes useful with invisible buttons, selectables, etc. to catch unused area. See Demo Window under "Widgets->Querying Status" for an interactive visualization of many of those functions.
Manually override io.WantCaptureKeyboard flag next frame (said flag is entirely left for your application to handle). e.g. force capture keyboard when your widget is being hovered.
Set next window content size (~ enforce the range of scrollbars). Not including window decorations (title bar, menu bar, etc.). Set an axis to 0.0 to leave it automatic. Call before Begin.
Notify TabBar or Docking system of a closed tab/window ahead (useful to reduce visual flicker on reorderable tab bars). For tab-bar: call after BeginTabBar() and before Tab submissions. Otherwise call with a window name.
Set a text-only tooltip, typically use with IsItemHovered. Overidde any previous call to SetTooltip.
Limited support
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Add style editor block (not a window). You can pass in a reference ImGuiStyle structure to compare to, revert to and save to (else it uses the default style).
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Shortcut for PushStyleColor(ImGuiCol_Text, col); Text(text); PopStyleColor();.
Limited support
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Shortcut for PushStyleColor(ImGuiCol_Text, style.Colors[ImGuiCol_TextDisabled]); Text(text); PopStyleColor();.
Limited support
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Shortcut for PushTextWrapPos(0.0f); Text(text); PopTextWrapPos();. Note that this won't work on an auto-resizing window if there's no other widgets to extend the window width, yoy may need to set a size using SetNextWindowSize.
Limited support
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
TreeNode functions return true when the node is open, in which case you need to also call TreePop when you are finished displaying the tree node contents.
Helper variation to completely decorelate the id from the displayed string. Read the FAQ in PushID's' doc about why and how to use ID. To align arbitrary text at the same level as a TreeNode you can use Bullet.
Limited support
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Helper variation to completely decorelate the id from the displayed string. Read the FAQ in PushID's' doc about why and how to use ID. To align arbitrary text at the same level as a TreeNode you can use Bullet.
Limited support
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
Formatting is not supported which means you need to pass a formatted string to this function. It's recommended to use Julia stdlib Printf's @sprintf as a workaround when translating C/C++ code to Julia.
ImGui is a very embeddable library because it abstracts things like drawing to the screen and creating windows to its backends. There are many official backends, but currently CImGui.jl only supports the GLFW/OpenGL3 backend.
Top-level function to call a renderloop implemented by the backend selected by set_backend(). This function will not return until the program exits, either by the user closing the window or ui() returning :imgui_exit_loop. It will also not yield the loop, though you may explicitly call yield() in ui().
Arguments
Positional arguments:
ui: The function to execute in the renderloop. This where all the GUI code with calls to CImGui should go.
ctx: The ImGui context to use. Note that DestroyContext() will automatically be called on it at the end of the renderloop, so it will be unusable afterwards.
Keyword arguments:
hotloading=true: Enable calling the latest version of ui() using @invokelatest. This is handy when using Revise.jl.
on_exit::Union{Function, Nothing}=nothing: A destructor/finalizer function that will be called before destroying ctx. This might be useful if you're using some external library that needs to be cleaned up in a certain order.
clear_color=Cfloat[0.45, 0.55, 0.60, 1.00]: The color of the window background. This can also be a Ref{Vector{Cfloat}} if you want to control the color dynamically (see the official demo for an example).
window_size=(1280, 720): The initial size of the window.
window_title="CImGui": The window title.
engine=nothing: An optional ImGuiTestEngine.Engine instance. If there are any tests registered with the test engine they will be queued and run automatically.
opengl_version::VersionNumber=v"3.2": The OpenGL version to use.
ImGui is a very embeddable library because it abstracts things like drawing to the screen and creating windows to its backends. There are many official backends, but currently CImGui.jl only supports the GLFW/OpenGL3 backend.
Top-level function to call a renderloop implemented by the backend selected by set_backend(). This function will not return until the program exits, either by the user closing the window or ui() returning :imgui_exit_loop. It will also not yield the loop, though you may explicitly call yield() in ui().
Arguments
Positional arguments:
ui: The function to execute in the renderloop. This where all the GUI code with calls to CImGui should go.
ctx: The ImGui context to use. Note that DestroyContext() will automatically be called on it at the end of the renderloop, so it will be unusable afterwards.
Keyword arguments:
hotloading=true: Enable calling the latest version of ui() using @invokelatest. This is handy when using Revise.jl.
on_exit::Union{Function, Nothing}=nothing: A destructor/finalizer function that will be called before destroying ctx. This might be useful if you're using some external library that needs to be cleaned up in a certain order.
clear_color=Cfloat[0.45, 0.55, 0.60, 1.00]: The color of the window background. This can also be a Ref{Vector{Cfloat}} if you want to control the color dynamically (see the official demo for an example).
window_size=(1280, 720): The initial size of the window.
window_title="CImGui": The window title.
engine=nothing: An optional ImGuiTestEngine.Engine instance. If there are any tests registered with the test engine they will be queued and run automatically.
opengl_version::VersionNumber=v"3.2": The OpenGL version to use.
CImGui.jl now uses semantic versioning to make development easier. This release is based on Dear ImGui 1.90.8.
Breaking: LibCImGui.jl has been merged into CImGui.lib, again for the sake of ease of development.
Breaking: The custom backends that we developed, ImGuiOpenGLBackend.jl and ImGuiGLFWBackend.jl, have been deprecated in favour of using ImGui's official backends. With this change we also dropped support for OpenGL 2, but purely out of laziness. If you need OpenGL 2 let us know and we can build and ship the official OpenGL 2 backend.
Breaking: The built-in renderloop is implemented using package extensions, which are only available on Julia 1.9+. Hence the new minimum required Julia version is 1.9.
CImGui.jl now uses semantic versioning to make development easier. This release is based on Dear ImGui 1.90.8.
Breaking: LibCImGui.jl has been merged into CImGui.lib, again for the sake of ease of development.
Breaking: The custom backends that we developed, ImGuiOpenGLBackend.jl and ImGuiGLFWBackend.jl, have been deprecated in favour of using ImGui's official backends. With this change we also dropped support for OpenGL 2, but purely out of laziness. If you need OpenGL 2 let us know and we can build and ship the official OpenGL 2 backend.
Breaking: The built-in renderloop is implemented using package extensions, which are only available on Julia 1.9+. Hence the new minimum required Julia version is 1.9.
This document was generated with Documenter.jl version 1.5.0 on Friday 2 August 2024. Using Julia version 1.10.4.
diff --git a/dev/index.html b/dev/index.html
index 08c41dd..a18056b 100644
--- a/dev/index.html
+++ b/dev/index.html
@@ -17,4 +17,4 @@
end
ig.End()
end
Note that neither ImGui nor OpenGL are thread-safe, be aware of this if you start Julia with multiple threads using --threads. If you need to use multiple threads in an application, one option is to use the threadpools introduced in Julia 1.9:
# Have an arbitrary number in the default pool, and 1 thread in the :interactive pool
-$ julia --threads=auto,1
Then start the render loop on the :interactive thread with Threads.@spawn :interactive and ensure that none of the other threads call GUI functions or modify the program state while your GUI code is being executing.
The API provided in this package is as close as possible to the original C++ API. When translating C++ code to Julia, please follow the tips below:
Replace ImGui:: to CImGui. (or ig. if you've run import CImGui as ig).
using CImGui.lib to import all of the ImGuiXXX types into the current namespace.
Member function calling should be translated in Julia style: fonts.AddFont(cfg) => ig.AddFont(fonts, cfg).
[using CImGui.CSyntax] provides two useful macros: @c for translating C's & operator on immutables and @cstatic-block for emulating C's static keyword.
As mentioned before, this package aims to provide the same user experience as the original C++ API, so any high-level abstraction should go into a more high-level package. Redux.jl might be of interest to you if you're looking for state management frameworks.
The default backend is based on ModernGL and GLFW which are stable and under actively maintained. Other popular backends like SFML and SDL could be added in the future if someone should invest time to make these packages work in post Julia 1.0 era.
Settings
This document was generated with Documenter.jl version 1.5.0 on Monday 29 July 2024. Using Julia version 1.10.4.