On this page

Qt Bridges - Java/Kotlin

Qt Bridge is a framework that allows you to write QML applications using Java/Kotlin. It connects the Java backend to QML frontends.

Getting Started

Setting up development environment

Prerequisites

Before generating or running a Qt Bridge project, ensure the following tools are installed:

  • Java Development Kit: OpenJDK 21 or newer
  • Gradle: Gradle 8.14.2 or newer

Validate your environment:

java --version
gradle --version

Installation

Use the starter script to quickly generate a new Qt Bridge project with all required files and directory structure.

Download the starter script alongside settings.gradle:

curl -O 'https://code.qt.io/cgit/qt/qtbridge-java.git/plain/examples/starter/qtbridge.starter.gradle.kts?h=dev' \
     -O 'https://code.qt.io/cgit/qt/qtbridge-java.git/plain/examples/starter/settings.gradle.kts?h=dev'

Check usage or help

gradle --init-script qtbridge.starter.gradle.kts usage

Generate a project

Run the initialization script using Gradle. This will create a new project in your current directory.

Default generation (Java):

gradle --init-script qtbridge.starter.gradle.kts

Custom generation (Kotlin):

 gradle --init-script qtbridge.starter.gradle.kts \
 -PprojectName=MyAwesomeApp \
 -PpackageName=com.company.app \
-Planguage=kotlin
Generation Parameters

The project generator accepts the following Gradle properties (-Pflags):

projectNameApplication name (default:MyApp)
packageNameJava/Kotlin base package (default:com.example)
languageSource language, either java or kotlin (default:java)
Generation Output

The starter script produces a fully configured Qt Bridge project with a recommended folder structure:

\c MyAwesomeApp/
├── src/
│   └── main/
│       ├── kotlin/           (or java/)
│       │   └── com/
│       │       └── company/
│       │           └── app/
│       │               ├── Main.kt            (or Main.java)
│       │               └── Controller.kt      (or Controller.java)
│       └── qml/
│           └── main.qml
├── build.gradle.kts
└── settings.gradle.kts

Running

After generating the project, navigate into the new directory and run it:

cd MyAwesomeApp
gradle MyAwesomeApp

Tutorials

The following snippet illustrates a simple Java backend example:

// Registers this class as QML singleton
@QMLRegistrable(singleton = true)
public class FruitBasket {
    // Establishes a binding to a callback interface that is used to emit signals or notifications
    // from Java to QML. This allows QML to react to specific events like validation failures or updates.
    public interface QmlCallback {
        void basketSold(Integer price);
        void basketStolen();
    }
    @QMLSignals
    QmlCallback qmlCallback;

    // A QtListModel of strings, bridged to QML as a QAbstractListModel.
    // This allows it to be used in model-driven QML components
    public final QtListModel<String> fruitList =
            new QtListModel<>(new ArrayList<>(Arrays.asList("Mango", "Kiwi")));

    // An Integer bridged to QML. Can be used on QML-side as a standard read-write property
    public QtProperty<Integer> fruitBasketPrice = new QtProperty<>(24);

    {
        // Observe fruitList changes
        fruitList.onSizeChanged(() -> System.out.println("List size changed to: " + fruitList.size()));
        // Observe price changes
        fruitBasketPrice.onValueChanged(() -> System.out.println("Fruit basket price changed"));
    }

    // Function that is invokable from QML
    public void sellAllFruits() {
        System.out.println("Selling all fruits");
        // Inform QML that sale was a success
        qmlCallback.basketSold(25);
    }

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.