As many of you might know, the preferences solution called BPrefs from Dreystone Software finally died with the release of Real Studio 2011r2. I decided to make my own preference file solution that makes plain-text XML plist documents that conforms to Apple's guidelines. I also decided to make it free! Download an example project with
XPrefs module included here:
http://cl.ly/8LCpPlease test the module out and post improvements below!
About
XPrefs:
XPrefs is a module that simplifies the task of storing preferences in an XML file.
Xprefs makes storing and loading preferences easy by using the Dictionary interface. Simply call '
XPrefs' like you would a global Dictionary object using KEY/VALUE pairs.
Xprefs preference files are located in the SpecialFolder.Preferences folder and can be read/manipulated using the Plist Editor included in Apple's developer tools.
XPrefs is strongly based on BPrefs from Dreystone Software. (
http://www.dreystone.com)
------------------------------------
Using
XPrefs:
------------------------------------
Change the constant called PREFERENCES_FILE_NAME to the following values
-Mac OS X:
--The application's Bundle Identifier followed by ".plist". This is a MUST for apps that are being submitted to the App Store!
-Windows/Linux:
--Whatever you want, there are no guidlines for these platforms.
DICTIONARY WRAPPER FUNCTIONS:
-
XPrefs.Clear()
--Deletes all key/value pairs.
-
XPrefs.HasKey(key) As Variant
--Checks to see if the passed key exists.
-
XPrefs.Remove(key)
--Deletes the passed key and associated value.
-
XPrefs.Value(key) = Variant
--Sets a key/value pair.
-
XPrefs.Value(key) As Variant
--Gets the value associated with the passed key.
PREFERENCE FILE FUNCTIONS:
-
XPrefs.Save()
--Saves the preferences in their current state. Put this in places that you want to trigger a save. Not neccesary if the autosave feature is enabled.
-
XPrefs.ToString() as String
--Use this to view the preferences file in raw XML format as it will be saved to the disk. (usually for testing purposes only)
-
XPrefs.File() as Folderitem
--Returns the preferences folderitem on disk.
-
XPrefs.AutoSave as Boolean
--If this property is true, the preferences will save whenever a value is changed.
PREFERENCE PROGRESS WINDOW:
-The window XPrefsSaving is simply a way to let your user see that the application is active while saving large preference files. Simply set the SaveAlertWait property to determine how long
XPrefs should wait (in seconds) to display the window. The reccomended time is 2 seconds. Set SaveAlertWait to a negative number to disable the window completely.
ERROR CODES:
-Check the error status of the last save by reading the LastErrorCode property. You can test it against one of the error constants.
--101 - OutputInterrupted
---The file write was interrupted. An example of this is a thread that uses
XPrefs bing paused by a menu bar interaction.
--102 - AccessDenied
---Access to the preference file was denied.
--103 - NotEnoughMemory
---You ran out of memory.
--104 - FileInUse
---The preference file is already in use.
--105 - InvalidName
---The PREFERENCES_FILE_NAME constant is not a valid file name.
------------------------------------
Release Notes:
------------------------------------
Version 1.6.4 -- (July 10, 2011)
-[NEW] Added SaveAlertWait as Double for long save times
-[NEW] Added XPrefsSaving as Window for long save times
-[NEW] Added LastErrorCode as Integer in case something goes wrong
-[NEW] Added error code constants in case something goes wrong
-[NEW] Added Access as Semaphore for multithreading
-[NEW] Replaced slow string processor with RegEx for speed reasons
-[FIX] Optimized portions of the code
-[FIX] Changed scope of many methods, properties, and constants
-[FIX] Corrupt preferences no longer crash
XPrefs -[FIX] Fixed a KeyNotFoundException
Version 1.0 -- (June 25, 2011)
-[NEW] Initial Release
Contact:
Author: 10101 Software
Website:
http://www.10101software.co.nrContact:
tbg10101@gmail.com