QML Hot Reload with Felgo Live is a hot code reload technology for QML & JavaScript code, with Qt & Felgo projects. It can be used with applications developed and deployed on Mobile, Desktop, Embedded and Web platforms. You can review your code changes inside the running application, on any platform.
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.
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!
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.
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. 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, download the Felgo Developer App for iOS or Android.
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 Developer App for iOS and Android.
Select Connect Desktop in the app and enter the Server ID of the Felgo Live Server you want to connect to. Each Live Server instance has a unique server identifier in the local network. It is displayed
prominently in the bottom-left of the Felgo Live Server window.
Tap Connect 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.
The Live Client remembers the identifiers of successful connections, creating a list of hosts that you can easily choose from.
Note: 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.
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.
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 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.
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.
The Felgo Live Client shows your app when you use Hot Reloading. It will reload your app after every code change. 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, download the Felgo Developer App for iOS or Android.
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.
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.
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.
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.
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.
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.
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.
You don’t need to install native mobile SDK for Android or iOS to develop and test your apps on mobile phones.
Test Felgo Plugins like Admob Ads, Facebook Login, Google Analytics, Firebase or push notifications. With Felgo Live you can skip the individual setup steps.
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.
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 project file
Open the CMakeLists.txt file of your project and add the following lines:
find_package(FelgoLive REQUIRED) target_link_libraries(appCppBackendCharts PRIVATE FelgoLive)
The Felgo demos and project wizards already contain comments with these settings that you can directly use.
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.
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 qmlRegisterType<MyQMLType>("com.yourcompany.xyz", 1, 0, "MyQMLType"); // … }
Use your custom QML type anywhere in your QML files:
import com.yourcompany.xyz // … 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 project configuration and the main.cpp file, you only need to uncomment them!
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.
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.
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 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 NavigationStack { AppPage { 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.
