{"id":31050359,"url":"https://github.com/jwharm/java-gi","last_synced_at":"2025-09-14T22:42:11.420Z","repository":{"id":60153234,"uuid":"529180836","full_name":"jwharm/java-gi","owner":"jwharm","description":"GObject-Introspection bindings generator for Java","archived":false,"fork":false,"pushed_at":"2025-09-13T16:01:54.000Z","size":5439,"stargazers_count":119,"open_issues_count":7,"forks_count":11,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-09-13T18:20:24.148Z","etag":null,"topics":["bindings","gnome","gtk","java","jep-454"],"latest_commit_sha":null,"homepage":"http://java-gi.org/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jwharm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-08-26T08:41:03.000Z","updated_at":"2025-09-13T16:01:57.000Z","dependencies_parsed_at":"2024-11-06T21:24:34.995Z","dependency_job_id":"e2702051-9136-41a1-aa26-86c39c4a5898","html_url":"https://github.com/jwharm/java-gi","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/jwharm/java-gi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwharm%2Fjava-gi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwharm%2Fjava-gi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwharm%2Fjava-gi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwharm%2Fjava-gi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jwharm","download_url":"https://codeload.github.com/jwharm/java-gi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwharm%2Fjava-gi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275180196,"owners_count":25419065,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-14T02:00:10.474Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bindings","gnome","gtk","java","jep-454"],"created_at":"2025-09-14T22:42:06.931Z","updated_at":"2025-09-14T22:42:11.399Z","avatar_url":"https://github.com/jwharm.png","language":"Java","readme":"# Java-GI\n\n**Java-GI** is a tool for generating GObject-Introspection bindings for Java. The generated bindings use the [Foreign Function \u0026 Memory API](https://openjdk.org/projects/panama/) (JEP 454) to access native resources from Java, with wrapper classes based on GObject-Introspection to offer an elegant API. Java-GI version 0.12.* generates bindings to develop Java applications for libraries, based of the versions in GNOME Platform 48:\n\n| Library       | Version |\n|---------------|---------|\n| GLib          | 2.84    |\n| GTK           | 4.18    |\n| LibAdwaita    | 1.7     |\n| GStreamer     | 1.24    |\n| GtkSourceview | 5.16    |\n| WebkitGtk     | 2.48    |\n\nYou can generate Java bindings for other libraries with the `java-gi` [command-line tool](https://jwharm.github.io/java-gi/generate/) on the GIR (introspection data) file.\n\nPlease note that Java-GI is still under active development, and the API is subject to unannounced changes. Feedback is welcome!\n\n[For more information, visit the Java-GI website.](https://jwharm.github.io/java-gi/)\n\n## Usage\n\nLet's write a small \"Hello World\" GTK application:\n\n```java\nimport org.gnome.gtk.*;\nimport org.gnome.gio.ApplicationFlags;\n\npublic class HelloWorld {\n\n    public static void main(String[] args) {\n        new HelloWorld(args);\n    }\n\n    private final Application app;\n\n    public HelloWorld(String[] args) {\n        app = new Application(\"my.example.HelloApp\", ApplicationFlags.DEFAULT_FLAGS);\n        app.onActivate(this::activate);\n        app.run(args);\n    }\n\n    public void activate() {\n        var window = new ApplicationWindow(app);\n        window.setTitle(\"GTK from Java\");\n        window.setDefaultSize(300, 200);\n\n        var box = Box.builder()\n                .setOrientation(Orientation.VERTICAL)\n                .setHalign(Align.CENTER)\n                .setValign(Align.CENTER)\n                .build();\n\n        var button = Button.withLabel(\"Hello world!\");\n        button.onClicked(window::close);\n\n        box.append(button);\n        window.setChild(box);\n        window.present();\n    }\n}\n```\n\nAdd the Gtk dependency to your build script, for example with Gradle:\n\n```groovy\nrepositories {\n    mavenCentral()\n}\n\ndependencies {\n    implementation 'io.github.jwharm.javagi:gtk:0.12.2'\n}\n```\n\nThe result:\n\n![Screenshot of a simple Java-GI HelloWorld app](docs/img/simple-helloworld.png)\n\n## Examples\n\nYou can find some examples [here](https://github.com/jwharm/java-gi-examples). Each example can be separately built and run with `gradle run`:\n\n| ![Browser screenshot](https://github.com/jwharm/java-gi-examples/blob/main/Browser/browser.png) | ![Peg Solitaire screenshot](https://github.com/jwharm/java-gi-examples/blob/main/PegSolitaire/peg-solitaire.png) | ![Calculator screenshot](https://github.com/jwharm/java-gi-examples/blob/main/Calculator/calculator.png) | ![Notepad screenshot](https://github.com/jwharm/java-gi-examples/blob/main/Notepad/notepad.png) |\n| ---- | ---- | ---- | ---- |\n| [Web Browser](https://github.com/jwharm/java-gi-examples/tree/main/Browser)                     | [Peg Solitaire](https://github.com/jwharm/java-gi-examples/tree/main/PegSolitaire) | [Calculator](https://github.com/jwharm/java-gi-examples/tree/main/Calculator) | [Notepad](https://github.com/jwharm/java-gi-examples/tree/main/Notepad) |\n\n## Generate bindings for other libraries\n\nJava-GI offers a command-line utility to generate bindings for any library that supports GObject-Introspection. It is documented [here](https://jwharm.github.io/java-gi/generate/).\n\n## Current features\n\nNearly all types, functions and parameters defined in a GIR file are supported by Java-GI. Even complex function signatures with combinations of arrays, callbacks, out-parameters and varargs are available in Java.\n\nSome interesting features of the bindings that Java-GI generates:\n\n### Automatic memory management\n\nMemory management of native resources is automatically taken care of. Java-GI uses GObject toggle references to dispose the native object when the Java instance is garbage-collected, and releases all other memory allocations (for strings, arrays and structs) after use.\n\n### Javadoc\n\nAll API docstrings are translated into Javadoc, so they are directly available in your IDE.\n\nAs an example, the generated documentation of `gtk_button_get_icon_name` contains links to other methods, and specifies the return value. This is all translated to valid Javadoc.\n\n![Javadoc screenshot](docs/img/javadoc.png)\n\nThe Javadoc is published [online](https://jwharm.github.io/java-gi/javadoc).\n\n### GObject type system\n\nGObject classes are available as Java classes (obviously). The GObject TypeClass definition is an inner class in the Java class.\n\nInterfaces are mapped to Java interfaces, using `default` interface methods to call native methods.\n\nType aliases (`typedef`s in C) for classes, records and interfaces are represented in Java with a subclass of the original type. Aliases for primitive types such as `int` or `float` are represented by simple wrapper classes.\n\nEnumerations are represented as Java `enum` types, and flag parameters are mapped to `EnumSet`.\n\nMost classes have one or more constructors. However, constructors in GTK are often overloaded, and the name contains valuable information for the user. Java-GI therefore maps constructors named \"new\" to regular Java constructors, and generates static factory methods for all other constructors:\n\n```java\n// gtk_button_new\nvar button1 = new Button();\n\n// gtk_button_new_with_label\nvar button2 = Button.withLabel(\"Open...\");\n\n// gtk_button_new_from_icon_name\nvar button3 = Button.fromIconName(\"document-open\");\n```\n\nSome struct types (called \"records\" in GObject-Introspection) don't have constructors, because in C these are meant to be stack-allocated. An example is `Gdk.RGBA`. Java-GI adds constructors that will allocate a new struct in an [Arena](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/foreign/Arena.html) of your choice. You can either allocate an empty struct (`var color = new RGBA();`) and fill in the values later, or pass the values immediately: `var purple = new RGBA(0.9f, 0.1f, 0.9f, 1.0f);`\n\n### Signals, callbacks and closures\n\nSignals are mapped to type-safe methods and objects in Java. (Detailed signals like `notify` have an extra `String` parameter.) A signal can be connected to a lambda expression or method reference:\n\n```java\nvar button = Button.withLabel(\"Close\");\nbutton.onClicked(window::close);\n```\n\nFor every signal, a method to connect (e.g. `onClicked`) and emit the signal (`emitClicked`) is included in the API. New signal connections return a `SignalConnection` object, that allows you to disconnect, block and unblock a signal, or check whether the signal is still connected.\n\nFunctions with callback parameters are supported too. The generated Java bindings contain `@FunctionalInterface` definitions for all callback functions to ensure type safety.\n\n[Closures](https://docs.gtk.org/gobject/struct.Closure.html) are marshaled to Java methods using reflection.\n\n### Registering new types\n\nJava-GI registers GObject-derived Java classes as a GType. When overriding virtual methods from a parent class (or implementing methods from an interface), Java-GI will register that in the GObject type system, so native code will call your Java method too. JavaBeans-style getter and setter method pairs are registered as GObject properties. You can also define your own custom signals, using the \"@Signal\" annotation. The following example defines an `int` property named `\"lives\"` and a `\"game-over\"` signal with a `String` parameter:\n\n```java\npublic class Player extends GObject {\n    private String name;\n\n    public int getLives() {\n        return lives;\n    }\n    \n    public void setLives(int value) {\n        this.lives = value;\n        if (value == 0)\n            emit(\"game-over\", this.name);\n    }\n\n    @Signal\n    public interface GameOver {\n        void apply(String playerName);\n    }\n}\n```\n\nRead the [Java-GI documentation](https://jwharm.github.io/java-gi/register/) for an overview of all the possibilities.\n\n### Composite template classes\n\nA class with a `@GtkTemplate` annotation will be registered as a Gtk composite template class:\n\n```java\n@GtkTemplate(ui=\"/my/example/hello-window.ui\")\npublic class HelloWindow extends ApplicationWindow {\n\n    @GtkChild(name=\"header_bar\")\n    public HeaderBar header;\n\n    @GtkChild\n    public Label label;\n    \n    @GtkCallback\n    public void buttonClicked() {\n        ...\n    }\n}\n```\n\nIn the above example, the `header_bar` and `label` elements and the `buttonClicked` callback function are all connected to the `hello-window.ui` file.\n\nYou can read more about template classes in [the documentation](https://jwharm.github.io/java-gi/templates/).\n\n### Parameters\n\nJava-GI takes care of marshaling Java values from and to native values. When working with arrays, Java-GI will automatically copy native array contents from and to a Java array, marshaling the contents to the correct types along the way. A `null` terminator is added where applicable. You also don't need to specify the array length as a separate parameter.\n\nNullability of parameters (as defined in the GObject-introspection attributes) is indicated with `@Nullable` and `@NotNull` attributes, and checked at runtime. The nullability attributes are imported from Jetbrains Annotations (as a compile-time-only dependency).\n\nVariadic functions (varargs) are supported too:\n\n```java\nDialog d = Dialog.withButtons(\n        \"Test dialog\",\n        window,\n        DialogFlags.MODAL,\n        \"Accept\",\n        ResponseType.ACCEPT,\n        \"Cancel\",\n        ResponseType.CANCEL,\n        null\n);\nd.show();\n```\n\nOut-parameters are mapped to a simple `Out\u003cT\u003e` container-type in Java, that offers typesafe `get()` and `set()` methods to retrieve or modify the value.\n\n```java\nFile file = ...\nOut\u003cbyte[]\u003e contents = new Out\u003cbyte[]\u003e();\nfile.loadContents(null, contents, null));\nSystem.out.printf(\"Read %d bytes%n\", contents.get().length);\n```\n\n### Builder pattern\n\nYou can construct an object with properties using a Builder pattern. In the \"Hello World\" app above, it's used to create a `Box`. It can be used for any other type too:\n\n```java\nvar window = ApplicationWindow.builder()\n    .setApplication(this)\n    .setTitle(\"Window\")\n    .setDefaultWidth(300)\n    .setDefaultHeight(200)\n    .build();\n```\n\nJava-GI generates builders for all classes. In a builder, you can set the properties of the class, its parents, and all implemented interfaces.\n\n### Exceptions\n\n`GError` parameters are mapped to Java `GErrorException`s.\n\n```java\ntry {\n    file.replaceContents(contents, null, false, FileCreateFlags.NONE, null, null);\n} catch (GErrorException e) {\n    ... // handle exception\n}\n```\n\n### Portability\n\nThe published bindings are cross-platform: You can use the same jar on all supported operating systems (64-bit Linux, Windows and MacOS) provided that the native libraries are installed. Platform-specific types and methods (like `Gtk.PrintUnixDialog`) check the operating system at runtime and throw an `UnsupportedPlatformException` when necessary.\n\n## Known issues\n\nJava-GI is still under active development. The most notable issues and missing features are currently:\n\n- Java does not distinguish between signed and unsigned data types. Be extra careful when native code returns, for example, a `guint`.\n- Java-GI makes heavy use of [Cleaners](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/ref/Cleaner.html) to free memory or decrease an object's refcount. Cleaners are triggered during garbage collection of a Java instance. However, Java doesn't guarantee when, and if, the GC will run, and what it will clean, leading to memory leaks.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwharm%2Fjava-gi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjwharm%2Fjava-gi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwharm%2Fjava-gi/lists"}