search

ice1000 / jimgui

:sparkling_heart: Pure Java binding for dear-imgui
Apache License 2.0
186 stars 13 forks source link
dear-imgui imgui java java-bindings

readme

jimgui

Join the chat at https://gitter.im/imgui-java/community Maven Central

Linux Build Windows Build
CCI AV

To jcenter users: as the deprecation of jcenter, this library is now published to maven central since v0.20. Please update your repository setting to reflect the change.

Cross-platform efficient pure Java binding for dear-imgui, Kotlin is used as code generation tool.

This binding is rather bare-metal, that reflects imgui's API directly. I think it's good enough, but you may expect some other styles of bindings.

There is a declarative wrapper of jimgui, namely flui available.

Features

Can be considered as both advantages and disadvantages.

Java

It is Java-only with an optional Kotlin DSL wrapper.

Pure

It hides everything about rendering behind-the-scene, so you don't need to worry about GLFW, OpenGL or DirectX stuffs (speaking of lwjgl or jogl integration -- see #18, it's hard).

Also, it doesn't separate jars for different platforms. One jar works on all supported platforms.

Usability

It is well-known that dear imgui doesn't have image loading out-of-the-box, but this library has, and it even has a wrapper for aiekick/ImGuiFileDialog and Flix01/imguidatechooser and some other minor widgets.

Efficiency

This is twofolded.

IDE-friendliness

It exploits JetBrains annotations, particularly with MagicConstant, NotNull, Nullable and Contract.

MagicConstant annotation enables IntelliJ IDEA to provide completion for int flags arguments with only the flags needed:

image

This project was created for a code editor and a game engine, both dead.

For macOS users, make sure you add -XstartOnFirstThread JVM argument when running applications built with jimgui.

Demo

Contents

Bindings to official features

Extra convenience provided

C++ interoperability

Backends and platforms

Usage

Code example

import org.ice1000.jimgui.JImGui;
import org.ice1000.jimgui.util.JniLoader;

public class Main {
  public static void main(String... args){
    JniLoader.load();
    try (JImGui imGui = new JImGui()) {
      // load fonts, global initializations, etc.
      while (!imGui.windowShouldClose()) {
        // some drawing-unrelated initializations
        // mostly do nothing here
        imGui.initNewFrame();
        // draw your widgets here, like this
        imGui.text("Hello, World!");
        imGui.render();
        // mostly do nothing here
      }
    }
  }
}

Kotlin DSL:

runPer(10) {
  "Window with Tabs" {
    tabBar("tab bar id") {
      tabItem("Tab One") { text("I am in Tab one!") }
      tabItem("Tab Two") { button("I am in Tab two!") }
      tabItem("Tab Three") { bulletText("I am in Tab three!") }
    }

    treeNode("PsiClassBody") {
      treeNode("PsiConstructor") {
        text("PsiIdentifier")
      }
      treeNode("PsiMethod") {
        text("PsiAnnotation")
        text("PsiLeafElement")
      }
    }
  }
}

Using Unicode strings

You can use ImGuiFontAtlas to extend glyph ranges for your font, which is needed if you want to display Unicode characters. You can find more info about glyph ranges at the dear-imgui repository.

Notice that to display Unicode characters you need to have your Java sources encoded and compiled as UTF-8. To compile the sources as UTF-8, add the following line to your build.gradle:

compileJava.options.encoding = 'UTF-8'

Gradle

import org.apache.tools.ant.taskdefs.condition.Os
// ...
dependencies {
  String jimguiVersion = 'v0.20.3'
  implementation "org.ice1000.jimgui:core:$jimguiVersion" // basic functionality
  implementation "org.ice1000.jimgui:kotlin-dsl:$jimguiVersion" // kotlin dsl wrapper
}
// ...
tasks.withType(JavaExec).configureEach {
  if (Os.isFamily(Os.FAMILY_MAC)) jvmArgs "-XstartOnFirstThread"
}

Gradle Kotlin DSL

import org.apache.tools.ant.taskdefs.condition.Os
dependencies {
  val jimguiVersion = "v0.20.3"
  implementation("org.ice1000.jimgui:core:$jimguiVersion") // basic functionality
  implementation("org.ice1000.jimgui:kotlin-dsl:$jimguiVersion") // kotlin dsl wrapper
}

tasks.withType<JavaExec>().configureEach {
  if (Os.isFamily(Os.FAMILY_MAC)) jvmArgs("-XstartOnFirstThread")
}

Maven

<dependency>
  <groupId>org.ice1000.jimgui</groupId>
  <!-- basic functionality -->
  <artifactId>core</artifactId>
  <version>v0.20.3</version>
  <type>pom</type>
</dependency>

Build

First you need to make sure you have cmake newer than 3.14 and the following software installed:

To compile a jar library, run (you need to use the developer command prompt for this on Windows):

$ ./gradlew jar

To run tests, run:

$ ./gradlew test