CImGui

This package provides a Julia language wrapper for cimgui: a thin c-api wrapper programmatically generated for the excellent C++ immediate mode gui Dear ImGui. Dear ImGui is mainly for creating content creation tools and visualization / debug tools. You could browse Gallery to get an idea of its use cases.

Installation

This is the doc for the v1.79 release, not the master branch. The master branch is currently being revamped. Please check #52 for the future directions of this package.

pkg> add CImGui

How to start

1. Run demo/demo.jl to test whether the default backend works on your machine

julia> using CImGui
julia> include(joinpath(pathof(CImGui), "..", "..", "demo", "demo.jl"))

2. Run examples/demo.jl and browse demos in the examples folder to learn how to use the API

julia> using CImGui
julia> include(joinpath(pathof(CImGui), "..", "..", "examples", "demo.jl"))

All of these examples are one-to-one ported from Dear ImGui's C++ examples and there is an interactive manual for quickly locating the code. You could also run ? CImGui.xxx to retrieve docs:

help?> CImGui.Button
  Button(label) -> Bool
  Button(label, size) -> Bool

  Return true when the value has been changed or when pressed/selected.

3. The rendering loop

One thing that is necessary but the package doesn't provide is the rendering loop. Note that all ImGui widgets should run within CImGui.Begin()...CImGui.End(), if not, a crash is waiting for you. For example, directly running CImGui.Button("My button") in REPL will crash Julia.

An example rendering loop module is provided here for those users who don't bother to study those boilerplate code and eager to draw some widgets on the screen.

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

julia> using .Renderer

julia> Renderer.render(width = 360, height = 480, title = "IMGUI Window") do
           CImGui.Begin("Hello ImGui")
           CImGui.Button("My Button") && @show "triggered"
           CImGui.End()
       end
Task (runnable) @0x00000001136bead0

Should you have any other questions, feel free to write a post at the Discussions area.

Usage

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.;
• using LibCImGui to import all of the ImGuiXXX types into the current namespace;
• Member function calling should be translated in Julia style: fonts.AddFont(cfg) => CImGui.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.

LibCImGui

LibCImGui is a thin wrapper over cimgui. It's one-to-one mapped to the original cimgui APIs. By using CImGui.LibCImGui, all of the ImGui-prefixed types, enums and ig-prefixed functions will be imported into the current namespace. It's mainly for people who prefer to use original cimgui's interface.

Backend

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.

License

Only the Julia code in this repo is released under MIT license. Other assets such as those fonts in the fonts folder are released under their own license.