Be Newsletter

Volume II, Issue 50; December 16, 1998

Table of Contents

• BE CLASSIFIEDS
• BE ENGINEERING INSIGHTS: Inspector Detector: The Shelf Inspector By Peter Potrebic
• DEVELOPERS' WORKSHOP: Memories of Tomorrow By Mikol Ryon
• The Next Steps, By Jean-Louis Gassée

BE CLASSIFIEDS:

Be Developer Classifieds are an opportunity for Be developers to tell each other about projects they're working on, are thinking about working on, or would like to work on. Here's your chance to request assistance on a project, or make your talents known to other projects.

For more information, check out the Classified Ads section in the Registered Be Developer area.

The process for adding and updating BeWare is now R4 friendly. Apps can now have R3 PowerPC, R3 Intel, R4 PowerPC, and R4 Intel FTP URLs, and applications are no longer limited to one "BeOS Version" for compatibility.

We will begin posting R4 BeWare on December 21st, so if you have an application posted on BeWare, you should update it to R4 as soon as possible. If you have previously uploaded a Masters Awards entry or a R4 Beta app, please upload them to <ftp://ftp.be.com/incoming/> and add or update its BeWare record so we are sure to post the correct version(s).

Adding or updating a BeWare app can only be done through the Registered Developer Area of our website, <http://www.be.com/developers/registered_entry.html>, and you can upload your app to <ftp://ftp.be.com/incoming/>.

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!

"Developers' Workshop" is a weekly feature that provides answers to our developers' questions, or topic requests. To submit a question, visit

http://www.be.com/developers/suggestion_box.html.

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 bitmap 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 <http://www.be.com/aboutbe/benewsletter/volume II/Issue45.html#Workshop> 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.