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