0.11.0

Java-GI 0.11.0 features a lot of improvements and bugfixes all over the board.

What's Changed

Improvements:

• Java-GI 0.11.0 upgrades the Java bindings to the GNOME 47 platform versions. Read the What's new for developers section of the GNOME 47 Release Notes for an overview of the changes in this GNOME release.
• The GListModel interface has been made generic in Java: ListModel<T extends GObject>. The entire hierarchy of classes and interfaces that implement GListModel is now generic as well.
• Furthermore, the ListModel interface now extends java.util.List, so all list models can now be used as a Java collection (enhanced for loop, process with stream(), ...).
• #123: An additional no-argument constructor has been added to classes that have ambiguity between the default MemorySegment-constructor and another constructor with one (optional) parameter, when passing null. To pass null, users had to cast it. The new constructors resolve this. (Thanks to David Goodenough for reporting this.) Example:

// Old
var frame = new Frame((String) null);

// New
var frame = new Frame();

• #126: It is now possible to connect signals from Builder objects. For example:

var button = Button.builder()
        .setLabel("Close")
        .onClicked(window::close)
        .build;

• The Gtk functions StyleContext.addProviderForDisplay and removeProviderForDisplay have been copied to Gtk.styleContextAddProviderForDisplay and Gtk.styleContextRemoveProviderForDisplay because the StyleContext class is deprecated. The functions can now be called from the Gtk class to avoid deprecation warnings.
• Gtk composite template classes are now registered with TemplateTypes.register(class) instead of the old Types.register(class). In previous java-gi versions, there were two Types classes, one in GObject and one in Gtk (to register template classes), and users had to carefully import the correct one. Renaming the Gtk Types class to TemplateTypes will make the distinction clear. The old class is still available in this release, but has been deprecated and will be removed in an upcoming release.
• Many functions that required closure parameters now expect callback methods (or lambdas). This makes much more sense in a statically-typed language like Java. (Technically this means that when regular functions in GObject-Introspection are "shadowed by" a _with_closures function, we ignore the "shadowed by" annotation.)
• #129: A new API has been added to create GObject property bindings with transformations. It works the same as in Gtk-rs: The second example on this page would look like this in Java:

button1.<Integer, Integer>bindProperty("number", button2, "number")
        .transformTo(n -> n + 1)
        .transformFrom(n -> n - 1)
        .bidirectional()
        .syncCreate()
        .build();

• #131: Java-GI now contains a custom org.gnome.glib.HashTable wrapper class for GHashTable that implements the java.util.Map<K,V> interface. The keys and values can be strings, pointers (MemorySegments in Java), or heap-allocated classes/structs (i.e. anything that implements the Java-GI Proxy interface). The class is not meant to be used instead of java.util.HashMap, but will help Java developers work with native functions that return or expect a GHashTable.
• #139: The API to manually override a GObject virtual method with a Java lambda has been removed. It is still possible to override a virtual method with a java.lang.reflect.Method parameter (as used by Types.register(classname)). Furthermore, no accessors will be generated anymore to directly get/set the parent_class field of typeclasses. These APIs were unsafe to use (to put it mildly) and with these changes, the amount of generated code in Java-GI has been reduced significantly.
• #140: Trailing flag parameters can now be set with either a Set or varargs. For example, to create a new application, use one of these two constructors:

public Application(@Nullable String applicationId, Set<ApplicationFlags> flags);
public Application(@Nullable String applicationId, ApplicationFlags... flags);

• #141: It is now possible to specify the name of the namespace for your own GObject-derived classes in package-info.java with the new @Namespace(name="...") annotation. The namespace name will be prefixed to the class name.
• Improved parameter references in generated Javadoc.
• All code examples on the website are now available in both Java and Kotlin.

Fixes:

• #106: The different length of long native data types on Windows (long is 32-bit) versus Linux and macOS (long is 64-bit) is now fully implemented in Java-GI. The generated Java API supports the lowest common denominator (int), and casts to the correct native datatype at runtime. Classes, interfaces and structs with long fields use two separate MemoryLayouts in Java internally that contain the correct alignment and padding for the applicable platform.
• #117: Fixed a ClassCastException when casting the ListModel items returned by File.openMultipleFinish() to File. (Thanks @SudoDios for reporting this.)
• The wrapper classes for GList and GSList now properly free the list items after use.
• #120: Fixed a crash when using variadic functions on macOS.
• Improved the MemoryLayout generator to correctly handle nested structs and unions.
• #124: Copy structs and boxed types when returned from a native function without ownership transfer. This will call the copy or ref function defined for that type (or g_boxed_copy for boxed types). This prevents a segfault when the struct is disposed somewhere else while Java is still using it.
• #125: Improve memory management for methods with callback parameters that have a DestroyNotify callback.

Miscellanious:

• The allocate() factory methods on struct/boxed types have been removed. These methods were replaced by constructors and had already been deprecated in the previous release.
• The Gtk "Getting Started" guide has been ported to Java, and is now available on the Java-GI website, with all example code.
• Two new examples were added to the java-gi-examples repository: ColumnViewDatagrid and Spacewar.

Availability and dependencies:

• The new release is available on Maven Central.
• Java-GI requires OpenJDK 22 or later.
• The bindings are based on the GNOME 47 libraries. These need to be installed.

Full Changelog: 0.10.2...0.11.0

0.10.2

This release contains small bugfixes and enhancements.

What's Changed

Fixes:

• #104: Fixed loading native libraries built by MSVC (thanks @Kontiterit)
• #105: Fixed the GitHub action to build Gtk Windows libraries (thanks @JFronny)
• #103: Fixed handling of toggle references in async code (thanks @pontaoski)
• #111 and #113: Fixed crash caused by incorrect ListModel ownership handling (thanks @JFronny, @SudoDios and @badcel)
• Improved the toggle reference functionality to be faster and thread-safe
• Fixed double ref of initially unowned (i.e. floating) objects
• Removed an unused Cleaner action that was attached to all GObject instances

Improvements:

• Functions in enumerations where the first parameter is the enumeration type itself, will now be available in Java as an instance method on that enumeration. For example, EventType.getFlags(EventType.TAG) has changed to EventType.TAG.getFlags().
  The applicable functions are auto-detected by the Java-GI bindings generator. The functions that have been changed in this release are listed here.
• In the Javadoc of all signal connect methods (starting with "on...", like Button.onClicked()), a link has been added to the declaration of the signal handler method prototype. No more need to guess the expected callback parameters!
• Error messages when registering a Java class as a new GType have been improved to log the relevant error cause.

This release is based on OpenJDK 22 and GNOME 46. The new release is available on Maven Central.

Full Changelog: 0.10.1...0.10.2

GTK Natives for 4.15.1

libraries

Add links to IDEs to website

0.10.1

This is a bugfix release.

What's Changed

• Fixed bug #17 - Nested arrays are unsupported: Java-GI now supports functions returning String[][]
• Fixed bug #101 - Gio Files aren't GObjects: The default superclass for interface instances (when not specified in the prerequisites) has been changed back to GObject
• Testcases were added for string and array marshaling; this uncovered several bugs that are now fixed
• An unnecessary null-check in the generated memory-address-constructors has been removed
• GIR files were updated to the latest GNOME 46 versions

The new release is available on Maven Central.

Full Changelog: 0.10.0...0.10.1

0.10.0

What's Changed

Java-GI has now been upgraded to the latest version of the "Panama" Foreign Function & Memory API (JEP 454), that was released with OpenJDK 22. As a result, Java-GI doesn't depend on OpenJDK preview features any longer!

Additionally, the bindings were updated to the latest GNOME 46 release.

A number of other changes:

• New Java classes were added for GList and GSList, that implement java.util.List so they are very easy to use.
• Flag parameters have been changed from int constants to EnumSet. This means you pass flag parameters using Set.of(flag1, flag2, ...) instead of the custom or() and combined() methods that existed previously.
• A number of fixes and improvements were applied to the Javadoc generator.
• Method handles are now generated as final static fields, to allow inlining by the jit compiler, improving performance.
• Native libraries are now loaded using the platform-native shared library loader (dlopen on Linux) so in many cases the Java library path doesn't need to be manually updated anymore.
• Several bugs with memory management and caching were fixed. Thanks to @BwackNinja for the detailed reports.
• Interface instances are now derived from TypeInstance instead of GObject (unless specified otherwise in the prerequisites).
• The gircore/gir-files repository is now included as a git submodule.
• The website was improved and uses a more modern theme.

Full Changelog: 0.9.2...0.10.0

0.9.2

This release contains a bugfix for Gtk composite template classes.
Special thanks to @EliasDevis for logging this issue.

This release is based on OpenJDK 21 and GNOME 45.

Full Changelog: 0.9.1...0.9.2

0.9.1

This release is still based on OpenJDK 21 and GNOME 45. It contains bugfixes and a number of improvements.

Special thanks go to @pontaoski and @Tennessene for logging issues and testing fixes.

What's Changed

Fixes:

• Fixed image URL prefixes in generated Javadoc.
• Fixed allocating and accessing nested record types.
• Fixed overriding protected methods in custom GObject-derived classes.
• Fixed issues with generating boxed types, that prevented generating bindings for spice-client-glib.
• Gtk class CustomLayout was removed. This type is not meant to be used in language bindings.
• Removed all "...Private" types from the generated bindings again (this was a regression in 0.9.0).

Improvements:

• Added constructors to record types, to replace the existing allocate methods.
• Added constructor overloads without an Arena parameter, defaulting to Arena::ofAuto.
• Added a test method to the Bitfield base class, to test if one or more flags are set; added a better Bitfield::toString as well.
• Alias types now have a from method to "cast" an alias from its target type.

Minor enhancements:

• Renamed GErrorException::getGError() to ::toGError(), the old method is marked deprecated
• Better Javadoc descriptions for packages
• Added support for Alias<MemorySegment> parameters (like GstClockID).

Full Changelog: 0.9.0...0.9.1

Please log a GitHub issue or join java-gi:matrix.org if you encounter problems with this release.

0.9.0

This release has been built with a completely rebuilt code generator, based on JavaPoet. The output should be the same as the previous version, save for some bugfixes that were done during testing. The only API changes are:

• Any changes to the GIR files in the gir-core repository since Java-GI 0.8.1 was released. These changes should be really minor, because the GIR files were not updated beyond the supported point-releases listed in the README.
• the deprecated builder setter syntax has been removed
• the deprecated struct allocate() methods that default to an "auto" allocator have been removed
• the deprecated static factory methods with new prefixes have been removed

These removals were all announced, and explained, in the Java-GI 0.8.0 release notes.

Even though I tried to test this release as well as I could, there can be bugs/regressions compared to previous releases. Please log any issues you encounter. As a fallback, it's possible to keep using release 0.8.1.

Full Changelog: 0.8.1...0.9.0

As always, the release is available on Maven Central.

0.8.1

This is a bugfix release. In specific cases (specifically when Java-GI patches a method return type), it was impossible to chain up from a derived class to a method in a superclass. This has now been resolved. Details in PR #81.

Full Changelog: 0.8.0...0.8.1

0.8.0

This release upgrades the Java bindings to OpenJDK 21! This is an incompatible change from Java-GI 0.7.x, because the Panama FFI API changed significantly since JDK 20. The JDK 21 version (JEP 442) is the last preview version though; in JDK 22 the API will be final!

Kotlin users must upgrade to Kotlin 1.9.20 or newer if they want to use Java-GI 0.8.0, because older Kotlin releases are incompatible with JDK 21.

Notable changes:

GNOME 45

All libraries have been upgraded to the versions of the GNOME 45 SDK and Freedesktop SDK 23.08. See the README.md for the exact version numbers.

Allocate structs with an Arena

The Panama FFI in its current form heavily uses memory arenas to manage allocation lifetimes. Users can choose between different arenas, depending on your use case. Therefore, the allocate() methods generated by Java-GI for record (struct) and union types now expect an Arena as the first parameter.

Example:

try (var arena = Arena.ofConfined()) {
    var red = RGBA.allocate(arena, 1.0, 0.0, 0.0, 0.0);
    // memory is now allocated
}
// memory is now deallocated

var blue = RGBA.allocate(Arena.ofAuto(), 0.0, 0.0, 1.0, 0.0);
// memory will be deallocated when the variable is garbage collected

var green = RGBA.allocate(Arena.global(), 0.0, 1.0, 0.0, 0.0);
// memory will be allocated during the entire application runtime

Read the Arena documentation for more information.

To ease the transition, the old allocate() methods without an Arena parameter are still available. These methods use an Arena.ofAuto() behind the scenes. Dealing with native memory deallocations during GC is rather ugly, so I don't want users to think this is the default option. Therefore, these methods have been marked as deprecated, and will be removed in the next Java-GI release.

Property names will be inferred by default

In a GObject-derived class, you can define custom properties with a @Property annotation on the getter and setter methods. With Java-GI 0.8.0, the name parameter of the annotation has become optional. If you don't specify a name, it will be inferred from the getter and setter method name (converting setMyProperty to my-property).

Builder syntax has changed

The setter methods in the Builder classes now start with a set... prefix. This allows the builders to be used as Java Beans, allowing a much nicer property assignment syntax in Kotlin. The old setters are still available, but deprecated, and will be removed in the next Java-GI release.

Shorter constructor names

The new prefix in named constructors doesn't really serve a purpose in Java, and has been removed. As an example, gtk_button_new_with_label() will no longer be available as Button.newWithLabel(), but Button.withLabel(). As with the other API changes, the old syntax (Button.newWithLabel()) is still available, but deprecated, and will be removed in the next Java-GI release.

Improved HarfBuzz type names

HarfBuzz types have a "_t" postfix in C, which was previously mapped to Java classes like FontT. The trailing "T" is now gone.

Improved handling of callback memory allocations

The Panama FFI needs an explicit memory allocation to a expose Java callback method to native code. These are now deallocated automatically, as specified in scope attribute in GObject-Introspection.

Improved binding of virtual methods

In previous versions, Java-GI mapped virtual methods to regular public Java methods. This is incorrect; virtual methods are not designed as an API, but can be used to "chain up" when implementing a derived class. This is why in PyGObject for example, virtual methods have a do_ prefix to prevent confusion with regular methods. In Java-GI 0.8.0, virtual methods are now exposed with protected visibility. You can "chain up" using the asParent() API that was implemented in Java-GI 0.7.0.

Upgraded and improved Cairo bindings

Not part of Java-GI, but related: The manually developed cairo bindings have also been upgraded to JDK 21, and now also support user-defined fonts.

More details in the PRs:

• Inferred property names by @jwharm in #73
• Upgrade cairo to 1.18.0 by @jwharm in #74
• Port to JDK 21 by @jwharm in #75
• Callback lifetimes by @jwharm in #76
• Use setter syntax in builder classes by @jwharm in #77
• Generate better Harfbuzz type names by @jwharm in #78
• Improve virtual methods by @jwharm in #79
• Shorter constructor names by @jwharm in #80

Full Changelog: 0.7.2...0.8.0