Writing Replicants is cool, and as our system evolves we'll see them used more often. Replicant creation is fairly easy, but there are some trouble spots. To help you avoid them I've started writing an application to smooth out the process: the Shelf Inspector. This app will work as a test bed for writing both Replicants and containers. It will also show off some of the new scriptability found in all Replicants and BShelf objects. This is Part 1 of a multi-part article.

The first step is to inspect (and manipulate) the contents of a container view. You can find the sample app associated with this text at

ftp://ftp.be.com/pub/samples/application_kit/ShelfInspector.zip.

This app lets you interrogate a BShelf object (aka "container view") to see what Replicants it contains. One common difficulty with Replicants is managing the add-on/library that defines the Replicant. The Shelf Inspector helps with this by showing the images currently loaded in the target application. It also lets you unload libraries that are no longer in use (be careful not to unload libraries that really are still in use!).

This a good time to build and run the Shelf Inspector. You'll notice when you launch it that it also launches the Container demo application; these two apps work together.

The Target Shelf: popup in the Shelf Inspector window can target any one of three container views in the system. Try it! The top list shows currently loaded Replicants; the lower list shows the libraries loaded by the target application. By selecting a Replicant in the top list you can delete it (with the Delete button) or you can try copying (cloning) the Replicant into the Container demo application.

A warning here: not all Replicants want to be cloned this way, but I thought it was useful to show the possibility. Such cloning can screw up the Container demo. If you run into problems it might help to remove the backing store file for the Container demo (delete /home/config/settings/Container_data).

That's about all there is to the app at this point. There will be more in the future. Now let's switch gears and talk about the implementation. The interesting code—which figures out what Replicants are loaded in some other application—is in the following functions:

BMessenger  TInfoWindow::MessengerForTarget(type_code w)
int32       TInfoWindow::GetReplicantAt(int32 index)
status_t    TInfoWindow::GetReplicantName(int32 uid,
              BMessage *result)
status_t    TInfoWindow::DeleteReplicant(int32 uid)
status_t    TInfoWindow::ImportReplicant(int32 uid)

The MessengerForTarget() function uses the BeOS scripting protocol to get a BMessenger for the target shelf in the target application. Taking the Deskbar as an example, the code looks like this:

request.AddSpecifier("Messenger");
request.AddSpecifier("Shelf");
request.AddSpecifier("View", "Status");
request.AddSpecifier("Window", "Deskbar");
to = BMessenger("application/x-vnd.Be-TSKB", -1);

We're asking for the "Messenger" to the "Shelf" in the View "Status" in the Window "Deskbar" of the Deskbar application.

Every Replicant living inside a BShelf object automatically inherits several "Properties":

• ID—each Replicant gets a unique ID when added to a shelf.

• Name—the Name of the top view of the Replicant.

• Signature—the signature of the add-on defining the Replicant.

• Suites—the computer-readable description of these properties.

• View—the property "pointing" to the top view of the Replicant.

The GetReplicantName() and GetReplicantAt() functions use these properties to do their work. Looking more closely at GetReplicantAt, it asks the shelf for the ID of the Replicant at a given index:

BMessage  request(B_GET_PROPERTY);
request.AddSpecifier("ID");               // want the ID
request.AddSpecifier("Replicant", index); // the index
// fTarget as returned by MessengerForTarget()
fTarget.SendMessage(request, &reply);

reply.FindInt32("result", &uid);

And that's how we get the Replicant's ID, which remains valid across "saves." Thus, in the Container demo, IDs remain valid across quit/launch cycles. For shelves that don't save their state (e.g., the Deskbar), the ID for a Replicant, such as the mailbox widget, potentially changes each time it is added to the shelf.

Just as every Replicant supports a set of properties, so does a shelf. Every shelf defines one property called "Replicant" that supports the following actions:

• counting the number of Replicants

• adding a new Replicant

• deleting an existing Replicant

• getting the "data archive" defining a Replicant

ImportReplicant() and DeleteReplicant() use these features. ImportReplicant() gets a copy of the data archive (the archived BMessage) for the Replicant. Then it sends that archive to the Container demo and asks it to create a new Replicant. Let's take a closer look:

BMessage  request(B_GET_PROPERTY); // Get the archive
BMessage  uid_specifier(B_ID_SPECIFIER);

// IDs are specified using code like so:
uid_specifier.AddInt32("id", uid);
uid_specifier.AddString("property", "Replicant");
request.AddSpecifier(&uid_specifier);

fTarget.SendMessage(&request, &reply);
// various error checking omitted

// OK, let's get the archive message
BMessage  data;
reply.FindMessage("result", &data);

// get messenger to the shelf in the Container demo
BMessenger  mess =
  MessengerForTarget(CONTAINER_MESSENGER);
BMessage  msg(B_CREATE_PROPERTY);

request2.AddMessage("data", &data);

return mess.SendMessage(&request2, &reply);

First we send a GET command, asking the shelf to return a copy of the archive data message for the Replicant whose unique ID is uid. Then we extract the archived data message and add it to a CREATE message. This is sent to the shelf in the Container demo app, and that's it. Note that not all Replicants respond well to this manipulation; the Shelf Inspector warns you if this is the case when you select the Copy to Container button. The Clock Replicant works fine, so it's a good one to play with.

The Library list isn't all that useful right now, but it can let you see if you're properly using some of the advanced Replicant features such as the be:load_each_time and be:unload_on_delete flags. If "unload_on_delete" is set in a Replicant that is removed, the corresponding library should also be removed. If "load each time" is set and the same Replicant is loaded multiple times you should also see the library loaded the same number of times. In a future version of the Shelf Inspector I'll include some configurable test Replicants that show these features in action.

That's it for this installment. Have fun programming the BeOS!

With BeOS R4 just out of the chute, I've prepared a little number that shows off a few of its new features:

ftp://ftp.be.com/pub/samples/intro/xmas.zip

This is sort of a remake of an old Mac demo, updated in R4 style.

The first new goodie is xres, a tool that lets you manipulate resource files. With xres you can create resource files, merge them with applications, and add and remove resources from those files and applications.

In this example, we'll use xres to load an image into a resource file for use in code. If you already have a resource file, perhaps one that contains the apps icon, this will add the image to the pre-existing resource file:

xres -o xmas_x86.rsrc -a bits:666:xmas_bmap newr4.jpg xmas_x86.rsrc

Here, xmas_x86.rsrc is the resource (if it doesn't exist, it will be created) and bits:666:xmas_bmap is the type:ID:name of the resource you're adding. (You can name these elements anything you want, but the name type 'bits' is a good choice for an image, as you'll see in a minute.) newr4.jpg and xmas_x86.rsrc are the two files being merged.

Now execute xres (you can type --help if you need more info) and add your resource file to the project file, if you haven't already done so.

Next we need to do something with our image:

#include <TranslationUtils.h>
#include <Bitmap.h>
...

BBitmap *icon_bitmap =
  BTranslationUtils::GetBitmap("xmas bmap");

This takes you from JPEG file to BBitmap with just one command and three lines of code. GetBitmap() is nice because it looks first for an image file with the name you gave it in the applications folder. If the file isn't there, GetBitmap() looks in the resources file for a resource of type 'bits' and the name you gave it.

The next code snippet takes a peek at the new BString class. In it, we first declare an empty BString, then use += operations to add characters to the string—just as we would with numerical variables. The BString class is very cool and will surely have an entire article devoted to it in the future.

#include <String.h>
...

BString path_string;
path_string+=file_path.Path();
path_string+="/xmas.aiff";

char snd_path[path_string.CountChars()+1];
path_string.CopyInto(snd_path, 0,
  path_string.CountChars()+1);

Also new in R4 is using the Media Kit to play a familiar sound track (thanks, Baron!). Take a look at Eric Shepherd's recent article

Developers' Workshop: Sounding Off With the New Media Kit

for more about sounding off with the new Media Kit.

Currently, BSoundPlayer assumes a 44kHz sound, which is why I use this bit of code to tell the constructor to use an alternate sample rate:

media_raw_audio_format fmt = sound->Format();
BSoundPlayer player(&fmt, ref.name);

That brings me to the end of my R4 teaser. My New Year's resolution is to turn this article file into a generic reminder daemon, so I can continue to bring you breaking news as it happens (and I can talk about it without breaching my NDA).

Release 4 is out and, so far, has been well received. It covers more hardware configurations, more popular graphics and storage devices, and the installation process has improved to the point where it's almost CEO-proof. I say "almost" because no installation is totally immune to the idiosyncrasies of users who know too little and too much.

Nevertheless, I'm proud of the work the Be team has done in everything from documentation to a Japanese input method, from performance to the Media Kit. I encourage you to try the BeOS for yourself and give us some feedback. Both your complaints and praises are appreciated and will be shared.

Also, please remember the two risk-free features of our offering. First, you don't have to give up the comforts of Windows and Microsoft Office; the BeOS lets you dual-boot our specialized OS and the general-purpose Windows. Second, we offer a money back guarantee—with no small print. We can't afford one unhappy customer. At the very least, we want you to be able to say to your friends that the BeOS wasn't for you, but the Be guys are good guys. Web-amplified word of mouth makes or breaks products and companies.

This commercial aside, we have more than ever on our plate, and the first six months of 1999 will keep us very busy. On the product side, we'll ship a maintenance release, 4.1, as soon as practical. The goals and benefits are straightforward: build on Release 4, fix known bugs, and add features and hardware coverage that didn't make the schedule-driven R4. We're eager to prove we're building up technical momentum.

On the marketing side, we'll have at least one Be developer event to promote the new BeOS features—the Media Kit in particular. We'll participate in trade shows including—but not limited to—NAMM (National Association of Music Merchants), the Music Messe in Germany, the NAB show, and, in June, PC Expo. We took our first Intel release to PC Expo in 1998. A year later, we'll have shipped two new releases, and will have "platform- proving" applications to show in the audio and video spaces. We've made visible milestones and have clear goals.

This is likely to be my last column before the Christmas holidays. To all our supporters, from investors to Be developers, members of our team and sympathizers cheering from the sidelines, my heartfelt thanks and wishes for warm and happy holidays with your loved ones.