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 51 52/*! 53 \fn BDragger::BDragger(BRect frame, BView* target, uint32 resizingMode, 54 uint32 flags) 55 \brief Creates a new BDragger and sets its target view. 56 57 The target view must be its immediate relative--a sibling, a parent, or 58 single child, however, the constructor does not establish this 59 relationship for you. 60 61 Once you construct the BDragger you must do one of of these: 62 - Add the target as a child of the dragger. 63 - Add the dragger as a child of the target. 64 - Add the dragger as a sibling of the target. 65 66 If you add the target as a child of the dragger it should be its only 67 child. 68 69 A BDragger draws in the right bottom corner of its frame rectangle. If the 70 \a target view is a parent or a sibling of the dragger then the frame 71 rectangle needs to be no larger than the handle. However, if the \a target 72 is a child of the dragger then the dragger's frame rectangle must enclose 73 the target's frame so that the dragger doesn't clip the \a target. 74 75 \param frame The frame rectangle that the dragger is draw into. 76 \param target The view to set the dragger to. 77 \param resizingMode Sets the parameters by which the dragger can be 78 resized. See BView for more information on resizing options. 79 \param flags The flags mask sets what notifications the BDragger can 80 receive. See BView for more information on \a flags. 81*/ 82 83 84/*! 85 \fn BDragger::BDragger(BMessage* data) 86 \brief Constructs a BDragger object from message \a data. 87 88 \param data The message \a data to restore from. 89*/ 90 91 92/*! 93 \fn BDragger::~BDragger() 94 \brief Destroys the BDragger object and frees the memory it uses, 95 primarily from the bitmap handle. 96*/ 97 98 99/*! 100 \fn static BArchivable* BDragger::Instantiate(BMessage* data) 101 \brief Creates a new BDragger object from the BMessage constructor. 102 103 \returns A newly created BDragger or \c NULL if the message doesn't 104 contain an archived BDragger object. 105*/ 106 107 108/*! 109 \fn status_t BDragger::Archive(BMessage* data, bool deep) const 110 \brief Archives the draggers's relationship to the target view. 111 112 The \a deep parameter has no effect on the BDragger object but 113 is passed on to BView::Archive(). 114 115 \returns A status code, typically \c B_OK or \c B_ERROR on error. 116 117 \see BView::Archive() 118*/ 119 120 121/*! 122 \fn void BDragger::AttachedToWindow() 123 \brief Puts the BDragger under the control of HideAllDraggers() and 124 ShowAllDraggers(). 125*/ 126 127 128/*! 129 \fn void BDragger::DetachedFromWindow() 130 \brief Removes the BDragger from the control of HideAllDraggers() 131 and ShowAllDraggers(). 132*/ 133 134 135/*! 136 \fn void BDragger::Draw(BRect updateRect) 137 \brief Draws the dragger handle. 138 139 \param updateRect The rectangular area to draw the handle in. 140*/ 141 142 143/*! 144 \fn void BDragger::MouseDown(BPoint point) 145 \brief Hook method that is called when a mouse button is pressed over the 146 dragger. 147 148 This results in the archiving of the target view and the dragger and 149 initiates a drag-and-drop operation. 150 151 \param point The point on the screen where to mouse pointer is when 152 the mouse is clicked. 153*/ 154 155 156/*! 157 \fn void BDragger::MessageReceived(BMessage* msg) 158 \brief Receives messages that control the visibility of the dragger handle. 159 160 \param msg The message received 161 162 \see BView::MessageReceived() 163*/ 164 165 166/*! 167 \fn static status_t BDragger::ShowAllDraggers() 168 \brief Causes all BDragger objects to draw their handles. 169 170 The Show Replicants menu item in Deskbar does its work through this 171 method. 172 173 \returns A status code, \c B_OK on success or an error code on failure. 174*/ 175 176 177/*! 178 \fn static status_t BDragger::HideAllDraggers() 179 \brief Hides all BDragger objects so that they're not visible on screen. 180 181 The Hide Replicants menu item in Deskbar does its work through this 182 method. 183 184 \returns A status code, \c B_OK on success or an error code on failure. 185*/ 186 187 188/*! 189 \fn static bool BDragger::AreDraggersDrawn() 190 \brief Returns whether or not draggers are currently drawn. 191 192 \returns \c true if draggers are drawn, \c false otherwise. 193*/ 194
