From The Blog: Introducing new preference storage features

[CoronaBot]

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.

View the full article

[funkyvisions]

I’ve started playing with this.  Where are the preferences stored in the simulator?  I’d like to periodically clear them out.  I looked under

~/Library/Application Support/Corona Simulator

which is where the sqlite data use to be for my app (that I am converting to preferences), but I don’t see anything.  Thanks.

[roaminggamer]

Look under your sandbox in the .system folder

You’ll see a file called: CoronaPreferences.sqlite

[funkyvisions]

I looked through my entire filesystem (MacOS) and I don’t have a file called CoronaPreferences.sqlite ANYWHERE on my drive.  The sandbox only shows me these directories.

iMac:Library doug$ ls -a -l  ~/Library/Application\ Support/Corona\ Simulator/buttermilk-82E60786AD31B97D35A0E9D48AF094B4

total 16

drwxr-xr-x   6 doug  staff   204 Sep 24 14:03 .

drwxr-xr-x  20 doug  staff   680 Sep 24 14:22 …

-rw-r–r--@  1 doug  staff  6148 Sep 24 14:13 .DS_Store

drwxr-xr-x   6 doug  staff   204 Sep 24 14:58 Caches

drwxr-xr-x   3 doug  staff   102 Sep 24 14:04 Documents

drwxr-xr-x   2 doug  staff    68 May 28  2015 tmp

 

iMac:Library doug$ ls -a -l  ~/Library/Application\ Support/Corona\ Simulator/buttermilk-82E60786AD31B97D35A0E9D48AF094B4/Caches/

total 64

drwxr-xr-x  6 doug  staff   204 Sep 24 14:58 .

drwxr-xr-x  6 doug  staff   204 Sep 24 14:03 …

-rw-r–r--@ 1 doug  staff  6148 Sep 24 14:04 .DS_Store

-rw-r–r--  1 doug  staff  8192 Sep 24 14:58 purchases.ice

-rw-r–r--  1 doug  staff  8192 Sep 24 14:58 scores.ice

-rw-r–r--  1 doug  staff  8192 Sep 24 14:58 settings.ice

 

iMac:Library doug$ ls -a -l  ~/Library/Application\ Support/Corona\ Simulator/buttermilk-82E60786AD31B97D35A0E9D48AF094B4/Documents/

total 16

drwxr-xr-x  3 doug  staff   102 Sep 24 14:04 .

drwxr-xr-x  6 doug  staff   204 Sep 24 14:03 …

-rw-r–r--@ 1 doug  staff  6148 Sep 24 14:04 .DS_Store

 

iMac:Library doug$ ls -a -l  ~/Library/Application\ Support/Corona\ Simulator/buttermilk-82E60786AD31B97D35A0E9D48AF094B4/tmp/

total 0

drwxr-xr-x  2 doug  staff   68 May 28  2015 .

drwxr-xr-x  6 doug  staff  204 Sep 24 14:03 …

 

I ended up just calling deletePreferences to get rid of them, but I’d still like to know where they are.

[roaminggamer]

Sorry.  Windows user here.  I should have said as much, but I made the assumption there would be a similar folder in the sandbox on Mac.

I’d also like to hear where this lives for the same reasons as you.

-Ed

[rob]

On a Mac, they are stored in .plist files. In many cases these are binary files. The location is:

/Users/yourhomedir/Library/Preferences/com.coronalabs.Corona_Simulator.plist.

However you should not edit this file. You use the “defaults” command:

defaults read com.coronalabs.Corona\_Simulator

Of course this will dump a ton of infomation: every app you’ve build, every simulator setting, stored project directories etc are in here.  The actual preferences for your app will be something like:

defaults read com.coronalabs.Corona\_Simulator appPreferences/961f35261fb74561587efd5007e5413c/music

will print out the value of the app’s music setting. The big long hex number should be the long number (in lower case) that you see when you do a “Show Project Sandbox”. There isn’t a good way to get all the keys for any given app.

You use defaults write to change values and defaults delete to remove them. Honestly if you want to clean them, add a temporary button to your UI that calls system.deletePreferences().

Rob

[funkyvisions]

Thanks Rob for the detailed explanation!  It’s all working perfectly and I’m gonna submit an update to my Apple TV game.  I’d been using the cache directory in the meantime, but we know that’s not safe.  I can’t wait for game center support so I can turn my game center stuff back on and not just be doing local scoreboards like I’m doing with preferences.

Oh, and as far as dumping all the keys for a given app.  This worked.

defaults read com.coronalabs.Corona_Simulator | grep 82e60786ad31b97d35a0e9d48af094b4

[r_donato]

I love this functionality. I fully intend to use it in my app.

[sirmania]

This is a lovely feature. I really liked the loadsave module, but this is easier to use.

@funkyvisions

Oh, and as far as dumping all the keys for a given app.  This worked.

defaults read com.coronalabs.Corona_Simulator | grep 82e60786ad31b97d35a0e9d48af094b4

I can’t seem to understand how to dump all the keys like you do funkyvisions  :unsure:

[rob]

@sirmania, @funkyfishions executed a command line command through the Mac’s “terminal” app that gives you access to the operating system’s command line.

“defaults” is the command that lets you manage user preferences on the Mac. For your simulator run versions of your apps, all of your preferences are stored in the com.coronalabs.Corona_Simulator preferences. To keep each of your simulator apps apart we generate a string similar to “82e60786ad31b97d35a0e9d48af094b4” but it will be different for each app. From the simulator you can load your app, and look in the console log window that we open and look for a line like this:

Oct 09 12:01:45.509 Project sandbox folder: ~/Library/Application Support/Corona Simulator/TurkeysRevenge- 1A1B9255FFAB34A09DDEB391EBF1CD9B

where it tells you the sandbox folder. That long number is your per-app ID that you can use to look up your keys. However that string has all the letters uppercased, but in the defaults they are lowercased. Never fear a simple change in the command will work for you without having to retype everything in lower case:

defaults read com.coronalabs.Corona_Simulator | grep -i 1A1B9255FFAB34A09DDEB391EBF1CD9B

 

The | command says to take the output from the first command and make it the input of the second command. The “grep” command is basically a search command and will filter out anything that doesn’t match what you typed in to look for.  The addition I added was the “-i” parameter which says to “ignore case” which is the magic to let it match your string with uppercase characters against the output of “defaults” which is lower case. This will filter out everything except those that match your app.

 

Rob

[sirmania]

Aha!

Thanks a lot Rob 

I didn’t notice @funkyfishions used small characters.

The -i parameter is nice to know about.

Thanks a lot for explaining so thoroughly. 

[techdojo]

This is a great feature, but having to put a hidden UI button in to clear out preferences is a bit of a pain.

It would be great if in a future version there was a separate .plist in the sandbox so it could be cleared out manually.

Just my $0.02

[rob]

I don’t think too many people need a hidden UI button in production apps. For mobile devices, it shouldn’t be much different than it is now with a save settings file, you delete the app from your device and re-install a new one.

For desktop solutions on the Mac you have a command line command “defaults” that can be used to manage resetting things. On Windows, if you choose the Registry model you can use regedit.exe to deal with them. 

The simulator is a little more complex. It’s like desktops, but with the difference that all the settings are stored in the Corona Simulator’s preferences, not the apps, so you have to know your app’s unique signature and find that with either “defaults” or “regedit” to manage them. But in either case with the right information you could write the necessary command line scripts (batch files) to automate your needs.

[funkyvisions]

I’ve started playing with this.  Where are the preferences stored in the simulator?  I’d like to periodically clear them out.  I looked under

~/Library/Application Support/Corona Simulator

which is where the sqlite data use to be for my app (that I am converting to preferences), but I don’t see anything.  Thanks.

[roaminggamer]

Look under your sandbox in the .system folder

You’ll see a file called: CoronaPreferences.sqlite

[funkyvisions]

I looked through my entire filesystem (MacOS) and I don’t have a file called CoronaPreferences.sqlite ANYWHERE on my drive.  The sandbox only shows me these directories.

iMac:Library doug$ ls -a -l  ~/Library/Application\ Support/Corona\ Simulator/buttermilk-82E60786AD31B97D35A0E9D48AF094B4

total 16

drwxr-xr-x   6 doug  staff   204 Sep 24 14:03 .

drwxr-xr-x  20 doug  staff   680 Sep 24 14:22 …

-rw-r–r--@  1 doug  staff  6148 Sep 24 14:13 .DS_Store

drwxr-xr-x   6 doug  staff   204 Sep 24 14:58 Caches

drwxr-xr-x   3 doug  staff   102 Sep 24 14:04 Documents

drwxr-xr-x   2 doug  staff    68 May 28  2015 tmp

 

iMac:Library doug$ ls -a -l  ~/Library/Application\ Support/Corona\ Simulator/buttermilk-82E60786AD31B97D35A0E9D48AF094B4/Caches/

total 64

drwxr-xr-x  6 doug  staff   204 Sep 24 14:58 .

drwxr-xr-x  6 doug  staff   204 Sep 24 14:03 …

-rw-r–r--@ 1 doug  staff  6148 Sep 24 14:04 .DS_Store

-rw-r–r--  1 doug  staff  8192 Sep 24 14:58 purchases.ice

-rw-r–r--  1 doug  staff  8192 Sep 24 14:58 scores.ice

-rw-r–r--  1 doug  staff  8192 Sep 24 14:58 settings.ice

 

iMac:Library doug$ ls -a -l  ~/Library/Application\ Support/Corona\ Simulator/buttermilk-82E60786AD31B97D35A0E9D48AF094B4/Documents/

total 16

drwxr-xr-x  3 doug  staff   102 Sep 24 14:04 .

drwxr-xr-x  6 doug  staff   204 Sep 24 14:03 …

-rw-r–r--@ 1 doug  staff  6148 Sep 24 14:04 .DS_Store

 

iMac:Library doug$ ls -a -l  ~/Library/Application\ Support/Corona\ Simulator/buttermilk-82E60786AD31B97D35A0E9D48AF094B4/tmp/

total 0

drwxr-xr-x  2 doug  staff   68 May 28  2015 .

drwxr-xr-x  6 doug  staff  204 Sep 24 14:03 …

 

I ended up just calling deletePreferences to get rid of them, but I’d still like to know where they are.

[roaminggamer]

Sorry.  Windows user here.  I should have said as much, but I made the assumption there would be a similar folder in the sandbox on Mac.

I’d also like to hear where this lives for the same reasons as you.

-Ed

[rob]

On a Mac, they are stored in .plist files. In many cases these are binary files. The location is:

/Users/yourhomedir/Library/Preferences/com.coronalabs.Corona_Simulator.plist.

However you should not edit this file. You use the “defaults” command:

defaults read com.coronalabs.Corona\_Simulator

Of course this will dump a ton of infomation: every app you’ve build, every simulator setting, stored project directories etc are in here.  The actual preferences for your app will be something like:

defaults read com.coronalabs.Corona\_Simulator appPreferences/961f35261fb74561587efd5007e5413c/music

will print out the value of the app’s music setting. The big long hex number should be the long number (in lower case) that you see when you do a “Show Project Sandbox”. There isn’t a good way to get all the keys for any given app.

You use defaults write to change values and defaults delete to remove them. Honestly if you want to clean them, add a temporary button to your UI that calls system.deletePreferences().

Rob

[funkyvisions]

Thanks Rob for the detailed explanation!  It’s all working perfectly and I’m gonna submit an update to my Apple TV game.  I’d been using the cache directory in the meantime, but we know that’s not safe.  I can’t wait for game center support so I can turn my game center stuff back on and not just be doing local scoreboards like I’m doing with preferences.

Oh, and as far as dumping all the keys for a given app.  This worked.

defaults read com.coronalabs.Corona_Simulator | grep 82e60786ad31b97d35a0e9d48af094b4

[r_donato]

I love this functionality. I fully intend to use it in my app.