Helper preferences

Levure provides your LiveCode application with a preferences management system.

On Macintosh OS X an external is used so you can set preferences using the OS X APIs. On Windows, Linux, iOS, and Android preferences are stored in a file containing data serialized using arrayEncode.

Contents

• Activate the preferences framework helper
• Specify the preferences file name
• Set default preferences values
• Set a preference to a value
• Get a preference value

Activate the preferences framework helper

The levure/framework/helpers/preferences helper provides an API for managing your application preferences. By default this helper is activated for you in app.yml:

# app.yml

helpers:
  1:
    folder: ./helpers
  2:
    filename: {{FRAMEWORK}}/helpers/preferences

Specify the preferences file name

You specify the preferences file name for the platforms your application supports in app.yml. You can provide an optional default file name for all platforms and then override it for specific platforms.

The preferences file is stored in the folder returned by levureApplicationDataFolder() on all platforms except macOS, where it is stored in ~/Library/Preferences, so you should specify only the name of the preferences file without any other path information.

IMPORTANT: Do not use quote marks around your strings in app.yml.

# app.yml

preferences filename:
  user:
    default:
    macos:
    windows:
    linux:
    ios:
    android:
  shared:
    default:
    macos:
    windows:
    linux:

Examples

You can set an optional default preferences filename for all platforms and then override it for specific platforms. So this:

preferences filename:
  user:
    default: com.mycompany.myapplication
    macos:
    windows: My Application.prefs
    linux: My Application.prefs
    ios:
    android:

Will cause your application to create and use these user preferences file names:

Platform	Preferences File Name
Mac OS	com.mycompany.myapplication
Windows	My Application Preferences
Linux	My Application Preferences
iOS	com.mycompany.myapplication
Android	com.mycompany.myapplication

Set default preferences values

You set default preferences values in a prefs.yml file that sits alongside app.yml in your app folder. You specify the default values by entering them as name: value pairs, one preference per line.

IMPORTANT: Do not use quote marks around your strings in prefs.yml.

my preference 1: my preference 1 default value
my preference 2: 100
my preference 3: true

Set a preference to a value

While your application is running you can set an application preference to a value with the appSetPref command. If the preference does not already exist, it will be created and set to the value.

appSetPref "my preference name", "my preference value"

The full syntax is:

appSetPref <pKey>, <pValue>, <pUserOrShared>, <pType>

Parameters:

Name	Description
pKey	Pass in name of preference to set.
pValue	Pass in value to set preference to. This can be a string or an array.
pUserOrShared	Pass in "shared" to set a pref in shared preferences. Leave empty for default behavior.
pType	Pass in "binary" to force pref to be stored as binary (OS X). By default if value contains NULL then it will be stored as binary.

Get a preference value

While your application is running you can get a preference value with the appGetPref function.

put appGetPref("my preference name") into tPreferenceValue

The syntax is:

appGetPref(<pKey>)

Returns: Value of a preference.

Parameters:

Name	Description
pKey	Pass in name of preference whose value you want to get.