QML Hot Reload with Felgo Live

What is QML Hot Reload?

Focus on Development - Stop Waiting for Build, Package and Deployment Steps

Hot Reload with Felgo Live allows you to change your QML & JavaScript source code and view the result in realtime. It applies QML, JavaScript and asset changes instantly on every connected device, immediately after saving. This reduces the long waiting times for build and deployment steps to only a couple of seconds.

Hot Reload applies changes in your source code without losing the state of your application. If you are currently working on a sub-page, you will not have to navigate back to it after every change, you will stay exactly where you are in your app.

You can even test your projects on mobile, without installing native mobile SDKs, only by installing the Felgo Live App on your device.

Save Time - Deploy and Test in Seconds

Felgo Live reduces deployment time, from several minutes to a couple of seconds. It deploys your code changes to all connected devices, automatically after saving. Save more than 95% of time on deployment for testing!

Iterate on a Specific Screen without Restarting Over and Over Again

Work on a single screen until it is pixel perfect, without ever leaving it. Felgo Live will fully preserve the application state and apply the change directly in your running app. No need to navigate back to the sub-page or popup that you are currently working on after each change.

You can learn more about the benefits of QML Hot Reload for Felgo and Qt here.

How to use QML Hot Reload with Felgo Live

Felgo Live consists of two components, the Live Server and the Live Client. The Live Server will observe your project's source code on your development machine. On every code change, it sends the changed QML and JS files to each connected Live Client.

The Felgo Live Client shows your app while you use Hot Reloading. It reloads your app after every code change. If you want to view your app on your mobile, you can download the Felgo Live Scripting app for iOS and Android. You can connect multiple Live Clients to your Live Server at the same time. This allows you to test your app on all your devices while developing, without having to install any native mobile SDK or wasting time on deployment.

The Felgo Live Client for Desktop is already part of the Felgo installation. For mobile, you can download the pre-built Live Client here:

1. Start Felgo Live

You can start Felgo Live for your active project, by clicking on the LIVE-Run button in Qt Creator.

This will open the Felgo Live Server and a desktop Live Client for local testing. The desktop client will automatically connect to the server.

2. Connect Additional Live Clients

If you want to connect your mobile devices, download and start the Felgo Live App for iOS and Android.

Select Connect Desktop in the app and accept the connection request in the Live Server. Felgo Live is using your local network, please make sure that all your devices are connected to the same local network.

You can also start a local instance of the Live Client on your development machine. Just click the "Run" button in the Live Server.

3. That's it!

Once you have connected a Live Client, it automatically loads your project. Every change to your source code will now be shown in real-time on any connected Live Client, as soon as you save your file.

Use QML Hot Reloading with custom C++ or Native Code

Refer to the Advanced Usage section to see how you can use the Felgo Live Module. This module allows you to use QML Hot Reloading together with custom C++, native code, or any Qt module that is not pre-configured in the provided Live Client apps.

How does Hot Reload with Felgo Live Work?

Basics & Live Reload

First we will look at the basics and the technique of a Live Reload, opposed to the new Hot Reload. Time for a quick detour to the basics of a Qt application. It consists of 2 main layers:

The C++ layer handles all the core functionality and does the heavy lifting. The C++ layer also contains the QML engine, which is able to load QML code at runtime. Thanks to the QML engine, you can reload the whole QML layer at runtime, without any compilation step.

This is exactly what happens with a Live Reload. When you hit save, your changed QML, JS and asset files are transferred to the Felgo Live Client, and the QML layer is reloaded.

All your custom C++ code however is part of the C++ layer. This code requires a build step to compile and deploy with the application. For this reason, you can add the Felgo Live Module to your own application, to use Hot Reload for QML together with your custom C++ and native code.

Hot Reload

Hot Reload takes this whole process even one step further. It detects exactly which parts of your QML files have changed. It then exchanges exactly those parts of the running application with the new QML content.

You can add and remove QML objects and set their properties in code while the app is running. You can also define new properties, signals and functions into existing QML objects. Basically all features of the QML language are supported by Hot Reload.

Felgo Live Server

The Live Server monitors your project source code and assets, to detect changes. It allows you to connect any number of Live Clients at the same time using your local network. After a change is detected in your project, the Live Server sends the changes to any connected Live Client.

You can connect any number of Live Clients to the Live Server. They show up as tabs on the top.

At the first start you already see the Desktop Client (1), which starts automatically if Auto Start (6) is enabled. You can also start it manually with the Start (3) button. You can configure the Desktop Client window to always stay on top by enabling Stay on Top (5).

When you connect a mobile Live Client, you can access its settings by selecting the corresponding tab (2).

On the bottom left of the Live Server you can access the settings menu (10). Here you can set which network adapter to use for Live Client connections.

Connected mobile clients offer some different options in the Live Server:

You can turn the Hot Reload (7) feature on or off. When enabled, any Live Client applies code changes while the app is running. Without Hot Reload, any code change triggers a full reload of the whole app or game window. Alternatively you can configure a Loader element to reload instead. You can also always manually trigger a Full Reload (8). Use this in case the Hot Reload state becomes inconsistent.

You can clear a Live Client's log window with the Clear Log (9) button. The log is also cleared before every reload. You can manually Disconnect (3) any Client. You can also do this action from the mobile device with a shake gesture. If you don't use a specific Live Client anymore, you can remove its tab entirely with the Remove (4) button.

Felgo Live Client

The Felgo Live Client shows your app when you use Hot Reloading. It will reload your app after every code change. If you want to view your app on your mobile, you can download the Felgo Live Scripting app for iOS and Android. You can connect multiple Live Clients to your Live Server at the same time. This allows you to test your app on all your devices while developing, without having to install any native mobile SDK or wasting time on deployment.

The Felgo Live Client for Desktop is already part of the Felgo installation. For mobile, you can download the pre-built Live Client here:

The Live Client contains all the most used Qt modules and Felgo Plugins. This allows you to test most features without the need to install the application in development on your mobile devices. It is also possible to use other features and plugins - the Felgo Live Module provides that functionality.

Benefits of Hot Reload

Benefits of Hot Reload over Live Reload

Hot Reload keeps your application running while it applies code changes. This means your app or game keeps its exact state when reloading. This helps speed up development even more.

Incremental UI building

You can build your user interface incrementally while navigating it at the same time, and iterate on any sub-page without navigating to it repeatedly. You can add navigation items, pages and sub pages and modify their content and immediately see the outcome on multiple platforms.

Catch errors early

Hot Reloading encourages you to save and test your source code frequently. After you change even a single line of code, you can hit save and immediately see the result. This way you can catch errors way earlier and speed up your overall development process.

Define interaction seamlessly

Hot Reload also allows you to add any form of interaction to the running QML application. You can add property bindings, signal handlers and regular JavaScript functions at any point to the QML tree. The new definitions are effective immediately.

Concurrent Testing on All Your Devices

You can connect as many devices as you want, and every single one is updated simultaneously. This allows you to test any change on different platforms and devices at the same time.

iOS Deployment from Windows & Linux

With Felgo Live, you can test your Felgo projects on your iPhone and iPad, even from Windows or Linux. No more need to ask your office neighbor with that shiny Mac, to build your application for iOS.

No Native SDKs Required

You don’t need to install native mobile SDK for Android or iOS to develop and test your apps on mobile phones.

Felgo Plugins without Additional Setup

Test Felgo Plugins like Admob Ads, Facebook Login, Google Analytics, Firebase or push notifications. With Felgo Live you can skip the individual setup steps.

Advanced Usage

C++ & Native Code - Build your own Live Clients with the Felgo Live Module

Some projects include custom C++ or native code. Those languages require a compilation step and cannot be reloaded directly with QML Hot Reloading.

Felgo provides the Live Client Module. You can use it to add QML live reloading features to your own application. This allows you to use all your C++ and native functionality, together with hot reloading for QML.

How to Build your own Live Client with Custom C++ and Native Code

With the new Live Client Module, you can add live code reloading to your own application in seconds. All you need to do is perform 2 simple steps:

1. Add the felgo-live config to your pro file

Open the *.pro file of your project and change the following line:

 CONFIG += felgo

to this:

 CONFIG += felgo felgo-live

Or you can also use 2 separate lines like this, so you can enable/disable the Live Client Module easier:

 CONFIG += felgo
 CONFIG += felgo-live

2. Start the Live Client instead of your project main QML file

Go to your project's main.cpp file and add the following line at the include section at the top:

 #include <FelgoLiveClient>

You do not want to load your project’s main QML file initially, instead you want to start as Live Client. Your project will then start with a connection screen and you can connect to the Live Server.

Remove the following 2 lines in your main.cpp file. You will need those lines for standard deployment or publishing later, so only comment them like this:

 // felgo.setMainQmlFileName(QStringLiteral("qml/Main.qml"));
 // engine.load(QUrl(felgo.mainQmlFileName()));

Now we can start the Live Client with one line of code. Add it just before the return statement at the end of the main function:

 FelgoLiveClient liveClient(&engine);

That’s it, you turned your own project into a Live Client. Build and run your project for any platform you want, Windows, macOS, Linux, Android or iOS.

Note: Run your application using the “Run” option in Qt Creator (the standard green run button)!

You can connect it to your Live Server just like the default Live Clients.

Tip: Disable the automatic start of the default Desktop Client in your Live Server, because you will use your own client instead!

To switch back to standard deployment, for example to publish your app, just undo the changes above.

Use Cases with Live Client Module

There also is a more detailed blog post about communication between C++ and QML. These are only short examples, to give you an idea of what you can do.

Add a Global C++ Object as a Context Property

You can make C++ objects accessible from anywhere in your QML files, with a context property.

Expose an object of your custom C++ class with a context property, e.g. in your main.cpp:

 #include "myglobalobject.h"

 // …

 int main(int argc, char *argv[])
 {
   // ...

   MyGlobalObject* instance = new MyGlobalObject();
   engine.rootContext()->setContextProperty("myGlobalObject", instance);

   // ...
 }

Now you can access your context property from anywhere inside your QML files.

 AppButton {
   text: "Do Something"
   onClicked: myGlobalObject.doSomething("with this text")
 }

You can find a full example including the C++ files here: How to Access a C++ Object from QML

Register your C++ Class as QML Type

Another option to communicate between C++ and QML, is exposing your C++ class as QML type.

Expose the QML type, e.g. in your main.cpp:

 #include "myqmltype.h"

 // …

 int main(int argc, char *argv[])
 {
   // …

   // MyQMLType will be usable with: import com.yourcompany.xyz 1.0
   qmlRegisterType<MyQMLType>("com.yourcompany.xyz", 1, 0, "MyQMLType");

   // …
 }

Use your custom QML type anywhere in your QML files:

 import com.yourcompany.xyz 1.0
 // …
 MyQMLType {
   id: myType
   someProperty: "someValue"
   onSomePropertyChanged: doSomething()
 }

You can find a full example including the C++ files here: How to Register your C++ Class as a QML Type

GitHub Example for using C++ with QML

You can also download this example project from GitHub. The Live Client Module integration steps are already prepared in the FelgoCppQML.pro and main.cpp files, you only need to uncomment them!

Download GitHub Example

Use All Felgo Plugins with Live Reload

Some plugins, like push notifications, rely on the app identifier of an application. With the Live Client Module, you will build your applications with your own app identifier set. This means you can use those plugins with Hot Reloading as well.

Full Reload

Hot Reload applies changes to your QML code at runtime. These changes are applied to the current state of the app or game. However, in some cases, a full reload is required. There are certain situations in which a Hot Reload is impossible, and a full reload will be performed automatically.

You can also choose to trigger a full reload manually. You can use this in case the Hot Reload state becomes inconsistent. Just click the "full reload" button in the Live Server.

Also some projects are naturally not well suited for Hot Reload. If your content is very dynamic and changes during runtime, Hot Reload could be undesirable. This is mostly the case for game projects. In this case you can just turn off hot reload entirely with the corresponding toggle button.

Felgo Live Reloader

A full reload means the Live Client must destroy and recreate the whole application window. For Felgo projects, this is the App or GameWindow instance.

In some projects the application window contains e.g. critical initialization code, that should not be rerun on every reload. It might be unnecessary or even undesirable to reload the whole window. Instead you can configure the Live Engine to reload the content of a QML Loader element. Just assign the property felgoLiveEngine.contentLoader, then a code change resets the Loader's content instead of reloading the window.

Example

To make use of the Reloader feature, you can set up your app or game similar to this:

Main.qml

 import Felgo 3.0
 App {
     Loader {
         id: myContentLoader
         source: "Content.qml"
     }

     Component.onCompleted: {
         // -> check if currently running in live client
         if(typeof felgoLiveEngine !== "undefined") {
             felgoLiveEngine.contentLoader = myContentLoader
         }
     }
 }

Content.qml

 import Felgo 3.0
 NavigationStack {
     Page {
         title: "Main content"

         // ...
     }
 }

With this setup, your app supports Hot Reload without reloading the window itself. The engine will only reload the content of the Loader, which contains Content.qml.

Note: Changes in Main.qml will now have no effect at runtime, since only the Loader content is reloaded.

Note: The Live Reloader only works if a Loader.source URL is used, not with a Loader.sourceComponent. This is because it needs to re-load the source QML file.

Voted #1 for:

  • Easiest to learn
  • Most time saving
  • Best support

Develop Cross-Platform Apps and Games 50% Faster!

  • Voted the best supported, most time-saving and easiest to learn cross-platform development tool
  • Based on the Qt framework, with native performance and appearance on all platforms including iOS and Android
  • Offers a variety of plugins to monetize, analyze and engage users
FREE!
create apps
create games
cross platform
native performance
3rd party services
game network
multiplayer
level editor
easiest to learn
biggest time saving
best support