Managing settings

The SettingsManager provides access to user settings in the system. It allows you to observe and modify settings, see Available settings for a list of available settings. All settings are readable, but only settings marked as writable can be changed.

Observing settings

Subscribe to receive updates when a setting value changes. The SettingsManager provides type-specific observation methods: observeBooleanSetting, observeStringSetting, observeIntSetting, and observeFloatSetting.

1
import android.util.Log
2
import com.tomtom.automotive.integration.client.api.settings.SettingsManager
3
import com.tomtom.automotive.integration.client.api.settings.observesettings.ObserveSettingFailure
4
import com.tomtom.automotive.integration.client.api.settings.observesettings.ObserveSettingListener
5
import com.tomtom.automotive.integration.client.api.settings.observesettings.ObserveSettingParameters
6
import com.tomtom.automotive.integration.client.common.Callback
7
import com.tomtom.automotive.integration.client.common.Result
8
import com.tomtom.automotive.integration.client.common.SdkReleasable
9

10
private val TAG = "Settings"
11
private var observeSettingReleasable: SdkReleasable? = null
12

13
fun observeStringSetting(settingsManager: SettingsManager, settingKey: String) {
14
    observeSettingReleasable = settingsManager.observeStringSetting(
15
        ObserveSettingParameters(settingKey),
16
        object : ObserveSettingListener<String?> {
17
            override fun onValueChanged(value: Result<String?, ObserveSettingFailure>) {
18
                when (value) {
19
                    is Result.Success -> {
20
                        val settingValue = value.value
21
                        Log.d(TAG, "Setting '$settingKey' changed to: $settingValue")
22
                    }
23
                    is Result.Failure -> {
24
                        when (value.failure) {
25
                            ObserveSettingFailure.NOT_EXIST -> {
26
                                Log.e(TAG, "Setting '$settingKey' does not exist")
27
                            }
28
                            ObserveSettingFailure.WRONG_TYPE -> {
29
                                Log.e(TAG, "Setting '$settingKey' is not a string type")
30
                            }
31
                        }
32
                    }
33
                }
34
            }
35

36
            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
37
                Log.e(TAG, "Settings unavailable: ${reason.devMessage}")
38
            }
39
        }
40
    )
41
}
42

43
fun unObserveSetting() {
44
    observeSettingReleasable?.release()
45
    observeSettingReleasable = null
46
}

Saving settings

Modify writable settings using the type-specific save methods: saveBooleanSetting, saveStringSetting, saveIntSetting, and saveFloatSetting. Only settings marked as writable can be changed.

1
import android.util.Log
2
import com.tomtom.automotive.integration.client.api.settings.SettingsManager
3
import com.tomtom.automotive.integration.client.api.settings.savesettings.SaveSettingCallback
4
import com.tomtom.automotive.integration.client.api.settings.savesettings.SaveSettingFailure
5
import com.tomtom.automotive.integration.client.api.settings.savesettings.SaveSettingParameters
6
import com.tomtom.automotive.integration.client.common.Callback
7
import com.tomtom.automotive.integration.client.common.Result
8

9
private val TAG = "Settings"
10

11
fun saveStringSetting(settingsManager: SettingsManager, settingKey: String, value: String) {
12
    settingsManager.saveStringSetting(
13
        SaveSettingParameters(settingKey, value),
14
        object : SaveSettingCallback {
15
            override fun onSaveCompleted(result: Result<Unit, SaveSettingFailure>) {
16
                when (result) {
17
                    is Result.Success -> {
18
                        Log.d(TAG, "Setting '$settingKey' saved to: $value")
19
                    }
20
                    is Result.Failure -> {
21
                        when (result.failure) {
22
                            SaveSettingFailure.NOT_EXIST -> {
23
                                Log.e(TAG, "Setting '$settingKey' does not exist")
24
                            }
25
                            SaveSettingFailure.READ_ONLY -> {
26
                                Log.e(TAG, "Setting '$settingKey' is read-only")
27
                            }
28
                            SaveSettingFailure.WRONG_TYPE -> {
29
                                Log.e(TAG, "Setting '$settingKey' is not a string type")
30
                            }
31
                        }
32
                    }
33
                }
34
            }
35

36
            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
37
                Log.e(TAG, "Settings unavailable: ${reason.devMessage}")
38
            }
39
        }
40
    )
41
}

Error handling

Observation failures

The ObserveSettingFailure enum describes possible failure reasons when observing settings:

NOT_EXIST - A setting with the given key doesn’t exist
WRONG_TYPE - The key references a setting of a different type

Save failures

The SaveSettingFailure enum describes possible failure reasons when saving settings:

NOT_EXIST - A setting with the given key doesn’t exist
READ_ONLY - The setting is defined as read-only and cannot be modified
WRONG_TYPE - The key references a setting of a different type