Using BShelf

A BShelf is an object that you "attach" to a view in order to make the view accept dropped BDragger objects. In user-talk, a shelf receives and displays replicants. Attaching a BShelf to a view (called the "container" view) is remarkably simple:

 BShelf *shelf = new BShelf(container_view);

That's all there is to it: With this single line of code, container_view is primed to accept and (automatically) display dropped replicants. A dropped replicant becomes a child of the container view. The container view itself can be any BView object - you don't alter the view in any way, or even tell it that it's going to be a container.

Note:: Attaching a shelf to a view is performed by the BShelf constructor only. You can't create a BShelf and then decide which view you want it to serve.

Dropping into the View Hierarchy

: When the user drops a replicant on a container view, the view receives a B_ARCHIVED_OBJECT message that contains a BDragger and the dragger's target (a BView). These two views (the BDragger and its target) are related as parent-child, child-parent, or as siblings (as explained in the BDragger class). The "more elderly" of the two objects is added as a child of the container view; if they're siblings, the two objects are both added as children.

: You can also send or post B_ARCHIVED_OBJECT messages to a BShelf to simulate a drag and drop.

Other BShelf Features

Settings. A BShelf can configure itself from a "settings" file, and can write its contents to that file. Your only chance to associate a BShelf with a settings file is during construction. You can save the contents at any time through the Save() function.

Replicant rejection. A BShelf can reject replicants, and can adjust the position of the replicants that it accepts. These features are provided through the hook functions CanAcceptReplicantMessage(), CanAcceptReplicantView(), and AdjustReplicantBy(). A named shelf can also reject replicants, as explained next.

BShelf names. When a replicant message is dropped on the shelf, the shelf's name (set in the constructor) is compared to the dropped message's "shelf_type" field (if it has one). If the two don't match, the replicant rejects the shelf. In this way, individual replicants can be picky about the shelves that they want to be displayed on. By default, a shelf accepts replicants that don't have a "shelf_type" field. However, if a BShelf is set to "enforce type" (set through SetTypeEnforced()), then it will only accept replicants that name the shelf (in their "shelf_type" fields).

A BShelf assigns each replicant a unique id that's valid for as long as the replicant is attached to the shelf. Replicant ids don't change, even if the shelf is Save()'d and then later restored (through the constructor).

How To AddReplicant

The function goes through these steps to reject and adjust the replicant:

First, it invokes the CanAcceptReplicantMessage() hook function. If the hook returns false, then AddReplicant() doesn't add the replicant.

Next, it looks for a "shelf_type" string field in the BMessage. If it finds one and the value of the field doesn't match the BShelf's name, the replicant is rejected.

If type enforcement is true (see SetTypeEnforced()) and the shelf has a name, then the BMessage must have a "shelf_type" string and this string must match the shelf name. Otherwise, the replicant is rejected.

There's no specific API for adding the "shelf_type" field to a view. If you want to configure your views to accept only certain BShelf objects, you have to add the field directly as part of the view's Archive() implementation.

The archive message is then unarchived (the replicant is instantiated). If the archive doesn't contain a BView, the message is passed on to another handler (B_DISPATCH_MESSAGE is returned).

CanAcceptReplicantView() hook function is called next (with a return of false meaning rejection).

Finally, AdjustReplicantBy() is called, and the replicant is drawn in the container view.

Except in the case of a no-view archive, AddReplicant() returns B_SKIP_MESSAGE.

Note:: If you want the ensure that the replicant is unique within the container view, add a "be:unique_replicant" entry of type B_BOOL_TYPE to the archive with the value true.

It's possible to archive a BDragger and call this function yourself, although that's not its expected use.

Scripting Support

: The BShelf class implements the suite called "suite/vnd.Be-shelf" consisting of the following message:

The Replicant Property

Message	Specifiers	Meaning
B_COUNT_PROPERTIES	B_DIRECT_SPECIFIER	Returns number of replicants in the shelf.
B_CREATE_PROPERTIES	B_DIRECT_SPECIFIER	Adds the archived replicant in the BMessage "data" to the view at the BPoint in "location."
B_DELETE_PROPERTY	B_INDEX_SPECIFIER, B_REVERSE_INDEX_SPECIFIER, B_NAME_SPECIFIER, B_ID_SPECIFIER	Removes the specified replicant from the shelf.
B_GET_PROPERTY	B_INDEX_SPECIFIER, B_REVERSE_INDEX_SPECIFIER, B_NAME_SPECIFIER, B_ID_SPECIFIER	Archives the specified replicant into a BMessage in "result."
anything else	B_INDEX_SPECIFIER, B_REVERSE_INDEX_SPECIFIER, B_NAME_SPECIFIER, B_ID_SPECIFIER	Directs the scripting message to the replicant interface "suite/vnd.Be- replicant" (described below), first popping the current specifier off the stack.

: Accesses replicants contained in the BShelf

: The "Replicant" property provides access to the replicants contained in a BShelf. It also allows you to manipulate the replicants themselves by forwarding certain messages to a "suite/vnd.Be-replicant" interface. This interface consists of the following messages:

The ID Property

Message	Specifiers	Meaning
B_GET_PROPERTY	B_DIRECT_SPECIFIER	Returns the replicant ID.

The replicant ID

The Name Property

Message	Specifiers	Meaning
B_GET_PROPERTY	B_DIRECT_SPECIFIER	Returns the name of the replicant view.

: The name of the replicant view

The Signature Property

Message	Specifiers	Meaning
B_GET_PROPERTY	B_DIRECT_SPECIFIER	Returns the signature of the add-on containing the code for the replicant.

: The replicant add-on MIME signature

The Suites Property

Message	Specifiers	Meaning
B_GET_PROPERTY	B_DIRECT_SPECIFIER	Returns "suite/vnd.Be-replicant" in "suites" and a flattened BPropertyInfo describing the scripting suite in "messages."

: The supported scripting suites

The View Property

Message	Specifiers	Meaning
any	B_DIRECT_SPECIFIER	Directs the scripting message to the replicant view, first popping the current specifier off the specifier stack.

: Redirects messages to the replicant view