Introducing new preference storage features

21 September 2016

Introducing new preference storage features

Many developers have requested the ability to set “preferences” within their apps as a way to store settings and other small amounts of data without having to load, parse, and save a file in the operating system.

For Windows apps, this could mean having access to registry settings, or for macOS, iOS, and tvOS, the ability to read and write from the app’s NSUserDefaults. This is especially important for tvOS since apps cannot rely on a saved settings file (tvOS may remove files from system.DocumentsDirectory if it needs storage space for other apps).

In response, Corona’s engineers have added functionality to the existing system.getPreference() API and they have created two new APIs in system.setPreferences() and system.deletePreferences().

Here are some important things to understand about this set of APIs:

• Previously, system.getPreference() was used to get read-only information about the user interface (UI) and locale settings. We have extended this API to allow you to retrieve key-value pairs in a cross-platform manner.
• system.getPreference() is singular and retrieves a single value based on the key.
• system.setPreferences() and system.deletePreferences() are plural and accept a table of multiple entries to facilitate better performance.
• These are storage-related APIs — they are not designed to create or manage any UI elements within the particular operating system.
• Only numbers, booleans, and strings are supported. If you need to save a table of data, you can use json.encode() to encode the table and then save it as a string.
• These APIs are designed to store small amounts of data. If you need to save large amounts of data, consider the traditional methods of using a stored file/database or cloud storage.
• Setting and deleting preferences are blocking actions and can affect performance. This is more noticeable on some operating systems than others (Android is the most costly, followed by Windows; Apple platforms perform the best).
• Apps running in the Corona Simulator will have their own preferences on a per-app basis. Apps built to run on Windows or macOS will have their own settings.
• These APIs are not currently available for Windows Phone 8.
• On Windows, preferences are stored in an SQLite database by default. If you’re interested in having preferences saved in the Windows registry, there are a few additional things to be aware of. Please see the Creating Win32 Desktop Apps guide for more details.

In conclusion

These APIs are available in major build 2016.2949. Click on the documentation links above to learn more about each individual API, as well as the Win32 setup options. Finally, feel free to join us in the Corona Forums to discuss these features further.