How to do simple state-management with pure CImGui

[Gnimuc]

Loading packages

Before reading this short tutorial, it's highly recommended to take a glance at Renderer.jl to at least get an idea about the fact that the render() function is running asynchronously.

using CImGui
include(joinpath(pathof(CImGui), "..", "..", "examples", "Renderer.jl"))
using .Renderer

Global variables

Let's start with a simple UI that only plots a sine wave.

Copy-paste the snippet into REPL to create the simple UI.

arr = Cfloat[sin(x) for x in 0:0.01:2pi];

function ui(arr)
    CImGui.Begin("Hello ImGui")
        CImGui.PlotLines("sine wave", arr, length(arr))
    CImGui.End()
end

Renderer.render(()->ui(arr), width = 360, height = 480, title = "A simple UI")

Now, put the UI window and REPL side-by-side and edit the global variable arr at 160 by running arr[160] = 2 in REPL, then you can see the UI gets updated immediately. No magic, crystal clear, just global variables.

Infinite Loop

In practice, the data arr is very likely to be updated by another function and there might be an infinite loop inside that function. How could we handle that? The short answer is using Tasks.

First, we define a stop_flag for exiting the function manually. Then, we define a simple function update! for manipulating the content of arr.

stop_flag = Ref(false)

update!(arr) = foreach(1:50:600) do i
    arr[i] = sin(time()+i)
end

The infinite_loop function looks like this:

function infinite_loop(arr, stop_flag::Ref{Bool})
    @async while true
        stop_flag[] && break
        update!(arr)
        yield()
    end
end

It's as simple as an infinite while loop that is going to be scheduled asynchronously and run concurrently by using @async-yield pairs.

To invoke the function, we firstly make sure the stop_flag is set to false, then call infinite_loop:

julia> stop_flag[] = false
false

julia> t = infinite_loop(arr, stop_flag)
Task (runnable) @0x000000011e8b6410

Now, you can see the animation in the UI window. To stop the task, set stop_flag to true.

julia> stop_flag[] = true
true

julia> t
Task (done) @0x000000011e8b6410

Mutable struct as state holder

For simple UIs, it's convenient to use global variables for state-management, but things get exaggerated every quickly as the UI states grow. It's better to integrate all of the global variables into a big global state instead of using separated global variables.

As of the above example, the UI has two meaningful states: a data container arr and a hook stop_flag controlling when to exit the infinite_loop. So our state holder can look something like this:

mutable struct MyStates
    arr::Vector{Cfloat}
    is_stop::Bool
end

Now, we can rewrite the whole example as:

using CImGui
include(joinpath(pathof(CImGui), "..", "..", "examples", "Renderer.jl"))
using .Renderer

mutable struct MyStates
    arr::Vector{Cfloat}
    is_stop::Bool
end

# nothing special, just a simple initialization 
state_holder = MyStates(Cfloat[sin(x) for x in 0:0.01:2pi], false) 

# this method is left intact
update!(arr) = foreach(1:50:600) do i
    arr[i] = sin(time()+i)
end
# we only need to add a helper method for multiple dispatch
update!(state::MyStates) = update!(state.arr)

# this is the UI function, whenever the structure of `MyStates` is changed, 
# the corresponding changes should be applied
function ui(state::MyStates)
    CImGui.Begin("Hello ImGui")
        CImGui.PlotLines("sine wave", state.arr, length(state.arr))
    CImGui.End()
end

# automatically set the flag when the function gets invoked
function infinite_loop(state::MyStates)
    state.is_stop = false
    @async while true
        state.is_stop && break
        update!(state)
        yield()
    end
end

Renderer.render(()->ui(state_holder), width = 360, height = 480, title = "A simple UI")
infinite_loop(state_holder)

An example of interactive development

In the example above, we need to run state_holder.is_stop = true to set the value in REPL. That's redundant, our UI needs to be improved! Let's add a Checkbox for controlling this state. To edit UI, we only need to tweak the ui function, that's the design. Functions should be decoupled from each other.

Note that directly copy-pasting the code below when the UI is running will not trigger any updates. We need to close the UI windows and run Renderer.render again. Hot-loading UI can be done using Revise.jl, but that's beyond the scope of this post.

function ui(state::MyStates)
    CImGui.Begin("Hello ImGui")
        is_connected = Ref(!state.is_stop)
        if CImGui.Checkbox("connected?", is_connected)
            state.is_stop = !is_connected[]
        end
        CImGui.PlotLines("sine wave", state.arr, length(state.arr))
    CImGui.End()
end

That's it.

[pbouffard]

How would I update values in the state based on widget inputs? For example I tried adding to the state:

mutable struct MyStates
  arr::Vector{Cfloat}
  is_stop::Bool
  afloat::Cfloat
end

and tried to use a slider to modify it:

CImGui.SliderFloat("slider float", Ref(state.afloat), 0.0, 1.0, "ratio = %.3f")

However after I change the slider it just snaps right back to 0.0, and the state value isn't updated.

[Gnimuc]

Julia's Ref(x) is not the same as C's &x. Ref(state.afloat) creates a new tmpvar and only the content of this tmpvar is modified by the C function, so the value state.afloat is left intact, please use the style I posted above.

If you feel like this is too cumbersome, you could use CImGui.CSyntax's @c macro like:

@c CImGui.SliderFloat("slider float", &state.afloat, 0.0, 1.0, "ratio = %.3f")

Basically, the code is lowered to:

var"##tmpvar##" = Ref(state.afloat)
ret = CImGui.SliderFloat("slider float", var"##tmpvar##", 0.0, 1.0, "ratio = %.3f")
state.afloat = var"##tmpvar##"[]
ret

[pbouffard]

Got it, thanks!

[sairus7]

Just rewrote this example to work with ImPlot demo:
JuliaImGui/ImPlot.jl#10