Preferences.txt

Binaries for BeOS Release 2 for PowerPC, source for *hopefully* any release.

Overview

The concept of this class is to make it easy for applications to have access to a preferences file which can be easily located, and easily used throughout the course of development and also effectively used as new versions are released.

The use I have intended for it is for the case of an application which has one preferences file for all of its 'preferred' data. The file is intended to be open for the duration of the application. Since no other application would be using this application's preferences it shouldn't be a problem.

Why use this code?

Don't you want to have a nice easy way of integrating preferences into your application? Want to be able to use something quickly in any application? Want it to be smart about new versions, and which application owns a file?

Hopefully I've got most of it!

Associated files

Example Preferences Application	-- example app for BeOS Release 2 for PowerPC.
Example-App-Settings			-- example app preferences file
Example.cp					-- example app source code
Example.h					-- example app source header
Example.project				-- example app project
Preferences.cp				-- source code
Preferences.h				-- header
Preferences.project			-- a project file for building the shared library
Preferences.so				-- the shared library
Preferences.txt				-- this file!

There are two ways to use this code in your project:

1.	Copy the source code and the header file into your project, and away you go.

2.	Copy the shared library to /boot/home/config/lib/ and use the header file to define it.
	Your application won't contain the code, just references to it. The code will be linked
	dynamically at run time by the kernel. At least I think that's the way it works!

Note: the example application requires you to use method 2, copying Preferences.so to /boot/home/config/lib/.

Implementation

This class will manage a preferences file for an application. The prefs file will remain open for as long as this object is active. You can implement this class by making a subclass, or by using it as it is.

My prefered method of using it is by creating a sub-class. All a a subclass needs to override is the function:

	virtual void AddDefaultData();

which creates the default data. Be sure to call the inherited function as it creates the data required to identify the file as being a preferences file for this application, and which version it is.

For further customisation the sub-class can also over-ride these functions:

	virtual void OpenCreate();

This function is called by Open() to create a new file. Be careful changing how this one works, it may have adverse effects on the bigger picture.

	virtual void Update();

This function is also called by . It is called when the existing preferences file belongs to the current application, but is an older version than what is expected. A new data message is created. For each name that exists in the new one, the data is copied to the old one, unless there is already data there by that name. This way as a program evolves, the user's older preferences file can still have some effect on the new version, and will be filled with the remaining default data from the new version. I thought this was a good idea.

	virtual void SetFileInfo();

This function is called just after the file is created, and gives you an opportunity to set some attributes for the preferences file. The default action is to set the file type to 'application/preferences' and to set the application as the default program for this file. I'm not sure that I have a good understanding of MIME file types, so if I'm blatantly wrong, please let me know.

Putting data in your preferences file

The calls to this class are just copied from the BMessage class. This has two advantages: Be programmers should be familiar with these calls and how to use them, and guess how the information is stored? That's right! Inside a BMessage! So why not just use a BMessage? Go ahead, that's all we do. (And a little bit more). The calls keep a record of the status of data. ie: it knows when it changes because the calls come through this class.

Not all of the data types are supported. Why? Not all data will be current the next time you run the application. Pointers for example, are not valid as soon as the object is deleted, which may be much earlier than the next time the application is launched!! I have included the generic data calls, so any data can be stored anyway.

Contacting the Author.

I am contactable by email, oddly enough, at this address:

	matt@musiclab.com.au

I'm an enthusiastic BeOS programmer, and musician. But, unfortunately, not good enough at either to give up my day job. But I'm working on it!

I am very keen to have feedback of any kind with regard to this code so far, and shortly I will follow with a little demo program. I'm also keen to find out how easy it was to read this, expand the archive and use the code, etc, etc.