Using QML Preview

The following information is designed to help you make the most of QML Preview and troubleshoot any issues you might run into as you use the tool.

For more information about QML Preview, see The QML Editing perspective.

Prerequisites in Windows and Mac OS

To use QML Preview in the Momentics IDE for BlackBerry, you need to have the following:

  • A graphics card with OpenGL 2.0 support
  • The latest drivers installed for your graphics card

Prerequisites in Linux

As of API level 10.2, QML Preview is supported when running certain versions of Ubuntu.

Using Ubuntu 14.04

QML Preview is supported on Ubuntu version 14.04. Because this version of Ubuntu comes with multiarch support, you don't need to install the ia32-libs library for 64-bit systems.

However, to use QML Preview with Ubuntu 14.04, you must have the libosmesa6 library installed (version 9.2.1-1ubuntu3).

For 32-bit systems, you can install the library with the following command:

sudo apt-get install libosmesa6

For 64-bit systems, you can install the library with the following command:

sudo apt-get install libosmesa6:i386

Known limitations of QML Preview

There are several limitations to keep in mind as you work with QML Preview in the Momentics IDE.

Using outdated graphics drivers

Outdated graphics drivers can cause unexpected behavior with QML Preview, including issues with rendering or the inability to use QML Preview. Ensure that you have the latest drivers available for your graphics card before you use QML Preview.

Using QML Preview in a virtual environment

If you run the Momentics IDE in a virtual environment, you need to enable 3-D support in your virtual environment to use QML Preview. For more information on enabling 3-D support, consult the documentation for your virtual environment. For example, if you are using VMware Workstation, see Enabling Accelerated 3-D for a Virtual Machine on the VMware Workstation website.

If you use a remote desktop tool to run the Momentics IDE, you can't use QML Preview.

Using QML with C++ objects

QML Preview tries to ignore the unsupported components and render the remaining QML components. A "missing component" placeholder may be displayed in place of the unsupported components. For the most accurate view of your QML content, you should run your app on a BlackBerry 10 device or the BlackBerry 10 Device Simulator.

If your project uses API level 10.2 or earlier, QML Preview renders your UI as it would appear on a device running the 10.2.1 version of the BlackBerry 10 OS. If your project uses API level 10.3 or later, QML Preview renders your UI as it would appear on a device running the 10.3.0 version of the OS.

Some components can't be rendered using QML Preview

Some components, such as the WebView control, can't be rendered in QML Preview. For the most accurate view of your QML content, you should run your app on a BlackBerry 10 device or the BlackBerry 10 Device Simulator.

For more information on the known limitations, see the release notes.

Some components can't be selected using QML Preview

Some components can't be selected in QML Preview using the selection feature. For example, you can't select an ActionBar , Tab , or TitleBar object in QML Preview.

For more information on the known limitations, see the release notes.

Previewing QML files when using static asset selection

Some apps use asset selectors to handle different device resolutions. If your app includes static asset selection, you need to select the matching device resolution for QML Preview to render correctly.

If you open the default main.qml file of an app that uses an asset selector containing an alternate main.qml file, QML Preview previews the main.qml file as it would appear on the device resolution that you've selected (even if that main.qml file would never be used on that device resolution). If you switch the device resolution to an appropriate device resolution, the preview renders as expected.

For example, the following image shows the preview of the pullmybeard.qml file with the 768 x 1280 device resolution selected. The preview seems to be incorrect because QML Preview is rendering a file that would never be used at this device resolution.

Screen showing the Momentics QML Preview using the incorrect QML file from the assets folder.

There is an asset selector for the 768 x 1280 device resolution (mindw76h128du) that contains an alternate pullmybeard.qml file. If you preview the pullmybeard.qml file in the mindw76h128du asset selector, QML Preview renders the UI as expected. You can also change the device resolution in the IDE to 720 x 720 to see the pullmybeard.qml file in the assets folder rendered correctly.

Screen showing the Momentics QML Preview using the correct QML file from the asset selector.

For more information about asset selectors, see Static asset selection. For the most accurate view of your QML content, you should run your app on a BlackBerry 10 device or the BlackBerry 10 Device Simulator.

In Momentics IDE 2.1.1 and later, an info icon appears beside the QML Preview drop-down list when there is more than one QML file with the same name in your project.

Momentics IDE info icon in QML Preview.

This icon indicates that you might be previewing a file that is not intended for the device that you've selected in the QML Preview drop-down list. If your preview doesn't appear as you expected, click the icon and read the text. If possible, an alternate file to preview is listed in the dialog box that appears.

QML Preview FAQ

The following list provides answers to frequently asked troubleshooting questions about QML Preview.

QML Preview has been updated so that each preview runs in a separate, standalone process. This technique improves the performance and stability of QML Preview. If you are previewing multiple QML files at one time, you may see multiple instances of the qmlpreview process.

If you get an error when using QML Preview, report the error using the Developer Issue Tracker and provide your workspace log file and the QML file that triggers the error. You can find the workspace log in the <path to workspace>/.metadata folder.

The Preprocess QML Files for QML Preview feature filters items that can't be rendered (such as C++ objects registered in QML) and displays the parts of the UI that can be shown. The preprocessing feature is enabled by default, but you can disable it if you need to.

To disable the feature:

  1. In Windows and Linux, on the Window menu, click Preferences. In Mac OS, on the Momentics menu, click Preferences.
  2. Expand BlackBerry and click QML Editor.
  3. In the QML Preview area, clear the Preprocess QML Files check box.

If you see the "Loading dynamic content of <file>" timeout message, close and reopen the QML file and try again. If the problem persists, report the error using the Developer Issue Tracker and provide your workspace log file and the QML file that triggers the error. You can find the workspace log in the <path to workspace>/.metadata folder.

Although QML Preview uses the same rendering engine as a device, there are several reasons why the preview doesn't match the UI, such as:

  • QML Preview renders only from the current file and may exclude components or features that are defined elsewhere in the app.
  • C++ components can't be rendered using QML Preview.
  • External assets that are located outside the assets folder of the project can't be previewed.
  • The current file uses a resolution, theme, or orientation that the device doesn't support.

QML Preview uses two methods to render your UI. If your project uses API level 10.2 or earlier, QML Preview renders your UI as it would appear on a device running the 10.2.1 version of the BlackBerry 10 OS. If your project uses API level 10.3 or later, QML Preview renders your UI as it would appear on a device running the 10.3.0 version of the OS.

If you get this error and clicking the Try again button doesn't resolve the issue, make sure your system meets the requirements listed above. If the problem persists, report the error using the Developer Issue Tracker and provide your workspace log file and the QML file that triggers the error. You can find the workspace log in the <path to workspace>/.metadata folder.

QML Preview can render only QML objects from the bb.cascades library that's imported into your project. If you import the bb.cascades 1.2 library but your API level is set to 10.1 or earlier, QML Preview can't render the file.

Workaround: Update your API level to 10.2, or change the imported library to match your selected API level. To change your API level, on the Window menu, click Preferences > BlackBerry > API Level and select the API level from the drop-down list.

To enable QML Preview:

  1. In Windows and Linux, on the Window menu, click Preferences. In Mac OS, on the Momentics menu, click Preferences.
  2. Expand BlackBerry and click QML Editor.
  3. In the QML Preview area, clear the Disable check box.

For more help

For more help, check out the Native Development support forums.

Last modified: 2014-11-17



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus