-
Notifications
You must be signed in to change notification settings - Fork 14
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.
- Activate the preferences framework helper
- Set the preferences file name
- Set default preferences values
- Set a preference to a value
- Get a preference value
- API
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:
- folder: ./helpers
- filename: "[[FRAMEWORK]]/helpers/preferences"
You set 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:
You can set an optional default preferences filename for all platforms and then override it for specific platforms. So this:
preferences filename:
user:
default: My Application.prefs
macos: com.mycompany.myapplication
windows:
linux:
ios:
android:
Will cause your application to create and use these user preferences file names:
| Platform | Preferences File Name |
|---|---|
| macOS | com.mycompany.myapplication |
| Windows | My Application.prefs |
| Linux | My Application.prefs |
| iOS | My Application.prefs |
| Android | My Application.prefs |
Note that in this example the default: preferences file name is used for all platforms except for macOS where it is overridden with the macos: file name.
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
While your application is running you can set an application preference to a value with the prefsSetPref command. If the preference does not already exist, it will be created and set to the value.
prefsSetPref "my preference 1", "a string value"
prefsSetPref "my preference 2", 80
prefsSetPref "my preference 3", false
While your application is running you can get a preference value with the prefsGetPref function.
put prefsGetPref("my preference name") into tPreferenceValue
Type: function
Syntax: prefsGetDefaults(<pUserOrShared>)
Summary: Returns the entire array of default preferences.
Returns: Array representing YAML configuration store in prefs.yml and prefs_shared.yml
Parameters:
| Name | Description |
|---|---|
pUserOrShared |
Preferences category. "user" or "shared". Default is "user". |
Type: function
Syntax: prefsGetPref(<pKey>,<pUserOrShared>)
Summary: Gets an application preference.
Returns: value
Parameters:
| Name | Description |
|---|---|
pKey |
Name of preference to get. |
pUserOrShared |
Preferences category. "user" or "shared". Default is "user". |
Type: function
Syntax: prefsGetPreferenceFile(<pUserOrShared>)
Summary: Returns the file where preferences are stored.
Returns: Filename or empty
Parameters:
| Name | Description |
|---|---|
pUserOrShared |
Preferences category. "user" or "shared". Default is "user". |
Description:
Returns the filename of the preference file. If an external is being used on OS X then empty will be returned.
Type: function
Syntax: prefsIsPrefSet(<pKey>,<pUserOrShared>)
Summary: Checks if a preference has been set on the computer the application is running on.
Returns: true/false
Parameters:
| Name | Description |
|---|---|
pKey |
Name of preference to check. |
pUserOrShared |
Preferences category. "user" or "shared". Default is "user". |
Type: command
Syntax: prefsReload <pUserOrShared>
Summary: Reloads preferences from the file on disk.
Returns: Empty
Parameters:
| Name | Description |
|---|---|
pUserOrShared |
Preferences category. "user" or "shared". Default is "user". |
Description:
This handler will clear out any values that are stored internally and reloads preferences from the file on disk.
Note that this command does nothing on OS X which handles preferences using Cocoa APIs.
Type: command
Syntax: prefsReset <pUserOrShared>
Summary: Resets all values in in preferences to empty.
Returns: Empty
Parameters:
| Name | Description |
|---|---|
pUserOrShared |
Preferences category. "user" or "shared". Default is "user". |
Description:
Use this handler if you would like to reset all preferences to their default values as defined
in prefs.yml and prefs_shared.yml.
Note that on OS X this command currently does not work.
Type: command
Syntax: prefsSave <pUserOrShared>
Summary: Saves preferences to disk.
Returns: Error message
Parameters:
| Name | Description |
|---|---|
pUserOrShared |
Preferences category. "user" or "shared". Default is "user". |
Description:
When setting preferences the preference is updated in memory. To permanently store changes on disk use this command.
Type: command
Syntax: prefsSetPref <pKey>,<pValue>,<pUserOrShared>,<pType>
Summary: Sets an application preference.
Returns: error message
Parameters:
| Name | Description |
|---|---|
pKey |
Name of preference to set. |
pValue |
Value to set preference to. This can be a string or an array. |
pUserOrShared |
Preferences category. "user" or "shared". Default is "user". |
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. |
Levure is an application development framework written for LiveCode.