The Interface Kit: BDragger

Derived from: public BView

Declared in: be/interface/Dragger.h

Library: libbe.so


Overview

A BDragger is a view that allows users to drag and drop a another 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, where the user can grab hold to drag both views.

When dragged in this way, the target view doesn't necessarily move. Rather, the view is archived in a BMessage object and the archive 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 the Show Replicants / Hide Replicants menu item in the desk bar. Showing replicants means that the BDraggers are visible on-screen; hiding replicants means that the BDraggers are hidden. (In other words, the fact that a BView can be replicated is hidden, not the replicants themselves.)


Constructor and Destructor


BDragger()


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

Initializes the BDragger so that it's tied to the target BView, which must become the BDragger's parent, sibling, or child. If it's a child, it should be the only child the BDragger has.

A BDragger draws only 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 frame rectangle must be large enough not to clip what the target draws.

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(void)

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 a window). 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 BDragger *Instantiate(BMessage *archive) 

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

See also: BArchivable::Instantiate(), instantiate_object(), Archive()


ShowAllDraggers() see HideAllDraggers()


Member Functions


Archive()


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

Calls the inherited version of Archive(), then records the BDragger's relationship to the target view in the BMessage archive. The deep flag is ignored.

See also: BArchivable::Archive(), Instantiate() static function


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.

See also: BView::AttachedToWindow()


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.

See also: BView::Draw()


IsVisibilityChanging()


      bool IsVisibilityChanging(void) const

Returns true if two things are true:

Otherwise, this function returns false. It's in the API merely to allow derived classes to 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.

See also: BHandler::MessageReceived()


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.

See also: BView::MouseDown()






The Be Book, in lovely HTML, for the BeOS Preview Release.

Copyright © 1997 Be, Inc. All rights reserved.

Be is a registered trademark; BeOS, BeBox, BeWare, GeekPort, the Be logo, and the BeOS logo are trademarks of Be, Inc.

Last modified September 18, 1997.