Real Software Forums

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/8LCp

Please 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.nr
Contact: tbg10101@gmail.com

If you're submitting apps to the Mac App Store, you really should be using NSUserDefaults/CFPreferences instead of writing your own file to the preferences folder.

Actually, Apple doesn't care how the file is managed so long as it is named correctly and is in the correct folder.

They might not reject your application, but it is not allowed. If you read through the "File-System Usage Requirements for the Mac App Store" section of the "Submitting to the Mac App Store" guide, you'll see that ~/Library/Preferences is not on the list of places you're allowed to write.

right, this should be known to all app store devlopers.
So please read again, and make sure.

Since you're using a module I'd recommend switching the global methods to public, otherwise the methods and properties are tossed into the completely global mix. It just makes more sense to call XPrefs every time outside of the module.

Otherwise it's great. It's a lot simpler than the other what I was using. I'll switch to yours. It'd be nice, though, to see an example of saving and loading custom classes (e.g. property classes).

@Jason_Adams:
Thanks! I will definitely change the scope of the methods for the next version.

I will also look into storing structures and classes but as of now I don't know how to do that. Do you have any pointers?

Well, after poking through your code, I feel like you already have the basis for saving custom classes. I'll walk you through my purpose, which you may include a similar example in your project.

I have a custom class which contains properties of a connection profile (i.e. address, port, a file name, etc.), and keep an array of this class for every instance the user creates. Within this class I created two methods: one for assigning, and one for retrieving a dictionary version of class. When I mean to store the class I retrieve the dictionary version and place it an array of dictionaries (via your module); upon loading I pull the array of dictionaries and reassign the dictionary to a new instance of the class and store it back into the array.

This method works due to the recursive method you use for nesting arrays and dictionaries.

Finally, on a side note, I added the following line to the Value (key As String) As Variant function as to avoid a KeyNotFoundException:



Hope this helps!

a: So why does it exist, who IS allowed to write there, and why?

b: Shouldnt you actually be writing to <username>/Library/Preferences ?

The 'preferred' way of writing preferences is by sending a command to the OS so it can manage the preferences, I think.

"~" is the user's home directory: http://en.wikipedia.org/wiki/Tilde#Directories_and_URLs

It exists for CFPreferences and NSUserDefaults or legacy applications who write their preferences there. While it is allowed for applications to write there outside of the Mac App Store, the App Store has tighter limitations and doing so will violate the rules.



This is the same as ~/Library/Preferences (the tilde expands to the user's home folder).



This isn't correct. The preferred way is to use CFPreferences or NSUserDefaults.

In general, using a shell is the wrong way to do anything if there's an available API to get the job done.

Is this going to be supported natively in RS? Personally I don’t care about the App Store and the restrictions that go with it (I even use my own preferred preference file format rather than a property list), but it looks like the only ‘legal’ way of managing preferences requires fiddling with declares.

macoslib has a CFPreferences wrapper. It could also have one for NSUserDefaults, were there interest. Cash would of course also be welcome.

New version is up! Tell me what you think. Thanks to all the people who had suggestion and bug reports!
Download: http://cl.ly/8LCp

------------------------------------
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

I just released XDB (X Database) as a lightweight database solution for RB developers.

Please use the XDB Light module as a replacement for XPrefs. It can only talk to a single file in the OS Applications Data folder.

The (regular) XDB module can handle as many files (wherever you want) as you want by setting the ActiveDB property and telling XDB to load a folderitem.

The XDB class is new. Each instance controls an XML file (wherever you want) of its own so now you can have a better DBMS interface. (typically one instance of XDB per table) The class is also a sub-class of Dictionary so there is less overhead for routine dictionary activities.

Download here: http://cl.ly/C3Fd

And tell me about any bugs!

-Tristan