system.getPreference()

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

Overview

Returns the requested preference's value.

Gotchas

Syntax

system.getPreference( category, name [, type] )
category (required)

String. Indicates where to read preferences from. Must be set to one of the following:

  • "app" — The application's custom preferences. These are defined by the Corona app developer.
  • "locale" — Accesses the operating system's read-only locale-related preferences.
  • "ui" — Accesses the operating system's read-only UI-related preferences.
name (required)

String. The unique name of the preference to read, depending on the category used:

  • "app" — A preference name written to storage by the Corona app developer via the system.setPreferences() function.
  • "locale" — Only supports preference names "country", "identifier", and "language".
  • "ui" — Only supports preference name "language".
type (optional)

String. Indicates the value type to be returned by this function. This type should match the preference value's type on storage. For example, all preferences belonging to the "locale" and "ui" categories are stored as strings and should be read as strings, while types for the "app" category should match the value types passed to the system.setPreferences() function. Accepted values include:

  • "string" (default)
  • "boolean"
  • "number"

Example

-- Print the operating system's read-only preferences
print( system.getPreference( "ui", "language" ) )        -- Print the UI (device) language, i.e. "en-US"
print( system.getPreference( "locale", "country" ) )     -- Print the locale country, i.e. "US"
print( system.getPreference( "locale", "identifier" ) )  -- Print the locale language identifier, i.e. "en_US"
print( system.getPreference( "locale", "language" ) )    -- Print the locale language code, i.e. "en"

-- 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" )