system.setPreferences()

Type Function

Library system.*

Return value Boolean

Revision Release 2024.3703

Keywords system preference, setPreferences

See also system.getPreference()

system.deletePreferences()

Overview

Writes a table of preference values to storage. If any of the given preferences do not exist in storage, they will be inserted. If any of the given preferences already exist in storage, they will be overwritten.

Returns true if all of the given preferences were written to storage successfully. Returns false if at least one of the given preferences failed to be written to storage.

Gotchas

This function is a blocking call and it won’t return a result until all of the given preferences have been written to storage. As a result, this function may cause performance issues and it should not be called frequently, during active gameplay, or in a UI object’s listener function. For best performance, it’s best to write multiple preferences via a single call after leaving a scene or during an "applicationExit" system event.

Syntax

system.setPreferences( category, preferences )

category _^(required)

String. Indicates which set of preferences should be accessed on the system. Currently, only the "app" category is supported — this is the application’s custom preferences defined by the Corona app developer.

preferences _^(required)

Table. Table of preferences to be written to storage. This table should contain key-value pairs where the key is the unique name of the preference and its value is either a boolean, number, or string.

Example

-- Write this app's custom preferences to storage
local appPreferences =
{
    myBoolean = true,
    myNumber = 123.45,
    myString = "Hello World"
}
system.setPreferences( "app", appPreferences )

-- Read the preferences that were written to storage above
local myBoolean = system.getPreference( "app", "myBoolean", "boolean" )
local myNumber = system.getPreference( "app", "myNumber", "number" )
local myString = system.getPreference( "app", "myString", "string" )

Type	Function
Library	system.*
Return value	Boolean
Revision	Release 2024.3703
Keywords	system preference, setPreferences
See also	system.getPreference()
	system.deletePreferences()