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.
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
= newBShelf
(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.
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.
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.
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).