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