XPreferences Reference

Synopsis

XPreferences is an AppleScript Library to help saving and loading settings(preferences) of an AppleScript application.

Because AppleScript applications (droplets, applets and script files) can keep values in properties after the termination of the execution, properties can be used to store settings. But values of properties will be initialized when the script is recompiled to fix bugs or to implement new functions.

Therefore, even in the case of AppleScript, it is useful to save settings in an external file.

XPreferences help to load and save a user defined script object to store settings (preferences script object) into "~/Library/Preferences" folder.

Also XPreferences support to update the preferences script object. When your AppleScript application is updated and the specification of the preferences script object is changed, XPreferences help to move values from old preferences script object to new one. (see Update preferences script object )

How to Use

  1. Define a script object to store settings (prefereces script object).
  2. Pass the script to XPreferences by using set_default_prefs.
  3. Load saved setttings as a script object (preferences script object).
  4. Obtain values from the preferences script object.
  5. Do your task.
  6. Update values in the preferences script object before termination of your script.
  7. Save the preferences script object by using save_current_prefs.

Example

use scripting additions
use XPreferences : script "XPreferences"

on setup()
script XPreferencesSampleSettings
property parent : AppleScript -- reduce size of the preferences file.
property version : "1.0" -- optional
property _msg : "hello"

on message()
return my _msg
end message

on set_message(v)
set my _msg to v
return me
end set_message

on update(old_settings) -- optional
set my _msg to old_settings's _msg
end update
end script

tell XPreferences
set_default_prefs(XPreferencesSampleSettings)
end tell
end setup

on run
setup()
set prefs to XPreferences's load()
display alert (prefs's message())
prefs's set_message("Hi")
XPreferences's save_current_prefs()
end run

Update preferences script object

To allow to update preference script object (e.g. adding new settings), the preference script object has a "version" property and "update" method.

If the default preferences script object passed to set_default_prefs has "version" property and its value is greather than the value of the "version" property of loaded preferences script object, preferences script object will be updated with following steps.

  1. Copy the default preferences script object.
  2. The "update" handler of new preferences object will recieve old loaded preferences script object.
  3. Copy values form old loaded preferences script object by your self in the update handler.

Methods

set_default_prefs

Set a default preferences as a script object.

set_pref_name

Set a file name of a preference file.

load

Load saved prefereces script object.

save_current_prefs

Save the preferences script object stored in XPreferences into a file.

save_as_pefs

Save a script object as a preferences script object into a file.

prefs

Obtain current preferences script object stored in XPreferences.