Settings QML Type

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

Import Statement:	import ArcGIS.AppFramework 1.0
Inherited By:	AppPlayerSettings

List of all members, including inherited members

Properties

fallbacksEnabled : bool
path : string

Signals

valueChanged(string key)

Methods

bool boolValue(string key)
bool boolValue(string key, bool defaultValue)
color colorValue(string key)
color colorValue(string key, color defaultValue)
bool contains(string key)
double numberValue(string key)
double numberValue(string key, double defaultValue)
remove(string key)
setColorValue(string key, color value)
setValue(string key, object value)
setValue(string key, object value, object defaultValue)
synchronize()
object value(string key)
object value(string key, object defaultValue)

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. }

Note: The corresponding handler is onValueChanged.

Method Documentation

bool boolValue(string key)

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

For example,

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

The key parameter

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

bool boolValue(string 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(string 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(string 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(string 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(string 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(string 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(string 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(string 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(string 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(string 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(string 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(string 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().