Archive for June 2012

Haiku Programming: Saving Settings

I think one of the biggest differences between Linux and Haiku is that of having a standard way of doing things. I probably be talking about this difference a lot in the future.

Disclaimer: I’m very new to Haiku programming, so I may make mistakes or not do something the Haiku way. Please correct me if you see any errors. Thank you!

I worked on my RSS feed aggregator a bit over the weekend. I began implementing saved settings.

Linux

There are many ways to save settings in Linux. You can save settings by using GConf (which I just found out is being deprecated in favor of Gsettings). You can use a text file (please make sure to ask xdg where to save it, and not just throw it into the home directory!). Text files can be XML or Lua or old-timey-X-style (whatever that’s called) or made up just for your application. This is probably an over simplified representation of settings files in Linux, but my point is that there’s no single standard way of doing it.

Haiku

The Haiku Human Interface Guidelines explain the standard way of saving settings in Haiku. It involved saving data into a BMessage and then flattening the BMessage into a file. Later, the file can loaded (unflattened) into a BMessage and the settings can be taken out of it.

The Haiku API includes a simple way to get the user’s settings directory:

BPath settingsPath;
find_directory(B_USER_SETTINGS_DIRECTORY, &settingsPath);

The current default user settings directory is “/boot/home/config/settings”. Use the Append method to add a nice name for your settings file:

settingsPath.Append("MyHaikuApplication");

This will make your settings file “/boot/home/config/settings/MyHaikuApplication”.

Messages

BMessage objects are integral to the Haiku API. Here’s a concrete example of what a BMessage looks like. For a BMessage object named “msg”, it has a “what” type (an integer) that can be used to determine the type of BMessage:

msg->what

I don’t use this for saving settings. It has another (very important) purpose that I’ll talk about some other time.

The other thing it has is a whole mess of named data. Here’s a quick example. I’ll save a number into a BMessage:

msg->AddFloat("Pi", 3.141592654);

I can also retrieve it:

float value;
msg->FindFloat("Pi", &value);

As you can see from the documentation, a BMessage can store all sorts of data, include any object or structure. It can even store more that one copy of named data. For example, all of these values will get stored:

msg->AddString("Address", "123 Business Drive");
msg->AddString("Address", "386 Computer Street");
msg->AddString("Address", "7 Internet Superhighway");

They can likewise be pulled out again by using the FindString method. BMessage objects can also store other BMessages. In summary, BMessage objects can allow you to easily store and retrieve data.

Flatten It

To save a BMessage object to file, “flatten” it using the Flatten method. Just send it a pointer to a BFile:

BFile file(settingsPath.Path(), B_CREATE_FILE | B_ERASE_FILE | B_WRITE_ONLY);
if (file.InitCheck() == B_OK)
    msg.Flatten(&file);

Unflattening a file is just as easy:

BFile file(settingsPath.Path(), B_READ_ONLY);
if (file.InitCheck() == B_OK)
    msg.Unflatten(&file);

Changes

Java has a way of serializing objects. This allows you to save an object to a file and then open it again. It sure can be handy, but if you make a change to the class then you can’t open the saved object anymore (as far as I know). The Haiku way of using a BMessage with named values in it doesn’t have this problem. You can always open it and try to read values from it. If the name of a value has changed or is new, then the find will fail and you can simply use a default value. Then, when application quits, you can overwrite the old settings file with the new one.

I WANT PLAIN TEXT FILES RARR!

I’m a Linux user, and I know the benefits of having settings saved in a plain text file. I don’t know of an easy way to extract information from a flattened BMessage besides loading it in an application. Even so, the benefit is that it makes the application responsible for controlling the settings file, even if it means creating a GUI that allows the user to change some settings. Haiku is a desktop operating system. It was designed to be used with a GUI and a mouse. It was also designed to be easy to use. A plain text settings file might be as easy to use as a GUI, but a GUI can allow settinsg to be more discoverable.

An Advanced Case

My RSS feed aggregator has some numerical settings, but it also has more advanced settings. I need to keep track of every “Feed” that the user wants to follow, and every news “Item” in that feed. That’s a list of Item objects inside a list of Feed objects.

I got advice from An Evil Yak, a nice Haiku developer. I decided to create one BMessage for every Feed and one BMessage for every Item. I’ll then add the Item message objects to their corresponding Feed message objects, and all of the Feed message objects to the main settings message object. I’ll then flatten that message to a file.