ArcGIS for Developers

Settings QML Type

The Settings component provides access to Parameters. More...

Import Statement: import ArcGIS.AppFramework 1.0
Inherited By:

AppPlayerSettings

Properties

Signals

Methods

Detailed Description

This component provides a built-in mechanism for developers to let end app users persist data such as preference, state information etc without having to worry about where the data is stored or to how to initialize a Settings component instance.

The data gets stored within the json file located under Settings folder (~/ArcGIS/AppStudio/Settings). Every app has a corresponding json file. Hence the persisted data can only be used in its own app.

Here is an example to show how to write to the apps settings file. This means you have a location that will persist values. Once stored, you can see how to read the values.

App {
    id: app
    width: 800 * AppFramework.displayScaleFactor
    height: 600 * AppFramework.displayScaleFactor

    ColumnLayout {
        anchors.fill: parent
        anchors.margins: 10

        TextField {
            Layout.fillWidth: true
            placeholderText: qsTr("Enter a value...")
            text: app.settings.value("textfield")
            onTextChanged: app.settings.setValue("textfield", text)
        }

        Button {
            text: qsTr("Read your settings")
            onClicked: resultText.text = app.settings.path + "\r\n"
                       + app.folder.readTextFile(app.settings.path) + "\r\n"
        }

        Text {
            id: resultText
            Layout.fillWidth: true
            Layout.fillHeight: true
        }
    }
}

Currently, data stored in the json file is not encrypted.

Be aware that, to use this function on Android, you will need to enable External Storage in your app's capabilities in ArcGIS AppStudio.

Property Documentation

fallbacksEnabled : bool

For internal use only.


[read-only] path : string

String value. Returns the directory path where the physical settings json file resides.


Signal Documentation

valueChanged( string key)

The signal executes whenever settings has been changed. You can also use it to know exactly which key-value pair has been changed. For example,

Component.onCompleted: { app.settings.setValue("names","bruce"); }

Connections { target: app.settings onValueChanged: console.log("Settings have been changed for ", key) //prints Settings have been changed for names. }


Method Documentation

bool boolValue(key)

Reads the boolean value of the provided key from the JSON file.

For example,

console.log(app.settings.colorValue("hasLoggedIn");

The key parameter

Key is the name the value will be stored under. For example, "hasSignedIn"


bool boolValue(key, bool defaultValue)

Reads the boolean value of the provided key from the JSON file. If the key doesn't exist it will create a new key and set its default value.

For example,

console.log(app.settings.boolValue("hasLoggedIn");

The key parameter

Key is the name the value will be stored under. For example, "hasSignedIn"

The defaultValue parameter

Boolean value.


color colorValue(key)

Use this to specifically return a color value.

For example,

console.log(app.settings.colorValue("backgroundColor");

The key parameter

Key is the name the value will be stored under. For example, "backgroundColor"


color colorValue(key, color defaultValue)

Optionally specify a default property.

For example,

console.log(app.settings.colorValue("backgroundColor", "blue");

The key parameter

Key is the name the value will be stored under. For example, "backgroundColor"

The defaultValue parameter

Color value. For example, "green", "#ffffff".

See also setColorValue().


bool contains(key)

Method to check a key-pair object exists within settings. Returns a boolean value. True if the key exists.

For example,

console.log ( app.settings.contains( "backgroundColor" ) );

The key parameter

Key is the name the value will be stored under. For example, "userName"


double numberValue(key)

Use this to specifically return a number value.

For example,

console.log(app.settings.numberValue("age");

The key parameter

Key is the name the value will be stored under. For example, "age"


double numberValue(key, double defaultValue)

Use this to specifically return a double value.

For example,

console.log(app.settings.numberValue("age");

The key parameter

Key is the name the value will be stored under. For example, "volume"

The defaultValue parameter

Double value. Can be a number (4) or a variable that is a double.


remove(key)

Method to remove a key-value pair from the settings.

For example,

app.settings.remove("userName");

The key parameter

Key is the name the value will be stored under. For example, "userName"


setColorValue(key, color value)

Method to specifically set color in a key-value pair in settings.

If a well known string is supplied, a hexadecimal value for that color will be stored. For example,

app.settings.setColorValue("backgroundColor", "yellow")

The key parameter

Key is the name the value will be stored under. For example, "backgroundColor"

The value parameter

Color value. For example, "green" or "#ffffff"

See also colorValue().


setValue(key, object value)

Method to set a key-value pair in settings.

For example,

app.settings.setValue("userName", "Indie")

The key parameter

Key is the name the value will be stored under. For example, "userName"

The value parameter

Object. For example, "Ashton", [21,5,15] or a variable.


setValue(key, object value, object defaultValue)

Optionally supply a default value for the method.

For example,

app.settings.setValue("userName", "Indie", "Ashton")

The key parameter

Key is the name the value will be stored under. For example, "userName"

The value parameter

Object. For example, "Ashton", [21,5,15] or a variable.

The defaultValue parameter

Object. For example, "Ashton", [21,5,15] or a variable.

See also value().


synchronize()

Writes any unsaved changes to permanent storage, and reloads any settings that have been changed in the meantime by another application.

For example,

Item {
        AppInfo {
                id: appInfo
        }

        appInfo.write();
}

object value(key)

Reads the value of the provided key from the json file.

For example,

var text = app.settings.value("username");
console.log ( text );

The key parameter

Key is the name the value will be stored under. For example, "userName".


object value(key, object defaultValue)

Reads the value of the provided key from the json file.

For example,

property string userName: app.settings.value("userName", "Ashley")
property int maxFeatures: app.settings.value("maxFeatures", 100)

The key parameter

Key is the name the value will be stored under. For example, "userName".

The defaultValue parameter

Object. For example, "Ashton", [21,5,15] or a variable.

See also setValue().