Skip to content

Commit

Permalink
Merge pull request #126 from Gnimuc/readme
Browse files Browse the repository at this point in the history
Remove explicit instructions from the readme
  • Loading branch information
JamesWrigley authored Jun 27, 2024
2 parents c046ebd + b8497f6 commit 7f61c0a
Showing 1 changed file with 8 additions and 82 deletions.
90 changes: 8 additions & 82 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,88 +11,14 @@
[![deps](https://juliahub.com/docs/CImGui/deps.svg)](https://juliahub.com/ui/Packages/CImGui/HqG2H?t=2)
[![Genie Downloads](https://shields.io/endpoint?url=https://pkgs.genieframework.com/api/v1/badge/CImGui)](https://pkgs.genieframework.com?packages=CImGui)

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

![demo](demo/demo.png)

## Installation

```julia
pkg> add CImGui
```

*Warning*: this package does not follow semantic versioning! See the docs for
information on safely setting compat bounds.

## How to start

### 1. Run `demo/demo.jl` to test whether the default backend works on your machine
```julia-repl
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-repl
julia> using CImGui
julia> include(joinpath(pathof(CImGui), "..", "..", "examples", "demo.jl"))
```
[All of these examples](examples/) (except for
[large_meshes.jl](examples/large_meshes.jl), which is a port of a
[stress-test][stress-test-comment]) are one-to-one ported from [Dear ImGui's C++
examples][upstream-examples] and there is an [interactive
manual][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](https://github.com/Gnimuc/CImGui.jl/blob/master/examples/demo.jl#L76-L113).
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](https://github.com/Gnimuc/CImGui.jl/blob/master/examples/Renderer.jl) for those users who don't bother to study those boilerplate code and eager to draw some widgets on the screen.
```julia-repl
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](https://github.com/Gnimuc/CImGui.jl/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`](https://github.com/Gnimuc/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](https://github.com/JuliaGL/ModernGL.jl) and [GLFW](https://github.com/JuliaGL/GLFW.jl) which are stable and under actively maintained. Other popular backends like [SFML](https://github.com/zyedidia/SFML.jl) and [SDL](https://github.com/ariejdl/SDL.jl) 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.


[stress-test-comment]: https://github.com/ocornut/imgui/issues/2591#issuecomment-496954460
[upstream-examples]: https://github.com/ocornut/imgui/blob/master/imgui_demo.cpp
[interactive-manual]: https://pthom.github.io/imgui_manual_online/manual/imgui_manual.html
See the [documentation](https://Gnimuc.github.io/CImGui.jl/stable) for more info.

3 comments on commit 7f61c0a

@JamesWrigley
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@JuliaRegistrator
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Registration pull request updated: JuliaRegistries/General/109914

Tip: Release Notes

Did you know you can add release notes too? Just add markdown formatted text underneath the comment after the text
"Release notes:" and it will be added to the registry PR, and if TagBot is installed it will also be added to the
release that TagBot creates. i.e.

@JuliaRegistrator register

Release notes:

## Breaking changes

- blah

To add them here just re-invoke and the PR will be updated.

Tagging

After the above pull request is merged, it is recommended that a tag is created on this repository for the registered package version.

This will be done automatically if the Julia TagBot GitHub Action is installed, or can be done manually through the github interface, or via:

git tag -a v2.0.0 -m "<description of version>" 7f61c0a33fdb7eb53938da6356f2010893b267f2
git push origin v2.0.0

@JamesWrigley
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CC @Gnimuc (sorry for the spam 🙈)

Please sign in to comment.