BDragger

Derived from: public BView

Declared in: be/interface/Dragger.h

Library: libbe.so

Summary

A BDragger is a view that lets users drag and drop some other view. The other view is the target of the BDragger and its immediate relative—a sibling, a parent, or an only child. The BDragger draws a handle, usually at the corner of the target view, that the user can grab. When the user drags the handle the target view appears to move with the handle.

When dragged in this way, the target view itself doesn't actually move. Instead, the view is archived in a BMessage object and the BMessage is dragged. When the BMessage is dropped, the target BView can be reconstructed from the archive (along with the BDragger). The new object is a duplicate—a replicant—of the target view.

This class works closely with the BShelf class. A BShelf object accepts dragged BViews, reconstructs them from their archives, and installs them in another view hierarchy.

BDraggers are under the control of DeskBar's "Show Replicants" / "Hide Replicants" menu item. Showing replicants means that the BDragger handles are visible on-screen; hiding replicants means that the handles are hidden.

Constructor and Destructor

BDragger()

	BDragger(BRect frame, BView *target, uint32 resizingMode = B_FOLLOW_NONE, uint32 flags = B_WILL_DRAW) BDragger(BMessage *archive)

Creates a new BDragger and sets its target view. The BDragger and the target BView must be directly related in the view hierarchy (as parent-child or as siblings); but, note well, the constructor doesn't establish this relationship for you. After you construct you BDragger, you have to do one of three things:

• add the target as a child of the dragger,

• add the dragger as a child of the target,

• or add the dragger as a sibling of the target.

If you add the target as a child of BDragger, it should be the only child that the BDragger has.

A BDragger draws in the right bottom corner of its frame rectangle. If the target view is a parent or a sibling of the BDragger, that rectangle needs to be no larger than the image the BDragger draws (the handle). However, if the target is the BDragger's child, the dragger's frame rectangle must enclose the target's frame (so that the dragger doesn't clip the target).

A BDragger is fully functional once it has been constructed and attached to the view hierarchy of its target. You don't need to call any other functions. However, the whole endeavor fails if the target BView can't be archived.

~BDragger()

virtual ~BDragger()

Frees all memory the BDragger allocated (principally for the bitmap image it draws).

Static Functions

HideAllDraggers() , ShowAllDraggers() , AreDraggersDrawn()

	static status_t HideAllDraggers(void) static status_t ShowAllDraggers(void) static bool AreDraggersDrawn(void)

These functions communicate with all BDragger objects in all applications (provided they're attached to windows). HideAllDraggers() hides the BDragger objects so that they're not visible on-screen. ShowAllDraggers() undoes the effect of HideAllDraggers() and causes all BDragger objects to draw their handles. The Show Replicants / Hide Replicants menu item does its work through these functions.

HideAllDraggers() may or may not hide the BDragger view in the way that BView's Hide() function does. The BDragger may still be visible, although it won't draw anything until ShowAllDraggers() is called. Therefore, if the target BView is the BDragger's child, it will not be hidden when HideAllDraggers() erases its parent.

AreDraggersDrawn() returns true when the BDraggers are shown and false when they're hidden.

Instantiate()

	static BArchivable *Instantiate(BMessage *archive)

Returns a new BDragger object, allocated by new and created with the version of the constructor that takes a BMessage archive. If the archive message doesn't contain and archived BDragger, Instantiate() returns NULL.

ShowAllDraggers() see HideAllDraggers()

Member Functions

Archive()

	virtual status_t Archive(BMessage *archive, bool deep = true) const

Records the BDragger's hierarchical relationship to the target view and then calls BView::Archive(). The deep flag has no significance for BDragger itself, but note that the flag is passed on to the BView version.

AttachedToWindow() , DetachedFromWindow()

	virtual void AttachedToWindow(void) virtual void DetachedFromWindow(void)

AttachedToWindow() makes sure that the BDragger is under the control of the HideAllDraggers() and ShowAllDraggers() functions, makes its low and background view colors match the view color of its parent, and determines the BDragger's precise relationship to its target view. To make this determination, the target must be in the view hierarchy; it can't be added to the window after the BDragger is. For example, if the target is the BDragger's child, it should be added to the BDragger and then the BDragger added to the window.

DetachedFromWindow() removes the BDragger from the control of the HideAllDraggers() and ShowAllDraggers() functions.

Draw()

	virtual void Draw(BRect updateRect)

Draws the handle—or fails to draw it and has the parent view draw in that area instead, if all BDraggers are hidden.

IsVisibilityChanging()

	bool IsVisibilityChanging(void) const

Returns true if two things are true:

• The BDragger is the parent of its target.

• The BDragger handle was visible but now should not be, or it wasn't visible and now should be.

Otherwise, this function returns false.

What's this function for? It's in the API so derived classes can implement their own versions of Draw(). If the BDragger isn't the parent of its target, the visibility of the BDragger view can be controlled by the Hide() and Show() functions rather than Draw().

MessageReceived()

	virtual void MessageReceived(BMessage *message)

Responds to messages that regulate the visibility of the BDragger handle.

MouseDown()

	virtual void MouseDown(BPoint where)

Responds to a B_MOUSE_DOWN message by archiving the target view (and the BDragger) and initiating a drag-and-drop operation, or by taking other appropriate action.

PopUp() , SetPopUp()

	BPopUpMenu *PopUp(void) const status_t SetPopUp(BPopUpMenu *context_menu)

Returns and sets the BPopUpMenu displayed when the user right clicks on the BDragger view after it has been attached to a BShelf.

Archived Fields

The Archive() function adds the following fields to its BMessage argument:

Field	Type code	Meaning
"_popup"	B_MESSAGE_TYPE	Archive of the pop-up menu. Field present only if this menu was set with SetPopUp().
"_rel"	B_INT32_TYPE	Relationship to the target view; one of: TARGET_IS_PARENT, TARGET_IS_CHILD, or TARGET_IS_SIBLING.