Release 2.16.0: iPhone X Support and Runtime Screen Orientation Changes

Release 2.16.0: iPhone X Support and Runtime Screen Orientation Changes


Felgo 2.16.0 adds support for devices with notches like iPhone X. This allows to create mobile apps or games that look good on all modern devices and screens. With this update you can also change the screen orientation of your app at runtime. Felgo 2.16.0 comes with many improvements and fixes and is free to use.

Why You Should Update Your iOS App to Support iPhone X

The iPhone X features a big edge-to-edge display with a notch for the front camera and speaker. Also, hardware buttons at the front no longer exist. They got replaced by on-screen buttons and gestures provided by the OS.

Edge-to-edge Display iPhone X vs iPhone 8

Your existing iOS apps will come with black borders to not overlay areas with a notch or screen gestures:

App Support for iPhone X

To fully support iPhone X and let your app fill the whole screen, you can add an additional launch image for the iPhone X resolution. You should add one image with 2436 x 1125 pixels for landscape mode, and one with 1125 x 2436 pixels for portrait.

Note: The updated Felgo project wizards already come with the right configuration and images. You can create a new project and have a look how the asset catalog is set up.

However, if your app now covers the full screen of the iPhone X, some parts are covered or not accessible:

Fullscreen iPhone X App with Notch

The notch covers the top navigation bar in portrait mode and your page content in landscape mode. For both orientations, the area for the home swipe gesture overlaps your app at the bottom. Also note that the new screen comes with rounded corners.

To solve this problem, your app must know about the safe area of the screen. It is the part of your app, which is not covered by the notch or on-screen gestures:

Screen Inset of iPhone X Page in Portrait Mode

For example, the top navigation bar requires more space on iPhone X when in portrait mode. In landscape mode it looks a bit different. Your app UI then requires margins to the left and right, as well as a small inset at the bottom:

Screen Inset of iPhone X Page in Landscape Mode

How to Create iPhone X Apps with Felgo

Felgo Apps Support for Display Notches and Safe Area

The latest Felgo update 2.16.0 adds support for iPhone X and screens with notches. With Felgo, you do not require any extra code to let your app look good on iPhone X. With only a few lines of code, it is possible to create native iOS apps that look good on every device:

import Felgo 3.0
import QtQuick 2.0

App {
 // adds tab navigation
 Navigation {

   // first tab
   NavigationItem {
     icon: IconType.home
     title: "Main"

     // main page
     NavigationStack {
       Page {
         title: "Main"

         Rectangle {
           anchors.fill: parent // Rectangle fills whole Page
           color: "lightgreen"

           AppText {
             anchors.centerIn: parent // AppText is centered on Page
             text: "Safe Area"

   // second tab
   NavigationItem {
     icon: IconType.gears
     title: "Settings"

     // settings page
     NavigationStack {
       Page { title: "Settings" }


This is how the above example app looks like on an iPhone X:

Tab and Navigation Bar - iPhone X Support

Felgo components like Navigation and NavigationStack automatically support the safe area. They include extra margins for the tab bar and navigation bar if required. Your Felgo app will look good out of the box when using these components. The Page content also auto-aligns with the safe area of the screen. For devices without notches, your app will not show any extra margins or insets.

Optimize Your App UI for iPhone X

For most use cases, the default settings are fine to let your app look good on devices with and without a notch. If you want more control over how to display your content, you can disable the useSafeArea setting of each Page. You then have two options to work with the safe area:

  • Configure certain content items within the Page to align with the safe area.
  • Retrieve the actual safe area inset of the screen and layout items as required.

The following example deactivates the useSafeArea setting and shows both approaches:

import Felgo 3.0
import QtQuick 2.0

App {

 Page {
   useSafeArea: false // the page content can use all available space

   // fill whole page/screen with blue color (background)
   Rectangle {
     anchors.fill: parent
     color: "lightblue"

   // fill only safe area with green color (content)
   Rectangle {
     anchors.fill: parent.safeArea
     color: "lightgreen"

   // adaptive background to cover top inset area (or status bar area on devices without insets)
   Rectangle {
     width: parent.width
     height: > 0 ? : nativeUtils.statusBarHeight()
     color: "yellow"


Running this app on an iPhone X produces this result:

iPhone X Safe Area - Adaptive Layout

The Page content can now cover the full screen by default. You can use the safeArea property of the Page to align items with the safe area of the screen. The above example uses this property to fill the safe area with a green rectangle. This is where you can place your content items.

The nativeUtils.safeAreaInsets hold the actual safe area inset of the screen in pixels. Devices without notches do not have any insets and thus return 0. For iPhone X, the yellow rectangle will cover the top inset, which includes the status bar. The height is set to match the status bar if no inset is returned by With this simple switch it is possible to still support older devices.

The available safeAreaInsets properties are:

  • nativeUtils.safeAreaInsets.right
  • nativeUtils.safeAreaInsets.bottom
  • nativeUtils.safeAreaInsets.left

Developing adaptive user interfaces this way is very convenient. The following example shows how you could use nativeUtils.safeAreaInsets.left to add more indent for the cells of a list.

import Felgo 3.0
import QtQuick 2.0

App {

 ListPage {
   useSafeArea: false // the page fills all available space
   model: 50 // quick way to populate the list with 50 items

   // UI for cells of the list
   delegate: SimpleRow {
     text: "Item #"+index

     // set indent of the cells
     // matches the safe area inset or minimum 16 dp (if no inset required, e.g. in portrait mode or on older devices)
     style.indent: Math.max(nativeUtils.safeAreaInsets.left, dp(16))


With such simple additions, you can make sure that your app looks perfect on screens with and without safe area insets.

iPhone X Safe Area - Adaptive Layout - List Cell

You don’t need to add such tweaks for regular apps that offer the standard iOS UI with a navigation bar and tab bar. The Felgo page and navigation components look good on all devices and adapt their style automatically.

iPhone X Support for Felgo Games

Prepare Your Games for Displays with Notches

If not taken into consideration, the iPhone X notch or home gesture area can heavily affect the user experience of your game. Let’s say your game uses the bottom screen area to show some touch input controls. The iPhone X does not own a home button, so it uses a small area at the bottom for native touch gestures.

iPhone X UI - Game Controls

Your input controls thus become inaccessible, and your game essentially not playable. You do not want to show such critical game elements in parts of the screen that are not safe.

How to Use the Safe Area in Your Game Scenes

With iPhone X Support for Felgo Games, your game is kept within the safe area out-of-the-box. You can rely on the GameWindow and Scene components to only use the safe area on displays with notches.

import Felgo 3.0
import QtQuick 2.0

GameWindow {
 id: gameWindow

 Scene {
   id: scene

   // fills the full screen
   Rectangle {
     anchors.fill: parent.fullWindowAnchorItem
     color: "lightblue"

   // fills the safe area
   Rectangle {
     anchors.fill: parent.gameWindowAnchorItem
     color: "lightgreen"

   // fills the scene
   Rectangle {
     id: rectangle
     anchors.fill: parent
     color: "lightyellow"

     Text {
       text: "Scene"
       anchors.centerIn: parent


The Scene::gameWindowAnchorItem only covers the safe area on devices like iPhone X. With the new Scene::fullWindowAnchorItem, you can choose to use the full screen for some UI elements of your game Scene. The above example covers the full screen with a blue background, but keeps other game elements safe:

iPhone X Game Scene - Safe Area Landscape

The Scene scaling mechanism resizes the Scene to match the game window, which reflects the safe area. To let your game scene fill the whole screen, it is possible to deactivate the Scene::useSafeArea setting:

iPhone X Game Scene - Use Safe Area

To retrieve exact pixel insets of the safe area, you can use the NativeUtils::safeAreaInsets property.

With the default setup, most Felgo games will work fine on iPhone X with few simple additions. For example, to let your background image cover the scene’s fullWindowAnchorItem instead of the game window.

To make your background image big enough to fill the screen of iPhone X, the following sizes are suggested:

Image type Unmodified Scene size (3:2 ratio) Suggested Background Size
sd 480 x 320 694 x 360
hd 960 x 640 1388 x 720
hd2 1920 x 1280 2776 x 1440

You can find a Photoshop template with the suggested background size here.

Simulate iPhone X on Desktop

The addition of iPhone X support also brings a new entry to the resolution simulator on Desktop.

Resolution Menu iPhone X Simulation

The desktop simulation for iPhone X does not only include the correct resolution, it also covers the safe area insets:

iPhone X Desktop Simulation with Insets

This is a huge time-saver when developing for iPhone X. You can test how your UI looks on Desktop and switch resolutions at runtime. No need to deploy your app to different physical or virtual devices.

Set Screen Orientation At Runtime

You can now set the preferred screen orientation at runtime from within your QML code!

To specify the global orientation you can use the new property NativeUtils::preferredScreenOrientation. E.g. to lock and unlock your app or game to portrait orientation, you can use the following lines of code:

import Felgo 3.0
import QtQuick 2.0

App {

 Column {
   AppButton {
     text: "Lock to portrait"
     onClicked: nativeUtils.preferredScreenOrientation = NativeUtils.ScreenOrientationPortrait
   AppButton {
     text: "Reset default orientation"

     // Resets to the orientation defined in AndroidManifest.xml / Project-Info.plist
     onClicked: nativeUtils.preferredScreenOrientation = NativeUtils.ScreenOrientationDefault


Runtime Orientation Switch

You can also specify the orientation per page in apps, using Page::preferredScreenOrientation. Use this example code to show a page fixed to portrait mode:

import Felgo 3.0
import QtQuick 2.0

App {
 id: app

 NavigationStack {
   id: stack

   Page {
     id: page
     title: "Screen orientation test"

     AppButton {
       text: "Push portrait page"
       onClicked: stack.push(portraitPage)

 Component {
   id: portraitPage

   Page {
     id: page
     title: "Portrait page"
     preferredScreenOrientation: NativeUtils.ScreenOrientationPortrait

Orientation Switch - Page-specific Orientation

These properties only have an effect on iOS and Android and override the default screen orientation defined in your project’s Project-Info.plist and AndroidManifest.xml.

New Felgo Live Server for Live Code Reloading

The new Felgo Live Server offers an improved user interface and new features.

New Felgo Live Server UI

With the new AUTO START option, you can disable the desktop client from launching automatically. This is handy if you switch between your projects often, or only want to test your project on mobile.

You can now also clear the log output of each client individually.

Connect and Remove Mobile Clients

To connect your mobile device, you only need to download the Felgo Live Scripting app for Android or iOS, and click on Connect Desktop.

Felgo Live Scripting App Connect Desktop

The Live Server will then show a pending connection request, like this:

New Felgo Live Server Connection Request

If you select Accept, your mobile device will be connected. The Live Server will memorize your device. The next time you connect, the request is accepted automatically.

If you want to remove your device completely, select the REMOVE option in the Live Server:

New Felgo Live Server Remove Mobile Client

Starting the Live Server the for First Time

The first time you start the Live Server, you will see a new welcome screen.

New Felgo Live Server Welcome Screen

If you want to connect any mobile device on Windows, it is very important to allow the Live Server to communicate through your firewall. Your project is transferred over a point-to-point connection between the Live Server and the Live Client. It does not leave your local network.

Update your Felgo Live Scripting App

If you already installed the Felgo Live Scripting app, it is very important to update the app to the latest version. This version of the Live Server uses a different protocol, and is only compatible with the latest version of the Live Scripting app.

New Felgo Live App

We usually recommend to use the latest version of the app anyway, to have access to the latest features. This time, it is mandatory.

More New Features in Felgo 2.16.0

Felgo 2.16.0 includes many more features and fixes like:

Be sure to update to the latest version. For a complete list of the changes, please check out our change log!

How to Update Felgo

Test out these new features by following these steps:

  • Open the Felgo SDK Maintenance Tool in your Felgo SDK directory.
  • Choose “Update components” and finish the update process to get this release as described in the Felgo Update Guide.

Felgo Update in Maintenance Tool

If you haven’t installed Felgo yet, you can do so now with the latest installer from here. Now you can explore all of the new features included in this release!


For a full list of improvements and fixes to Felgo in this update, please check out the change log!



More Posts Like This


How to Make Cross-Platform Mobile Apps with Qt – Felgo Apps

Release 2.15.1: New Firebase Features and New Live Code Reloading Apps | Upgrade to Qt 5.10.1 & Qt Creator 4.5.1

Release 2.15.0: Upgrade to Qt 5.10 & Qt Creator 4.5 | Firebase Data Structures and Queries & Many Improvements

New Mobile App Development Documentation with QML Live Reloading of Code Snippets

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