XML elements in app descriptor file

The app descriptor file must specify the app ID, build ID, version number, a Qt binary file for the entry point, and the physical size of the display area. The file can also define fields such as an icon image file, author name, app name and description, and more.

Name Required Description Attributes Example
<action> Yes Specifies the actions associated with the invocation target. Actions are strings that identify the operations that your application is registered to handle. For Qt apps, you must include an <action> tag with the value run_native, to run the app using the OS runtime.

system

(Required)

Specifies whether the action is a system action and not a user action. For Qt apps, you must set this attribute to true.

 <action system="true">run_native</action>
<arg> No Defines the arguments for configuring the application when started. The order of the arguments is important because they're presented in the application's command line in the same order listed in the app descriptor file.   <arg>-b -v</arg>
<aspectRatio> No Specifies whether the application displays in landscape or portrait mode. If no value is specified, the application uses the default orientation set by the OS.   <aspectRatio>landscape</aspectRatio>
<asset> Yes Specifies an asset to package in the BAR file. For Qt apps, you must include an <asset> tag that names the Qt binary that's the app entry point.

Any assets listed on the command line override those specified with this tag. The text of the tag is a path relative to the BAR package root directory. You can also use the dest attribute to specify the asset—this is recommended when using nested <exclude> and <include> elements.

Unless otherwise noted, the attributes are optional.

defaultexcludes

When yes, apply the exclusion patterns to the directory tree. For the list of exclusion patterns, see the <asset> element in the application descriptor file DTD.

dest

The asset's destination path. Typically, the value is the last part of the path value (i.e., the filename).

entry

When true, use the asset to start the application. The default setting is false.

path

(Required)

The location of the asset relative to the current working directory of the packager.

public

When true, store the asset in the public directory of the BAR file, which is readable by other applications. Icon assets should be public. The default setting is false.

type

The asset type. For Qt binaries, use Qnx/Elf.

 <asset type="Qnx/Elf" path="QtApp" entry="true">QtApp</asset>
<author> No Specifies the author name (typically the company or developer name).   <author>My Company Inc.</author>
<autoOrients> No Indicates whether the application automatically reorients its content when the physical orientation of the device changes.   <autoOrients>false</autoOrients>
<buildId> Yes, if not using <buildIdFile> Specifies the build identifier, which is an integer between 0 and 65535. You modify the value when you want the identifier to change.   <buildId>1</buildId>
<buildIdFile> No Names the file that stores the build identifier. This file is located in your application root folder and it stores the build identifier as an integer. The packager tool increments this value each time you build the BAR package.

If you use this element, don't include the <buildId> element.

The default file created by the Momentics IDE is buildnum. 		  <buildIdFile>buildnum</buildIdFile>
<description> No Defines the text to display when the application is installed. You can use nested <text> elements to define text for different languages and locales.   <description>The Hello World Qt demo app.</description>
<env> Yes Defines environment variable settings. For Qt apps, you must define the QQNX_PHYSICAL_SCREEN_SIZE variable and you can defined others as well, as explained in "QNX CAR environment variables".

var

(Required)

Name of the environment variable.

value

(Required)

Value of the environment variable.

 <env var="QQNX_PHYSICAL_SCREEN_SIZE" value="150,90"/>
<exclude> No Specifies the files to exclude from the BAR file based on a filter pattern defined in the name attribute. This element is nested within the <asset> tag.

name

(Required)

The string patterns for filtering files when excluding them. Use the following tokens to match string values:

  • Asterisk(*): Matches zero or more characters.
  • Question mark (?): Matches one character.
  • Double asterisk (**): Matches zero or more directories or folders.

<asset path="Device-Debug/FolderA" type="Qnx/Elf" dest="HelloWorldDisplayManaged">

<exclude name="TEMP?.gif" />

</asset>
<filter> No Specifies a target filter. This element is nested within the <invoke-target> element.

For each target, filters must be declared to describe the kinds of unbound invocations that it supports. Each filter defines an action to perform for MIME types that match the filter.

Unbound invocations should generally provide an action, but must provide either a MIME type, URI, or both. They may also define properties, which are sent to the invocation target. 		  See the <invoke-target> element.
<icon> No Defines an icon for the app. The path of the icon file is defined in the nested <image> tag. If no file is specified, the app doesn't have any default icon but is represented by an empty spot in the viewing area showing the installed apps.   See the <image> element.
<id> Yes Provides an identifier (50 characters or less) for your app. We recommend using a reverse DNS-style naming convention for the value. The value is the package name in the BAR file.   <id>com.mycompany.QtApp</id>
<image> No Specifies the location of the icon image to use for the app. The value is the path to the image asset (PNG or JPG file) from the application root path. The recommended image size is 86 x 86 or 90 x 90 pixels.

This element is nested within the <icon> element. 		 

<icon>

<image>icon.png</image>

</icon>
<include> No Specifies the files to include in the BAR file based on a filter pattern defined in the name attribute. This element is nested within the <asset> tag.

name

(Required)

The string patterns for filtering files when including them. Use the following tokens to match string values:

  • Asterisk(*): Matches zero or more characters.
  • Question mark (?): Matches one character.
  • Double asterisk (**): Matches zero or more directories or folders.

<asset path="Device-Debug/FolderA" type="Qnx/Elf" dest="HelloWorldDisplayManaged">

<include name="App?.png" />

</asset>
<initialWindow> No Contains elements used to override the default properties of the initial app window.  

<initialWindow>

<systemChrome>none</systemChrome>

<transparent>false</transparent>

</initialWindow>
<invoke-target> No Defines an invocation target, which allows one application (the target) to be launched from another application (the client). Typically, the target is part of an application or viewer bundled in the BAR file. An application or viewer must declare each of its targets against an entry point (e.g., the id attribute value of <invoke-target>).

When declaring a target, a globally unique target-key must be used. To ensure the uniqueness of the value, we recommend that you use conventions such as a reverse-DNS name.

This element can contain the following elements:
  • <filter>
  • <icon>
  • <invoke-target-name>
  • <invoke-target-type>
  • <splashScreens>

id

(Required)

A globally unique ID that must start with the application package name. The ID can be up to 50 characters.

<invoke-target id="com.mycompany.pdf.app">

<invoke-target-name>DocFactory</invoke-target-name>

<invoke-target-type>application</invoke-target-type>

<icon>

<image>DocFactoryIcon.png</image>

</icon>

<splashScreens>

<image>DocFactorySplash.png</image>

</splashScreens>

<filter>

<action>bb.action.VIEW</action>

<mime-type>application/pdf</mime-type>

<mime-type>application/x-pdf</mime-type>

<property var="saveOnClose" value="true"/>

</filter>

</invoke-target>
<invoke-target-name> No Defines the text to display in the UI. If this value isn't specified, the application name (i.e., the value in <name>) will be displayed.   See the <invoke-target> element.
<invoke-target-type> No Defines the target type. The supported types are:
application
The target is an application and is started only when required.
viewer
The target reference always spawns a new window and window reparenting is required.
   See the <invoke-target> element.
<mime-type> No The MIME type of the data that the invocation target can process. This element is nested within the <filter> element. The grammar for the MIME type must support these specifications:
  • RFC 2045 (content-types)
  • RFC 4288 (IANA registration)
   See the <invoke-target> element.
<name> No Defines the string value to display when the app is installed. This UTF-8 value can be at most 25 characters.   <name>Qt App</name>
<packageLocale> No Lists the locales supported by the application. The values given must be defined in the IETF Best Current Practice (BCP) 47 specification. You can use a comma-delimited list of locales to specify more than one.   <packageLocale>en-US,de_DE,fr_CA</packageLocale>
<permission> Yes Specifies the privileges (also known as capabilities, user actions, or actions) that the application requests from the OS. For Qt apps, you must include a <permission> tag with the value run_native, to run the app using the OS runtime.

The list of permission settings relevant to Qt apps is given in "App permissions".

system

(Required)

Specifies whether the action is a system action and not a user action. For Qt apps, you must set this attribute to true.

 <permission system="true">run_native</permission>
<platformArchitecture> No Specifies the processor architecture that the application is compiled for. If you don't specify a value, the Momentics IDE inspects the binary to determine the value.

You can use the following values:
x86
Specifies to compile your application to run on a simulator.
armle-v7
Specifies to build the application to run on a device.
   <platformArchitecture>x86</platformArchitecture>
<platformVersion> No Lists the locales supported by the application. The values given must be defined in the IETF Best Current Practice (BCP) 47 specification. You can use a comma-delimited list of locales to list more than one.   <platformVersion>10.2.0.155</platformVersion>
<property> No Specifies additional arguments to send to an invocation target. This element is nested within the <filter> element.

var

(Required)

Name of the property.

value

(Required)

Value of the property.

 See the <invoke-target> element.
<qnx> Yes Defines the top-level element of the schema used for the app descriptor file.

xmlns

(Optional)

URL reference to the XML namespace.

 See the example of the app descriptor file in "Writing the app descriptor file".
<splashScreens> No Contains <image> elements that specify images to display when the application launches. You can nest <text> elements within the <image> elements to define different splashscreens for different locales. A splashscreen image file must be a PNG or JPG file whose path is in the application root folder.  

<splashScreens>

<image>

<text xml:lang="fr">splash-600x1024_fr.jpg</text>

</image>

</splashScreens>
<splashscreen> No Specifies the image file to display when the app is launching. You can use the <text> element to specify different images for different languages and locales. This file must be a PNG or JPG file with resolution sizes of 1024 x 600 pixels (landscape) or 600 x 1024 (portrait). The image can be in the application root folder or in a folder accessible from the root.  

<splashscreen>

sample-splashscreen-landscape.png:sample-splashscreen-portrait.png

<text xml:lang="de-DE">sample-splashscreen-landscapeDE.png:sample-splashscreen-portraitDE.png</text>

</splashscreen>
<systemChrome> No When standard, the initial application window is displayed with the standard system chrome (i.e., title bar, borders, and controls) provided by the OS. When none, no system chrome is displayed. This setting can't be changed at run time.   See the <initialWindow> element.
<text> No Specifies text for the parent <name> and <description> elements, to support different languages and locales. You can also use this element to specify multiple image files for the <image> and <splashscreen> elements.

xml:lang

(Required)

The language or locale code. The XML locale strings use hyphens per the IETF Best Current Practice (BCP) 47 specification. For example, you can use en-US (United States English), de-DE (German), or fr-CA (Canadian French).

<description>The Hello World Qt demo app.

<text xml:lang="de-DE">The German description for the Hello World Qt demo app.</text>

</description>
<transparent> No Specifies whether the initial application window is alpha-blended with the background. The use of transparency can slow down rendering and consume more memory. The transparency setting can't be changed at run time and is valid only when the <systemChrome> element is set to none.   See the <initialWindow> element.
<versionNumber> Yes Specifies the app version as a string in the format <0-999>.<0-999>.<0-999>. The version is useful for determining whether the application requires an upgrade. The value can be a one-, two-, or three-part value, such as 1, 1.0, or 1.0.0.   <versionNumber>1.0.0</versionNumber>