readme.txt
1Inspector Detector: the Shelf Inspector
2
3Writing replicants is cool, and as our system evolves we'll see them used more often. Replicant creation is fairly easily, 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 multipart article.
4
5The 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>.
6
7This 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 still are 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.
8
9The 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.
10
11A 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
12(delete /boot/home/config/settings/Container_data).
13
14That'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:
15
16BMessenger TInfoWindow::MessengerForTarget(type_code w)
17int32 TInfoWindow::GetReplicantAt(int32 index)
18status_t TInfoWindow::GetReplicantName(int32 uid, BMessage *result)
19status_t TInfoWindow::DeleteReplicant(int32 uid)
20status_t TInfoWindow::ImportReplicant(int32 uid)
21
22The 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:
23
24 request.AddSpecifier("Messenger");
25 request.AddSpecifier("Shelf");
26 request.AddSpecifier("View", "Status");
27 request.AddSpecifier("Window", "Deskbar");
28 to = BMessenger("application/x-vnd.Be-TSKB", -1);
29
30We're asking for the "Messenger" to the "Shelf" in the View "Status" in the Window "Deskbar" of the Deskbar application.
31
32
33Every replicant living inside a BShelf object automatically inherits several "Properties":
34
35 * ID - each replicant gets a unique ID when added to a shelf.
36 * Name - the Name of the top view of the replicant.
37 * Signature - the signature of the add-on defining the replicant.
38 * Suites - the computer-readable description of these properties.
39 * View - the property "pointing" to the top view of the replicant.
40
41The 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:
42
43 BMessage request(B_GET_PROPERTY);
44 request.AddSpecifier("ID"); // want the ID
45 request.AddSpecifier("Replicant", index); // the index
46 // fTarget as returned by MessengerForTarget()
47 fTarget.SendMessage(request, &reply);
48 reply.FindInt32("result", &uid);
49
50And 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.
51
52Just as every replicant supports a set of properties, so does a shelf. Every shelf defines one property called "Replicant" that supports the following actions:
53
54 * counting the number of replicants
55 * adding a new replicant
56 * deleting an existing replicant
57 * getting the "data archive" defining a replicant
58
59ImportReplicant() 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:
60
61 BMessage request(B_GET_PROPERTY); // Get the archive
62 BMessage uid_specifier(B_ID_SPECIFIER);
63
64 // IDs are specified using code like so:
65 uid_specifier.AddInt32("id", uid);
66 uid_specifier.AddString("property", "Replicant");
67 request.AddSpecifier(&uid_specifier);
68
69 fTarget.SendMessage(&request, &reply);
70 // various error checking omitted
71
72 // OK, let's get the archive message
73 BMessage data;
74 reply.FindMessage("result", &data);
75
76 // get messenger to the shelf in the Container demo
77 BMessenger mess MessengerForTarget(CONTAINER_MESSENGER);
78 BMessage msg(B_CREATE_PROPERTY);
79 request2.AddMessage("data", &data);
80 return mess.SendMessage(&request2, &reply);
81
82
83First 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.
84
85The 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.
86
87That's it for this installment. Have fun programming the BeOS!
88