Settings Service

_|

The Magic Lane SDK for Android provides functionality for storing key-value pairs in permanent storage. This is managed via the SettingsService class.

The settings are saved within a .ini file.

Create a Settings Service

You can create or open a settings storage using the factory method of SettingsService. If no path is provided, a default one will be used:

Kotlin

val settings = SettingsService.produce(null)

Java

SettingsService settings = SettingsService.produce(null);

Or a custom path can be provided:

Kotlin

val settings = SettingsService.produce("/custom/settings/path")

Java

SettingsService settings = SettingsService.produce("/custom/settings/path");

You can also access the current file path where the settings are stored:

Kotlin

val currentPath = settings?.path

Java

String currentPath = settings != null ? settings.getPath() : null;

Add and get values

You can store various types of data using appropriate set methods:

Kotlin

settings?.setStringValue("username", "john_doe")
settings?.setBooleanValue("isLoggedIn", true)
settings?.setIntValue("launchCount", 5)
settings?.setLongValue("highScore", 1234567890123L)
settings?.setDoubleValue("volume", 0.75)

Java

if (settings != null) {
    settings.setStringValue("username", "john_doe");
    settings.setBooleanValue("isLoggedIn", true);
    settings.setIntValue("launchCount", 5);
    settings.setLongValue("highScore", 1234567890123L);
    settings.setDoubleValue("volume", 0.75);
}

To retrieve values, use the corresponding get methods. These methods take an optional defaultValue parameter which is returned when the key could not be found in the selected group. The defaultValue does not set the value.

Kotlin

val username = settings?.getStringValue("username", "guest")
val isLoggedIn = settings?.getBooleanValue("isLoggedIn", false)
val launchCount = settings?.getIntValue("launchCount", 0)
val highScore = settings?.getLongValue("highScore", 0L)
val volume = settings?.getDoubleValue("volume", 1.0)

Java

String username = settings != null ? settings.getStringValue("username", "guest") : "guest";
boolean isLoggedIn = settings != null ? settings.getBooleanValue("isLoggedIn", false) : false;
int launchCount = settings != null ? settings.getIntValue("launchCount", 0) : 0;
long highScore = settings != null ? settings.getLongValue("highScore", 0L) : 0L;
double volume = settings != null ? settings.getDoubleValue("volume", 1.0) : 1.0;

When the set is made on a type and the get is made on another type, a conversion is done. For example:

Kotlin

settings?.setIntValue("count", 1234)

val value = settings?.getStringValue("count") // Returns "1234"

Java

if (settings != null) {
    settings.setIntValue("count", 1234);
}

String value = settings != null ? settings.getStringValue("count") : null; // Returns "1234"

Tip

Each change may take up to one second to be written to storage. Use the flush method to ensure the changes are written to permanent storage.

Groups

Groups allow you to organize settings in logical units. The default group is DEFAULT. Only one group can be active at a time, and nested groups are not allowed.

Kotlin

// All operations above this are made inside DEFAULT
settings?.beginGroup("USER_PREFERENCES")

// All operations here are made inside USER_PREFERENCES

settings?.beginGroup("OTHER_SETTINGS")

// All operations here are made inside OTHER_SETTINGS

settings?.endGroup()
//All operations below this are made inside DEFAULT

Java

// All operations above this are made inside DEFAULT
if (settings != null) {
    settings.beginGroup("USER_PREFERENCES");
}

// All operations here are made inside USER_PREFERENCES

if (settings != null) {
    settings.beginGroup("OTHER_SETTINGS");
}

// All operations here are made inside OTHER_SETTINGS

if (settings != null) {
    settings.endGroup();
}
// All operations below this are made inside DEFAULT

In order to get the current group use the groupName property:

Kotlin

val currentGroup = settings?.groupName

Java

String currentGroup = settings != null ? settings.getGroupName() : null;

danger

The values passed to beginGroup are converted to upper-case.

Tip

A flush is automatically done after the group is changed.

Remove values

Remove value by key

The remove method takes the key (or a pattern) and returns the number of deleted entries from the current group.

Kotlin

val removedCount = settings?.remove("username")

Java

int removedCount = settings != null ? settings.remove("username") : 0;

Clear all values

Use the clear method which removes all the settings from all the groups.

Kotlin

settings?.clear()

Java

if (settings != null) {
    settings.clear();
}