Settings

Settings can be defined in an app for use at run time only or saved to persist across sessions. You can read user or system environment variables, set environment variables or properties during run time, or save settings to a file.

Environment variables

Environment variables can be set for the user or for the system. They can be set before running your app and used to configure alternative app behavior. For example, the setting of the LANG environment variable will influence the locale that is used by Qt applications.

To read the value of any environment variable in your app, use AppFramework.environment.value() .

To overwrite the current setting of an environment variable, use AppFramework.environment.setValue() . This change will remain valid while the app is running.

PropertySet

PropertySet is a component that allows you to set key-value pairs that can be used in QML bindings. This component is best used when you don't know what the property value will be before the app is launched, and instead it is set at run time.

For more information, see the API Reference for PropertySet.

Settings file

Settings can be saved in a JSON file and are both written to and read from by the Settings component.

The location of this JSON file varies depending on your operating system, as well as whether the app is created as a stand-alone app or used through AppRun or AppStudio Player. In almost all cases, directly editing the file isn't needed, but it may be necessary to open these files for bug testing purposes. If you need to do this, the files are located in the following folders, named by their UUID in ArcGIS Online:

• Windows: C:\Users\YourUsername\ArcGIS\AppStudio\Settings
• macOS and Ubuntu: ~\ArcGIS\AppStudio\Settings

After an app is built, this settings file can be generated in one of four standard locations, depending on organizational information in the app and user permissions. These are fallback locations, and you can define if your app will use them with the useFallbacks Boolean property.

Define the setting values in a file

Settings are assigned and stored as key-value pairs, which are used to represent any settings you have added. If a key doesn't exist, it can be created either to a set default or to whatever the user first sets it to. Be aware that these key values are case sensitive; use consistent capitalization throughout.

The Settings component supports four types of values that can be useful in different contexts. The following examples show typical ways in which the values might be used.

The basic value and setValue functions are intended for strings and can be used for a wide variety of scenarios. In this case, the following code sample provides a way to set a default path URL:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
readonly property string defaultLibraryPath: "~/ArcGIS/Example App/Library"

Item {
    Component.onDestruction: {
        var paths = libraryTextField.text.trim();

        if (paths.length <= 0) {
            paths = defaultLibraryPath;
        }

            settings.setValue("libraryPaths", paths, defaultLibraryPath);
    }

    TextField {
        id: libraryTextField

        Layout.fillWidth: true

        text: defaultLibraryPath
    }
}

The boolValue function provides a choice of true or false, ideal for a closed question with little required nuance. The following code sample applies the setting to a switch, determining if the application retains logins across sessions:

1
2
3
4
5
6
7
8
9
property bool staySignedIn: false

    Switch {
    checked: staySignedIn
    onCheckedChanged: {
        staySignedIn = true;
        settings.boolValue("staySignedIn", true);
    }
}

The Settings component also provides numberValue to define an integer, which is useful for granular settings, such as size, or scenarios that require a choice between multiple distinct options, and colorValue , which stores a hexadecimal color value, largely used for customizing the appearance of an app. While these functions store different types of values, they behave in the same way as boolValue .