Skip to content

Commit

Permalink
Update website for version 0.7
Browse files Browse the repository at this point in the history
  • Loading branch information
jwharm committed Sep 15, 2023
1 parent 9452bbf commit c6abb6f
Show file tree
Hide file tree
Showing 3 changed files with 55 additions and 34 deletions.
2 changes: 1 addition & 1 deletion website/docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Please note that Java-GI is still under active development. Feedback is welcome.

## Supported libraries

Java-GI version 0.6.1 has been tested with the following libraries:
Java-GI version 0.7 has been tested with the following libraries:

| Library | Version |
|---------------|---------|
Expand Down
48 changes: 48 additions & 0 deletions website/docs/register.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,54 @@ public void init() {
}
```

## Signals

Java-GI 0.7 added support for custom signals in Java classes that extend GObject. For example:

```java
public class Counter extends GObject {

// register the type
private static final Type gtype = Types.register(Counter.class);

// define signal
@Signal
public interface LimitReached {
public void run(int limit);
}

public void count() {
num++;
if (num == limit) {
// call GObject.emit(signalName, args...) to emit the signal:
emit("limit-reached", limit);
}
}

...
}
```

The "limit-reached" signal is defined with a functional interface annotated as `@Signal`. The method signature of the functional interface is used to define the signal parameters and return value. The signal name is inferred from the interface too (converting CamelCase to kebab-case) but can be overridden.

You can connect to the custom signal, like this:

```java
counter.connect("limit-reached", (Counter.LimitReached) (limit) -> {
System.out.println("Limit reached: " + limit));
}
```

Because the signal declaration is an ordinary functional interface, the declaration in the above example can also be declared as an `IntConsumer`:

```
@Signal
public interface LimitReached extends IntConsumer {}
```

It's also possible to set a custom signal name and optional flags in the `@Signal` annotation, for example `@Signal(name="my-signal", detailed=true)` to define a detailed signal.


## Examples

In [this example application](https://github.com/jwharm/java-gi-examples/tree/main/PegSolitaire), the inner class `SolitairePeg` is registered as a GObject subclass that implements the `Paintable` interface.
39 changes: 6 additions & 33 deletions website/docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,33 +12,19 @@ Make sure that the native GLib, Gtk and/or GStreamer libraries are installed on

* GStreamer: Follow the [installation instructions](https://gstreamer.freedesktop.org/documentation/installing/).

Next, add the dependencies as described on [JitPack.io](https://jitpack.io/#jwharm/java-gi/0.6.1). For example, if you use Gradle:
Next, add the dependencies. For example, if you use Gradle:

```groovy
allprojects {
repositories {
mavenCentral()
maven { url 'https://jitpack.io' }
}
repositories {
mavenCentral()
}
dependencies {
// For the @Nullable/@NotNull annotations
compileOnly 'org.jetbrains:annotations:24.+'
// Include the libraries you want to use.
implementation 'com.github.jwharm.java-gi:glib:latest.release'
implementation 'com.github.jwharm.java-gi:gtk:latest.release'
implementation 'com.github.jwharm.java-gi:adwaita:latest.release'
implementation 'com.github.jwharm.java-gi:gstreamer:latest.release'
implementation 'com.github.jwharm.java-gi:gtksourceview:latest.release'
implementation 'com.github.jwharm.java-gi:webkitgtk:latest.release'
implementation 'io.github.jwharm.javagi:gtk:0.7'
}
```

The `glib` jar contains GLib, GIO, GObject and GModule, and the Java-GI base classes. You should always include it. The other jars only need to be included if you intend to use that specific functionality.

The `gtk` jar contains, besides Gtk, also the bindings for Gdk, GdkPixbuf, Graphene, HarfBuzz and Pango. Furthermore, it depends on the [cairo-java-bindings](https://github.com/jwharm/cairo-java-bindings). Maven or Gradle will download the cairo dependency from JitPack.io automatically.
This will add the Gtk bindings to the application's compile and runtime classpath. Other libraries, like `webkit`, `gst`, `adw` and `gtksourceview` can be included likewise. The complete list of available libraries is available [here](https://github.com/jwharm/java-gi/tree/main/modules).

## Application code

Expand Down Expand Up @@ -93,7 +79,7 @@ Build and run the application with the following parameters:

* While the Panama foreign function API is still in preview status, set the `--enable-preview` option both when **compiling** and **running** your application.

* To suppress warnings about native access, also add `--enable-native-access=ALL-UNNAMED`. For module-based applications, add `--enable-native-access=org.gnome.glib` (and all other modules that you use) instead.
* To suppress warnings about native access, also add `--enable-native-access=ALL-UNNAMED`.

* If you encounter an error about a missing library, override the java library path with `"-Djava.library.path=/usr/lib/..."`

Expand All @@ -102,16 +88,3 @@ See [this `build.gradle` file](https://github.com/jwharm/java-gi-examples/blob/m
## Java library path

If you see an error about a missing library, make sure that all dependencies are installed, and available on Java library path (the `"java.library.path"` system property). If necessary, you can override the Java library path with the `-Djava.library.path=` JVM argument, for example: `-Djava.library.path=/lib/x86_64-linux-gnu` on Debian-based systems.

## Modules

For module-based applications (with a `module-info.java` file), the following modules are available:

* org.gnome.glib
* org.freedesktop.gstreamer
* org.gnome.gtk
* org.gnome.adwaita
* org.gnome.gtksourceview
* org.gnome.webkitgtk

Each module transitively exports its dependencies, so when you want to create a Gtk application, you only need to add `requires org.gnome.gtk;` to your `module-info.java` file.

0 comments on commit c6abb6f

Please sign in to comment.