Initializes the BShelf object so that it serves a container view. The versions that accept an entry_ref or BDataIO argument prime the shelf so that it (initially) contains the replicants that are archived in the referred to file or stream using Save(). The ref/stream argument is also used as the archival repository when you tell your BShelf to Save() itself.

If the allowsDragging flag is true, the user will be able to drag replicant view within the container's bounds. If the flag is false, dropped views stay where they're first put.

name is the BShelf's handler name. The name can be important: It's compared to the replicant's shelf_type field, as explained in AddReplicant().

Warning

There's an archive-accepting version of the BShelf constructor declared in Shelf.h. Don't use it.

The destructor calls Save(), and then frees the object.

This hook function is invoked automatically when a replicant is dropped on the BShelf. It gives the shelf a chance to fine-tune the placement of the BDragger and its target view.

destRect is the rectangle (in the container view's coordinates) in which the dropped replicant is about to be drawn. Exactly what the rectangle means depends on the relationship between the dragger and its target:

• If the dragger is the target's parent, then destRect encloses the BDragger's frame.

• Otherwise (if the target is the parent, or if the two views are siblings), destRect encloses the target's frame. Note that in the case of siblings, the BDragger's frame isn't included in the rectangle.

archive is the archive message that was dropped on the shelf.

The BPoint that this function returns offsets (is added into) the location of the replicant. If you don't want to move the replicant, return BPoint(0, 0). Note that the BDragger and the view are both moved by this offset, even in the case where destRect doesn't include the dragger's frame.

This function ignores the "allows dragging" flag given in the BShelf constructor. In other words, you can adjust a replicant's placement through this function even if the BShelf doesn't otherwise allow dragging.

These hook functions are invoked from within AddReplicant() whenever a replicant is dropped on the BShelf. You can implement these functions to reject unwanted replicants.

CanAcceptReplicantMessage() is called first; the argument is the archive that (should) contain the replicated view. If you don't like the look of the archive, return false and the message will be thrown away. Note that you shouldn't return false if the archive doesn't seem to be in the correct form (specifically, if it doesn't contain any views). Rejection of such messages is handled more elegantly (and after this function is invoked) by the AddReplicant() function.

CanAcceptReplicantView() is invoked after the message has been unarchived. destRect is the rectangle that the replicant will occupy in the BShelf's container view's coordinates. view is the replicated view itself. archive is the original message.

If either function returns false, the replicant is rejected and the message is thrown away (it isn't passed on to another handler). A return of true does the obvious thing.

This hook function is invoked from within DeleteReplicant() to indicate a replicant has been deleted from the BShelf. It is called after the view has been removed from the shelf with the index of the replicant in the shelf, its archive message, and the detached view.

This function is invoked automatically when a replicant is dropped on the BShelf. The archive message contains the BDragger archive that's being dropped; point is where, within the container view's bounds, the message was dropped. 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.

Returns the number of replicants attached to the shelf.

Removes the specified replicant from the shelf. It identifies replicants by either a view, a replicant message, or a unique id.

IndexOf() returns the index of a specified replicant in the shelf, or -1 if no such replicant exists. It accepts either a view, a replicant message, or a unique id as identifiers.

ReplicantAt() returns information about a replicant in a shelf given its index (as returned by IndexOf()). It returns the BMessage archive of the replicant or NULL if the index is invalid. It returns the view of the replicant as well as its uid, if these parameters are non-NULL. It returns an error message in err if there was an error in initializing the given replicant.

Writes the shelf's contents (the replicants that it contains) as an archive to the entry_ref or BDataIO object that was specified in the constructor. You can also set the location where the shelf is saved with SetSaveLocation() and fetch it with SaveLocation(). The entry_ref is stored in ref (if ref is non-NULL) and the BDataIO the shelf will be written to is returned. If the shelf will be written to an entry_ref that is not a BDataIO, SaveLocation() returns NULL.

By default, the save is only performed if the object's "dirty" flag is set—in other words, if it has changed since it was last written. You can force set the dirty flag by calling SetDirty().

IsDirty() returns the current state of the "dirty" flag.

SetAllowsDragging() determines whether the BShelf accepts replicants dragged into the view by the user. AllowsDragging() returns whether the BShelf accepts replicants dragged by the user into the container view's frame

SetAllowsZombies() determines whether the BShelf accepts zombie views. AllowsZombies() returns whether the BShelf accepts zombie views. A zombie view is one whose associated executable cannot be located.

Similarly, SetDisplaysZombies() determines whether the BShelf displays zombie views and DisplaysZombies() returns whether the BShelf displays zombie views.

These two methods set and return the type enforcement flag. When it is true, the shelf compares its name to the shelf_type field of any dropped messages. The replicant is accepted only if the two match. If the dropped message does not have a shelf_type field, then it is rejected. Type enforcement is false by default.

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 replicant ID

The name of the replicant view

The replicant add-on MIME signature

The supported scripting suites

Redirects messages to the replicant view