Skip To Content

AppFramework QML Type

Provides access to path settings, visual settings and OS information. More...

Import Statement: import ArcGIS.AppFramework 1.0

Properties

Signals

Methods

Detailed Description

The AppFramework component provides a number of miscellaneous functions to display information about the device or app, as well as to perform actions that need to be performed above other objects. The AppFramework component also contains functions to create a number of other component objects.

AppFramework is a singleton component, created on the app's launch. Individual instances of this component cannot be created.

The following code snippet explains the usage of AppFramework component, displaying in text the userHomePath and osVersion properties.

App {
    id: app;
    width: 800;
    height: 532;

    Text {
        id: titleText;

        anchors {
            left: parent.left;
            right: parent.right;
            top: parent.top;
            topMargin: 100;
        }

        Column {
            Text { font.pointSize: 15; text: "UserHomePath: " +AppFramework.userHomePath; }
            Text { font.pointSize: 15; text: "OS Version: " + AppFramework.osVersion; }
        }

        color: "#4c4c4c";
        horizontalAlignment: Text.AlignHCenter;
    }

}

Enumerations

Capability enumeration

Enum describing the capabilities the app can have access to. Informs the checkCapability method.

NameValue
AppFramework.Location0
AppFramework.Storage1
AppFramework.Camera2
AppFramework.Microphone3
AppFramework.BackgroundLocation4

Property Documentation

[read-only] availableLocaleNames : QStringList

Returns a list of available locale names.

ComboBox {
    model:AppFramework.availableLocaleNames
}

[read-only] buildAbi : string

Returns the full architecture string that the app was compiled for.

Text {
    text: AppFramework.buildAbi
}

[read-only] buildCpuArchitecture : string

Returns a string describing the architecture of the CPU that the app was compiled for.

Text {
    text: AppFramework.buildCpuArchitecture
}

[read-only] clipboard : Clipboard

If no clipboard object exists, creates a new clipboard object. Otherwise, returns the pre-existing clipboard object.


[read-only] currentCpuArchitecture : string

Returns a string describing the architecture of the CPU that the app is currently running on. Note that this function is dependent on what the OS reports, and may not describe the actual CPU architecture if the OS does not provide that information.

Text {
        text: AppFramework.currentCpuArchitecture
}

defaultLocale : string

Contains the default locale for an application. The default locale is the same as the systemLocale property.

This property accepts only correctly formatted locale codes.

AppFramework.defaultLocale = "fr_CA"; // sets the current locale to Canadian French
AppFramework.defaultLocale = AppFramework.systemLocale; // restores current locale to system locale

displayScaleFactor : double

Returns the device's scale factor, calculating it if necessary based on the screen's DPI.

Text {
    text:"Hello AppStudio!"
    font.pixelSize: 20 * AppFramework.displayScaleFactor
}

[read-only] environment : Environment

If no environment object exists, creates a new environment object. Otherwise, returns the pre-existing environment object.


importPathList : QStringList

Returns the list of directories where the engine searches for installed modules in a URL-based directory structure.

ComboBox {
        model:AppFramework.importPathList
}

[read-only] isOnline : bool

Returns true if the device is currently connected to a network. Otherwise, returns false.

This property will be deprecated soon, and should no longer be used. Instead, use the isOnline property in the Networking component.


[read-only] kernelType : string

Returns the type of operating system kernel Qt was compiled for. This will also usually be the kernel the application is running on. On Windows, this returns the type of Windows kernel, such as 'winnt'. On Unix systems, this returns the same name as the output of the command "uname -s".


[read-only] kernelVersion : string

Returns the release version of the operating system kernel. On Windows, this will return the version of the NT or CE kernel. On Unix systems (including Android and MacOS), this will return the same as the "uname -r" command would return.

If the version cannot be determined, returns an empty string.

Text {
        text:"OS Kernel is " + AppFramework.kernelType  + " and version is "+ AppFramework.kernelVersion
}

[read-only] logging : Logging

Creates and returns a new logging object.


[read-only] network : Network

Returns a network object, creating one if one does not exist.


offlineStoragePath : string

Returns the directory for storing offline user data.

Text {
    text: AppFramework.offlineStoragePath
}

[read-only] osDisplayName : string

Returns a form of the product version similar to that returned by osVersion, but containing other identifying tokens like operating system type and codenames. The resulting string is good to display to the user, but may be unsuitable for long-term storage.

If osVersion returns 'unknown', this will instead refer to the kernelType and kernelVersion properties.

Text {
    text: AppFramework.osDisplayName
}

[read-only] osName : string

Returns the product name of the operating system the application is running in.

Text {
    text: AppFramework.osName
}

[read-only] osVersion : string

Returns the product version of the operating system in string form. If this cannot be determined, returns 'unknown'.

Text{
    text: AppFramework.osVersion
}

[read-only] qtVersion : string

Returns the version number of Qt at run-time as a string.

Text {
    text: AppFramework.qtVersion
}

[read-only] settings : Settings

Returns a settings object, creating one if one does not exist.


[read-only] sslLibraryBuildVersion : string

Returns the version string of the SSL library in use. If no SSL support is available, returns an empty value.

Text {
    text: AppFramework.sslLibraryBuildVersion
}

[read-only] sslLibraryVersion : string

Returns the version number of the SSL library in use. If no SSL support is available, returns an empty value.

Text {
    text: AppFramework.sslLibraryVersion
}

[read-only] standardPaths : StandardPaths

Returns a StandardPaths object. If one does not exist, one will be created.


[read-only] systemInformation : object

Returns an object containing values with additional information about the platform the app is running on. This is useful for differentiating between different models running the same OS, such as between iPhones and iPads, or for providing information that may help distinguish what platform the device is.

Warning: Differentiation of Android hardware between ARM and x86 environments may not be possible. Instead, this will be reported based on the app's target environment.

Text {
    text: JSON.stringify(AppFramework.systemInformation, undefined, 2)
}

On an iOS device, this property returns something like this:

{
  "family": "tablet",
  "manufacturer": "Apple",
  "model": "iPad Mini",
  "unixMachine": "iPad5,4",
  "unixNodeName": "iPad-Mini-Name",
  "unixRelease": "17.4.0",
  "unixSysName": "Darwin",
  "unixVersion": "Darwin Kernel Version 17.4.0: Fri Dec 8 19:35:52 PST 2017; root:xnu-4570.40.9~1/RELEASE_ARM64_T7001"
}

While on an Android device, the results will resemble this:

{
  "family": "phone",
  "manufacturer": "samsung",
  "model": "SM-G955F",
  "unixMachine": "armv8l",
  "unixNodeName": "localhost",
  "unixRelease": "4.4.111-13760092-QB18535760",
  "unixSysName": "Linux",
  "unixVersion": "#1 SMP PREEMPT Thu Jun 14 16:44:12 KST 2018"
}

[read-only] systemLocale : string

Returns the locale provided by the operating system.


[read-only] temporaryFolder : FileFolder

Creates and returns a new folder in the system's temporary directory.


[read-only] userHomeFolder : FileFolder

Creates and returns a folder at the destination defined by the user home path.


userHomePath : string

Returns the device's user home path.

Text {
    text: AppFramework.userHomePath
}

[read-only] version : string

Returns the current AppFramework version the app is using.

Text {
    text: AppFramework.version
}

Signal Documentation

onlineStateChanged( bool online)

Signal emitted when the online state of the device has changed.


Method Documentation

addImportPath(string path)

Adds the defined path as a directory where the engine searches for installed modules in a URL-based directory structure. The defined path is inserted as the first item to the existing import path list.

AppFramework.addImportPath("http://appstudio.arcgis.com");
console.log(AppFramework.importPathList[0]);

The path parameter

The path to be added as a directory. this may be a local filesystem directory, a path or URL for a Qt Resource, or a URL.


color alphaColor(color color, double alpha)

Converts a color into an alpha-blended or semi-transparent color using the input alpha value.

Item {
        Rectangle {
                id:rect
                width: 20;height:20;
                color:  "#ff0000"
        }

        Button {
                text:"CreateAlphaColor"
                onClicked: {
                        var color = rect.color;
                        var newColor = AppFramework.alphaColor(color, 0.50);
                        console.log(newColor.toString()); // returns #80ff0000
                        rect.color = newColor;
                }
        }
}

The color parameter

The RGB value of this color.

The alpha parameter

The alpha component (transparency) of this color. For example, for 50% transparency, enter 0.5.


BinaryData binaryData(var value)

Produces a binary data object to manage binary content. This object will be created containing the given variable.

The value parameter

The variable the binary data object will be created containing.


BinaryData binaryData()

Produces a binary data object to manage binary content, e.g. to convert from one text encoding scheme to another, or manipulate raw data.

For example,

var s = "Hello";
var b = AppFramework.binaryData(s); //  produces a binary data object
b.size; // returns 5
b.setStringData("AppStudio for ArcGIS"); // Sets the string data to a 20-byte binary object.
b.size; // returns 20

bool checkCapability(capability capability)

This method is in the process of being deprecated, and should not be used. Instead, use the checkPermission method from the Permission component in the Platform plugin.

Returns true if the app has granted access to the capability defined in the parameter.

This will return true on desktop platforms (Windows, macOS, and Linux) by default.

These capabilities need to be enabled in the Settings for your app in AppStudio. This method is read-only, and cannot change these capabilities.

Rectangle {
    width: 25
    height: width
    color : AppFramework.checkCapability(AppFramework.Camera) ? "green" : "red"
}

The capability parameter

The capability to check the access of. This is informed by the Capabilities enum.


clearComponentCache()

Clears the engine's internal component cache.

This function causes the property metadata of all components previously loaded by the engine to be destroyed. The engine is returned to a state where it doesn't cobtain any loaded component data.


collectGarbage()

Invokes the garbage collector, which will attempt to reclaim memory by locating and disposing of objects no longer reachable in the script environment.

Normally this function isn't necessary; the garbage collector is automatically invoked. However, this function can be called manually to ensure garbage collection should be performed as soon as possible.

AppFramework.collectGarbage();

color contrastColor(color color, color tintColor)

Generates a brighter or darker version of the supplied color to contrast. The tintColor parameter adds a shade of variety to the returned color.

The color parameter

The color to return a brighter or darker version of.

The tintColor parameter

The color to tint the returned, contrasting color with.


color contrastColor(color color)

Generates a black or white color value that contrasts with the given color value. A lighter color will return black, while a darker color will return white.

var color = "#00ffff"; // on the brighter side
var tintColor = "#ff0000"
var newColor = AppFramework.contrastColor(color,tintColor);
console.log(newColor.toString()); // returns"#ff0000"

The color parameter

The color value to return a contrasting value for.


string createId()

Creates a uniquely identifying ID in string format.

var id = AppFramework.createId();
return id; // 6c2ca30085ff45f49b6242e588c5ebf3

string createUuidString(int format)

Creates a universally unique identifier (UUID) string; a 128-bit number to use as a way to identify a particular object or component.

For example,

var currentItemUuid = AppFramework.createUuidString(1);
var thisFilename = (currentItemFilename !== "") ? currentItemFilename + "_" + currentItemUuid : "export" + currentItemUuid;

The format parameter

0 to include curly brackets and hyphens, e.g. {3F2504E0-4F89-41D3-9A0C-0305E82C3301}. 1 to include hyphens but not curly brackets, e.g. 3F2504E0-4F89-41D3-9A0C-0305E82C3301. 2 to not include hyphens or curly brackets, e.g. 3F2504E04F8941D39A0C0305E82C3301.


string createUuidString()

Creates a universally unique identifier (UUID) string; a 128-bit number to use as a way to identify a particular object or component. Without a defined format, defaults to using curly brackets and hyphens.


File file(string path)

Creates a new file object at the specified path destination.

The path parameter

The path to the file that will be created.


File file(url pathUrl)

Creates a new file object at the specified URL destination.

The pathUrl parameter

The URL to the file that will be created.


FileFolder fileFolder(string path)

Creates a new fileFolder object at the specified path destination.

The path parameter

The path to the folder that will be created.


FileFolder fileFolder(url pathUrl)

Creates a new fileFolder object at the specified URL destination.

The pathUrl parameter

The URL to the file that will be created.


FileInfo fileInfo(string path)

Creates a new FileInfo object at the specified path destination.

The path parameter

The path to the object that will be created.


FileInfo fileInfo(url pathUrl)

Creates a new FileInfo object at the specified URL destination.

The pathUrl parameter

The URL to the object that will be created.


bool grabWindowToClipboard(rect rect)

Save a graphic image of the screen to the clipboard.

By including a definition of the rectangle that you wish to capture, you can tailor your screen shot. In the following example, when the user clicks the button an image is saved to the clipboard whose origin is the left hand edge of the app and the bottom of the toolbar, and its extent is the same height and width of the map component.

Button {
    text: "Capture"
        onClicked: AppFramework.grabWindowToClipboard( Qt.rect(0, toolbar.height, map.width, map.height) )
}

The rect parameter

The rectangle extent to save to clipboard, in the form of (x, y, width, height).


bool grabWindowToClipboard()

Save a graphic image of the screen to the clipboard.

The following example will save an image to the clipboard and will include content for the full extent of the app.

Button {
        text: "Capture"
        onClicked: AppFramework.grabWindowToClipboard()
}

bool grabWindowToFile(string path, rect rect)

Save a graphic image of the screen to a nominated file.

By including a definition of the rectangle that you wish to capture, you can tailor your screen shot. In the following example, when the user clicks the button an image is saved to file called map.png whose origin is the left hand edge of the app and the bottom of the toolbar, and its extent is the same height and width of the map component.

Button {
    text: "Capture"
        onClicked: AppFramework.grabWindowToFile("map.png", Qt.rect(0, toolbar.height, map.width, map.height) )
}

The path parameter

The filename and path for the saved image.

The rect parameter

The rectangle extent to save to file, in the form of (x, y, width, height).


bool grabWindowToFile(string path)

Save a graphic image of the screen to a nominated file.

The following example will save an image to a file called map.png and will include content for the full extent of the app.

Button {
    text: "Capture"
        onClicked: AppFramework.grabWindowToFile("map.png")
}

The path parameter

The filename and path for the saved image.


bool instanceOf(var value, var type)

Returns true if the supplied value is of the requested value type. Otherwise, returns false.

Item {
        property url testUrl: "http://"
        property string testUrlString: "http://"

        ImageObject {
                id: imageObject
        }

        Component.onCompleted: {
                console.log( AppFramework.instanceOf(imageObject.exifInfo, "ExifInfo")); // returns true
                console.log( AppFramework.instanceOf(testUrl, "url")); // returns true
                console.log( AppFramework.instanceOf(testUrlString, "string")); // returns true
                console.log( AppFramework.instanceOf(testUrlString, "url")); // returns false
        }
}

The value parameter

The value to check the type of.

The type parameter

The type of value to check the provided value against.


bool isAppInstalled(string appIdentifier)

Returns true if the given app is installed on the device. Otherwise, returns false.

This method is currently only implemented on iOS and Android. On all other platforms, this method returns true regardless.

The appIdentifier parameter

The identifying string for the app. This requires a URI scheme (e.g. app-urlscheme://) on iOS, or a package name (com.app.package.name) on Android.


loadTranslator(var translations, string appFolderPath, string locale)

Loads a translator for the set locale. For example, this code snippet:

var locale = "fr_CA";
AppFramework.loadTranslator( app.info.json.translations, app.folder.path, locale);

will load the translation file languages/HelloApp_fr.qm if available.

var locale = "fr_CA";
AppFramework.loadTranslator( app.info.json.translations, app.folder.path, locale);

The translations parameter

A JavaScript object that contains fileName and path members. fileName refers to a string array containing translation files. Note that the actual translation files will have a suffix for each locale. path refers to a subfolder in the app where these translations can be found. For instance, the following translation object will return the translation files for HelloApp, found in the 'languages' folder:

{
    "fileName": [ "HelloApp" ],
    "path": "languages"
}

The appFolderPath parameter

The actual location of the current running app. For apps running in AppStudio or AppStudio Player this will be a location in the file system; for built apps, this location will be to a Qt Resource. To refer to either location, use app.folder.path.

The locale parameter

The locale code for the language you intend to load translation files from.


loadTranslator(var translations, string appFolderPath)

Loads a translator in the default locale. The default locale is described by the defaultLocale property.

AppFramework.defaultLocale = "fr_CA";
AppFramework.loadTranslator( app.info.json.translations, app.folder.path);

The translations parameter

A JavaScript object that contains fileName and path members. fileName refers to a string array containing translation files. Note that the actual translation files will have a suffix for each locale. path refers to a subfolder in the app where these translations can be found. For instance, the following translation object will return the translation files for HelloApp, found in the 'languages' folder:

{
    "fileName": [ "HelloApp" ],
    "path": "languages"
}

The appFolderPath parameter

The actual location of the current running app. For apps running in AppStudio or AppStudio Player this will be a location in the file system; for built apps, this location will be to a Qt Resource. To refer to either location, use app.folder.path.


LocaleInfo localeInfo(var locale)

Returns a locale object initialized to the given locale. If a locale object doesn't exist, one will be created.

The locale parameter

The locale code to return an object for.


LocaleInfo localeInfo()

Returns a locale object initialized to the default system's locale. If a locale object doesn't exist, one will be created.


string objectToString(object object)

Returns a user-readable string describing the defined object. It provides the structure of the component along with the class hierarchy and lists all the properties, signals and methods it supports.

console.log(AppFramework.objectToString(imageObject.exifInfo))

The object parameter

The object to return information about.


string pathVariable(string name)

Returns the path of the input environment variable as a string.

For example,

AppFramework.pathVariable("HOME"); // produces C:\Users\UserName
AppFramework.resolvedPath("$HOME/file.txt"); // produces C:\Users\UserName/file.txt
AppFramework.resolvedPathUrl("$HOME/file.txt"); // produces file:///C:/Users/UserName/file.txt
AppFramework.setPathVariable("HOME", "C:/Temp");
AppFramework.resolvedPath("$HOME/file.txt"); // now produces C:/Temp/file.txt
AppFramework.resolvedPathUrl("$HOME/file.txt"); // produces file:///C:/Temp/file.txt

The name parameter

The name of the path variable.

See also setPathVariable().


removeImportPath(string path)

Removes the path from the list of import paths.

AppFramework.removeImportPath("http://appstudio.arcgis.com");

The path parameter

The path you wish to remove from import paths.


string resolvedPath(string path)

Refers to a local filename or resource.

For example,

AppFramework.resolvedPath("~/file.txt");

produces the path: "C:/Users/UserName/file.txt"

The path parameter

The path you wish to resolve.


string resolvedPath(url pathUrl)

Converts a file URL into a local filename or resource.

For example,

u = AppFramework.resolvedPathUrl(":/file.png"); // produces qrc:///file.png
AppFramework.resolvedPath(u); // produces :/file.png

The pathUrl parameter

The URL you wish to convert.


url resolvedPathUrl(string pathUrl)

Converts a local filename or resurce into a file URI scheme.

For example,

AppFramework.resolvedPathUrl("C:/Temp/file.txt"); // produces "file:///C:/Temp/file.txt"
AppFramework.resolvedPathUrl("~/file.txt"); // produces "file:///C:/Users/Somebody/file.txt"
AppFramework.resolvedPathUrl(":/file.txt"); // produces "qrc:///file.txt"

The pathUrl parameter

The path to convert into a URL scheme.


url resolvedUrl(url url)

Returns the given URL, resolved relative to the URL of the caller.

property url urlTest : "./temp"
// returns "file:///C:/Users/john007/ArcGIS/AppStudio/Apps/49cfc974e8fc48f2bfd91e0f873c2353/temp"
console.log(AppFramework.resolvedUrl(urlTest));

The url parameter

The URL to resolve.


sendKey(var key, item item)

Sends a triggered key press, or sequence of key presses, to the target item.

The key parameter

The key being sent to the item.

The item parameter

The item the key is being sent to.


sendKey(var key)

Sends a triggered key press, or sequence of key presses, to the app.

The key parameter

The key being sent to the app.


sendStandardKey(var key, item item)

Sends the triggered standard key binding to the item.

For a list of applicable key bindings, refer to Qt's listing: http://doc.qt.io/qt-5/qkeysequence.html#StandardKey-enum

The key parameter

The key being sent to the item.

The item parameter

The item the key is being sent to.


sendStandardKey(var key)

Sends the triggered standard key binding to the app.

For a list of applicable key bindings, refer to Qt's listing: http://doc.qt.io/qt-5/qkeysequence.html#StandardKey-enum

The key parameter

The key being sent to the app.


setPathVariable(string name, string value)

Sets the environment variable used in the expansion of a call to resolvedPath.

For example,

AppFramework.pathVariable("HOME"); // produces C:\Users\UserName
AppFramework.resolvedPath("$HOME/file.txt"); // produces C:\Users\UserName/file.txt
AppFramework.resolvedPathUrl("$HOME/file.txt"); // produces file:///C:/Users/UserName/file.txt
AppFramework.setPathVariable("HOME", "C:/Temp");
AppFramework.resolvedPath("$HOME/file.txt"); // now produces C:/Temp/file.txt
AppFramework.resolvedPathUrl("$HOME/file.txt"); // produces file:///C:/Temp/file.txt

The name parameter

The name of the path variable being set.

The value parameter

The value of the path variable being set.

See also pathVariable().


trimComponentCache()

Trims the in-use engine's internal component cache. This function causes the property metadata of any loaded components not currently in use to be destroyed. If there is no engine currently in use, does nothing.


string typeOf(var value, bool displayName)

Returns the type of alias value that has been given as a string.

console.log(AppFramework.typeOf(myButton, true)); // returns Button_QMLTYPE_34

The value parameter

The value to identify.

The displayName parameter

If true, will return the alias name.


string typeOf(var value)

Returns the type of value it has been given as a string.

console.log(AppFramework.typeOf(myButton)); // returns Button

The value parameter

The value to identify.


UrlInfo urlInfo(url url)

Creates and returns a new UrlInfo object based on the given URL.

The url parameter

The URL to derive an object from.


object xmlToJson(string xml, object options)

Converts the given string containing XML content into a JavaScript object, with configurable options.

This XML content can originate from a file or from the internet. If the content comes from online, use the NetworkRequest object to retrieve such concept.

The xml parameter

The XML content string to convert.

The options parameter


object xmlToJson(string xml)

Converts the given string containing XML content into a JavaScript object.

This XML content can originate from a file or from the internet. If the content comes from online, use the NetworkRequest object to retrieve such concept.

The xml parameter

The XML content string to convert.