1/* 2 * Copyright 2012 Haiku inc. 3 * Distributed under the terms of the MIT License. 4 * 5 * Documentation by: 6 * John Scipione, jscipione@gmail.com 7 * 8 * Corresponds to: 9 * /trunk/headers/os/interface/Dragger.h hrev45050 10 * /trunk/src/kits/interface/Dragger.cpp hrev45050 11 12 13/*! 14 \file Dragger.h 15 \brief Provides the BDragger class. 16*/ 17 18 19/*! 20 \class BDragger 21 \ingroup interface 22 \ingroup libbe 23 \brief A view that allows the user drag and drop a target view. 24 25 The target view must be its immediate relative--a sibling, a parent, or 26 single child. The target BView must be able to be archived. 27 28 The dragger draws a handle on top of the target view, usually in the 29 bottom left the corner that the user can grab. When the user drags the 30 handle the target view appears to move with the handle. 31 32 However the target view doesn't actually move, instead, the view is archived 33 into a BMessage object and the BMessage object is dragged. When the BMessage 34 is dropped, the target BView is reconstructed from the archive (along with 35 the BDragger). The new object is a a replicant of the target view. 36 37 An example of a dragger handle on the Clock app can be seen below. 38 39 \image html BDragger_example.png 40 41 This class is tied closely to BShelf. A BShelf object accepts dragged BViews, 42 reconstructs them from their archives and adds them to the view hierarchy 43 of another view. 44 45 The Show Replicants/Hide Replicants menu item in Deskbar shows and hides the 46 BDragger handles. 47*/ 48 49 50/*! 51 \fn BDragger::BDragger(BRect frame, BView* target, uint32 resizingMode, 52 uint32 flags) 53 \brief Creates a new BDragger and sets its target view. 54 55 The target view must be its immediate relative--a sibling, a parent, or 56 single child, however, the constructor does not establish this 57 relationship for you. 58 59 Once you construct the BDragger you must do one of of these: 60 - Add the target as a child of the dragger. 61 - Add the dragger as a child of the target. 62 - Add the dragger as a sibling of the target. 63 64 If you add the target as a child of the dragger it should be its only 65 child. 66 67 A BDragger draws in the right bottom corner of its frame rectangle. If the 68 \a target view is a parent or a sibling of the dragger then the frame 69 rectangle needs to be no larger than the handle. However, if the \a target 70 is a child of the dragger then the dragger's frame rectangle must enclose 71 the target's frame so that the dragger doesn't clip the \a target. 72 73 \param frame The frame rectangle that the dragger is draw into. 74 \param target The view to set the dragger to. 75 \param resizingMode Sets the parameters by which the dragger can be 76 resized. See BView for more information on resizing options. 77 \param flags The flags mask sets what notifications the BDragger can 78 receive. See BView for more information on \a flags. 79*/ 80 81 82/*! 83 \fn BDragger::BDragger(BMessage* data) 84 \brief Constructs a BDragger object from message \a data. 85 86 \param data The message \a data to restore from. 87*/ 88 89 90/*! 91 \fn BDragger::~BDragger() 92 \brief Destroys the BDragger object and frees the memory it uses, 93 primarily from the bitmap handle. 94*/ 95 96 97/*! 98 \fn static BArchivable* BDragger::Instantiate(BMessage* data) 99 \brief Creates a new BDragger object from the BMessage constructor. 100 101 \returns A newly created BDragger or \c NULL if the message doesn't 102 contain an archived BDragger object. 103*/ 104 105 106/*! 107 \fn status_t BDragger::Archive(BMessage* data, bool deep) const 108 \brief Archives the draggers's relationship to the target view. 109 110 The \a deep parameter has no effect on the BDragger object but 111 is passed on to BView::Archive(). 112 113 \returns A status code, typically \c B_OK or \c B_ERROR on error. 114 115 \see BView::Archive() 116*/ 117 118 119/*! 120 \fn void BDragger::AttachedToWindow() 121 \brief Puts the BDragger under the control of HideAllDraggers() and 122 ShowAllDraggers(). 123*/ 124 125 126/*! 127 \fn void BDragger::DetachedFromWindow() 128 \brief Removes the BDragger from the control of HideAllDraggers() 129 and ShowAllDraggers(). 130*/ 131 132 133/*! 134 \fn void BDragger::Draw(BRect updateRect) 135 \brief Draws the dragger handle. 136 137 \param updateRect The rectangular area to draw the handle in. 138*/ 139 140 141/*! 142 \fn void BDragger::MouseDown(BPoint point) 143 \brief Hook method that is called when a mouse button is pressed over the 144 dragger. 145 146 This results in the archiving of the target view and the dragger and 147 initiates a drag-and-drop operation. 148 149 \param point The point on the screen where to mouse pointer is when 150 the mouse is clicked. 151*/ 152 153 154/*! 155 \fn void BDragger::MessageReceived(BMessage* msg) 156 \brief Receives messages that control the visibility of the dragger handle. 157 158 \param msg The message received 159 160 \see BView::MessageReceived() 161*/ 162 163 164/*! 165 \fn static status_t BDragger::ShowAllDraggers() 166 \brief Causes all BDragger objects to draw their handles. 167 168 The Show Replicants menu item in Deskbar does its work through this 169 method. 170 171 \returns A status code, \c B_OK on success or an error code on failure. 172*/ 173 174 175/*! 176 \fn static status_t BDragger::HideAllDraggers() 177 \brief Hides all BDragger objects so that they're not visible on screen. 178 179 The Hide Replicants menu item in Deskbar does its work through this 180 method. 181 182 \returns A status code, \c B_OK on success or an error code on failure. 183*/ 184 185 186/*! 187 \fn static bool BDragger::AreDraggersDrawn() 188 \brief Returns whether or not draggers are currently drawn. 189 190 \returns \c true if draggers are drawn, \c false otherwise. 191*/ 192
