Integrate Felgo with Existing Applications

With Felgo you can create powerful standalone apps and games for multiple platforms. It is however also possible to integrate Felgo content into existing apps. You can load complete QML files with all Felgo features in Android and iOS apps. This guide explains the necessary steps to integrate QML with existing applications.

Use Cases

Integrating Felgo and QML in existing native apps has many beneficial use cases:

  • Implement parts of your app or game in QML. You can load content created with QML as one or many single screens in your app. This way you can implement your logic with the power of QML while still using the native look-and-feel and navigation concepts of your platform.
  • Show QML content as sub-views inside other screens. You can leverage the simplicity of QML for smaller parts of your app or game's UI.
  • Load a complete Felgo-powered app or game from the platform's IDE. You can skip installing the Qt Creator IDE and just implement a Felgo application using Android Studio or Xcode.

Example Applications

You can find examples of integrating Felgo and QML with existing apps on our Github page:


Project Setup

First set up your project to enable loading QML content from a native Android application.

Felgo Dependency

Add the vplay-android dependency in your build.gradle file:

 dependencies {
   implementation 'net.vplay:vplay-android:2.18.1'

Also add the Felgo Maven repository at the repositories block:

 repositories {
   maven { url '' }

Activity Base Class

Integrating QML content in your Android application requires a custom Activity base class. Extend any Activity where you would like to show QML content from VPlayAndroidActivity:

 public class MyQmlActivity extends VPlayAndroidActivity {

  public void onCreate(Bundle savedInstanceState) {
    // more Activity setup

Any other Activities that do not show QML content do not require a special base class.

Add QML Files to Your Project

You can load QML files from anywhere. All you need is the text content of the QML file. This lets you even load QML files from the web at runtime.

The most common use case is loading QML files from your project assets. To do so, place your .qml files under your projects assets directory (usually <project-dir>/src/main/assets). You can also use subfolders inside assets and reference files relatively from within QML.

Load QML Content

You can load any QML content using the class VPlayAndroidFragment. You can add an instance of the Fragment in code or in a layout XML file.

Using a Layout XML File

You can add VPlayAndroidFragment to any layout .xml file:


This loads the file qml/Main.qml from your project assets.

Using FragmentManager

To programmatically add a VPlayAndroidFragment to an Activity, you can use FragmentManager:

 void loadQml() {
   try {
         .replace(, new VPlayAndroidFragment()
                 .setQmlSource(getApplicationContext(), "qml/Main.qml"),
   } catch (IOException ex) {
     // QML file not found
     Log.w("MainActivity", "Could not load QML file", ex);

Here is the ID of an existing view to place the new Fragment into. This loads the file qml/Main.qml from your project assets. You can also load content from other places.

Use the method VPlayAndroidFragment.setQmlSource(Context context, URI source) to load QML from a local file. The source URI should start with file://. In this case, relative resource lookup within QML starts at the source file's directory.

Use the method VPlayAndroidFragment.setQmlContent(String qmlContent, String qmlBaseUrl) to load QML content directly from a source string. The paramater qmlBaseUrl represents a virtual base URL for a relative resource lookup. As an example, you can set it to "assets:/qml/subdir/Main.qml" to start the lookup within QML at the "qml/subdir" directory inside assets.


Project Setup

First set up your project to enable loading QML content from a native iOS application.

Initialize CocoaPods

You can add the Felgo dependency to an existing Xcode project using CocoaPods. If you have not yet used CocoaPods, you can install it with Homebrew from terminal:

 $ brew install cocoapods

If your project does not yet use CocoaPods, you can add it via terminal. Execute the following command in your Xcode project root:

 $ pod init

This creates a file named Podfile in the same directory.

Felgo Dependency

Add the VPlayIOS dependency in your Podfile:

 target 'MyIOSApp' do
   # more dependencies

   pod 'VPlayIOS', :git => ''

Afterwards, update CocoaPods dependencies:

 $ pod install

This generates a file called <project-name>.xcworkspace. To use CocoaPods, open this file in Xcode instead of the <project-name>.xcodeproj.

Initialize the Felgo Runtime

Start the Felgo runtime before QML content can be used. You can do this, for example, in your AppDelegate's didFinishLaunchingWithOptions method. When your app terminates, you can quit the Felgo Runtime again:

 #import "VPlayIOS.h"

 @implementation AppDelegate

 - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

   // other code ...

   [[VPlayIOS sharedInstance] start];

   return YES;

 - (void)applicationWillTerminate:(UIApplication *)application {

   // other code ...

   [[VPlayIOS sharedInstance] quit];


Add QML Files to Your Project

You can load QML files from anywhere. All you need a URI to the QML file. This lets you even load QML files from the web at runtime.

The most common use case is loading QML files from your project resources. To do so, add your .qml files to your project resources in Xcode. You can also use subfolders inside resources and reference files relatively from within QML.

Add Felgo View

You can display QML content using the class VPlayIOSView. You can add an instance of the view in code or in an interface builder file.

Using Interface Builder

You can add VPlayIOSView using the Xcode Interface Builder. Add an empty View to your interface and set the custom class to VPlayIOSView:

To access the view from source code, add an IBOutlet property to your ViewController implementation:

 #import "VPlayIOSView.h"

 @interface ViewController

 @property (weak, nonatomic) IBOutlet VPlayIOSView *vplayView;


You can then add a referencing outlet by right-clicking the view in Interface Builder:


You can also add VPlayIOSView to another view in code. Example from within a ViewController implementation:

 #import "VPlayIOSView.h"

 @interface ViewController()

 @property (strong, nonatomic) VPlayIOSView *vplayView;


 @implementation ViewController

 // more methods...

 - (void)addQMLView {
   self.vplayView = [VPlayIOSView new];
   self.vplayView.frame = self.view.bounds;
   [self.view addSubview:self.vplayView];


Load QML Content

To load QML content, assign a URI to the property VPlayView.qmlSource. You can use any URI, for example to a web resource, a local file or a project resource.

This example loads Main.qml from your project resources:

 - (void)loadQML {
   self.vplayView.qmlSource = [[NSBundle mainBundle] URLForResource:@"Main" withExtension:@"qml"];

You can also load QML directly from an NSData or NSString object. For this, assign to the property VPlayView.qmlContent:

 - (void)loadQML {
   // obtain QML content from anywhere...
   NSString *content = @"import Felgo 3.0; App { AppText { text: 'Direct QML content' } }";

   self.vplayView.qmlContent = [content dataUsingEncoding:NSUTF8StringEncoding];

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
create apps
create games
cross platform
native performance
3rd party services
game network
level editor
easiest to learn
biggest time saving
best support