From a6ada82b00fc88528a86557c61658540182ada1a Mon Sep 17 00:00:00 2001 From: John Scipione Date: Fri, 21 Dec 2012 22:31:29 -0500 Subject: [PATCH] Add BDragger class documentation --- docs/user/interface/BDragger_example.png | Bin 0 -> 5415 bytes docs/user/interface/Dragger.dox | 191 +++++++++++++++++++++++ 2 files changed, 191 insertions(+) create mode 100644 docs/user/interface/BDragger_example.png create mode 100644 docs/user/interface/Dragger.dox diff --git a/docs/user/interface/BDragger_example.png b/docs/user/interface/BDragger_example.png new file mode 100644 index 0000000000000000000000000000000000000000..11693a204aa8eb941fe7b2d586805ebfa1484eb5 GIT binary patch literal 5415 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 R9UTAw002ovPDHLkV1oQlQlS6< literal 0 HcmV?d00001 diff --git a/docs/user/interface/Dragger.dox b/docs/user/interface/Dragger.dox new file mode 100644 index 0000000000..d211bcc681 --- /dev/null +++ b/docs/user/interface/Dragger.dox @@ -0,0 +1,191 @@ +/* + * Copyright 2012 Haiku inc. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * John Scipione, jscipione@gmail.com + * + * Corresponds to: + * /trunk/headers/os/interface/Dragger.h hrev45044 + * /trunk/src/kits/interface/Dragger.cpp hrev45044 + + +/*! + \file Dragger.h + \brief Provides the BDragger class. +*/ + + +/*! + \class BDragger + \ingroup interface + \ingroup libbe + \brief A view that allows the user drag and drop a target view. + + The target view must be its immediate relative--a sibling, a parent, or + single child. The target BView must be able to be archived. + + The dragger draws a handle on top of the target view, usually in the + bottom left the corner that the user can grab. When the user drags the + handle the target view appears to move with the handle. + + However the target view doesn't actually move, instead, the view is archived + into a BMessage object and the BMessage object is dragged. When the BMessage + is dropped, the target BView is reconstructed from the archive (along with + the BDragger). The new object is a a replicant of the target view. + + An example of a dragger handle on the Clock app can be seen below. + + \image html BDragger_example.png + + This class is tied closely to BShelf. A BShelf object accepts dragged BViews, + reconstructs them from their archives and adds them to the view hierarchy + of another view. + + The Show Replicants/Hide Replicants menu item in Deskbar shows and hides the + BDragger handles. +*/ + + +/*! + \fn BDragger::BDragger(BRect frame, BView* target, uint32 resizingMode, + uint32 flags) + \brief Creates a new BDragger and sets its target view. + + The target view must be its immediate relative--a sibling, a parent, or + single child, however, the constructor does not establish this + relationship for you. + + Once you construct the BDragger you must do one of of these: + - Add the target as a child of the dragger. + - Add the dragger as a child of the target. + - Add the dragger as a sibling of the target. + + If you add the target as a child of the dragger it should be its only + child. + + A BDragger draws in the right bottom corner of its frame rectangle. If the + \a target view is a parent or a sibling of the dragger then the frame + rectangle needs to be no larger than the handle. However, if the \a target + is a child of the dragger then the dragger's frame rectangle must enclose + the target's frame so that the dragger doesn't clip the \a target. + + \param frame The frame rectangle that the dragger is draw into. + \param target The view to set the dragger to. + \param resizingMode Sets the parameters by which the dragger can be + resized. See BView for more information on resizing options. + \param flags The flags mask sets what notifications the BDragger can + receive. See BView for more information on \a flags. +*/ + + +/*! + \fn BDragger::BDragger(BMessage* data) + \brief Constructs a BDragger object from message \a data. + + \param data The message \a data to restore from. +*/ + + +/*! + \fn BDragger::~BDragger() + \brief Destroys the BDragger object and frees the memory it uses, + primarily from the bitmap handle. +*/ + + +/*! + \fn static BArchivable* BDragger::Instantiate(BMessage* data) + \brief Creates a new BDragger object from the BMessage constructor. + + \returns A newly created BDragger or \c NULL if the message doesn't + contain an archived BDragger object. +*/ + + +/*! + \fn status_t BDragger::Archive(BMessage* data, bool deep) const + \brief Archives the draggers's relationship to the target view. + + The \a deep parameter has no effect on the BDragger object but + is passed on to BView::Archive(). + + \returns A status code, typically \c B_OK or \c B_ERROR on error. + + \see BView::Archive() +*/ + + +/*! + \fn void BDragger::AttachedToWindow() + \brief Puts the BDragger under the control of HideAllDraggers() and + ShowAllDraggers(). +*/ + + +/*! + \fn void BDragger::DetachedFromWindow() + \brief Removes the BDragger from the control of HideAllDraggers() + and ShowAllDraggers(). +*/ + + +/*! + \fn void BDragger::Draw(BRect updateRect) + \brief Draws the dragger handle. + + \param updateRect The rectangular area to draw the handle in. +*/ + + +/*! + \fn void BDragger::MouseDown(BPoint point) + \brief Hook method that is called when a mouse button is pressed over the + dragger. + + This results in the archiving of the target view and the dragger and + initiates a drag-and-drop operation. + + \param point The point on the screen where to mouse pointer is when + the mouse is clicked. +*/ + + +/*! + \fn void BDragger::MessageReceived(BMessage* msg) + \brief Receives messages that control the visibility of the dragger handle. + + \param msg The message received + + \see BView::MessageReceived() +*/ + + +/*! + \fn static status_t BDragger::ShowAllDraggers() + \brief Causes all BDragger objects to draw their handles. + + The Show Replicants menu item in Deskbar does its work through this + method. + + \returns A status code, \c B_OK on success or an error code on failure. +*/ + + +/*! + \fn static status_t BDragger::HideAllDraggers() + \brief Hides all BDragger objects so that they're not visible on screen. + + The Hide Replicants menu item in Deskbar does its work through this + method. + + \returns A status code, \c B_OK on success or an error code on failure. +*/ + + +/*! + \fn static bool BDragger::AreDraggersDrawn() + \brief Returns whether or not draggers are currently drawn. + + \returns \c true if draggers are drawn, \c false otherwise. +*/