[haiku-commits] haiku: hrev45051 - docs/user/interface
- From: jscipione@xxxxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Sat, 22 Dec 2012 04:31:46 +0100 (CET)
hrev45051 adds 1 changeset to branch 'master'
old head: 57ec88b65143cf9dde533d2bff83816495d951f9
new head: a6ada82b00fc88528a86557c61658540182ada1a
overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=a6ada82+%5E57ec88b
----------------------------------------------------------------------------
a6ada82: Add BDragger class documentation
[ John Scipione <jscipione@xxxxxxxxx> ]
----------------------------------------------------------------------------
Revision: hrev45051
Commit: a6ada82b00fc88528a86557c61658540182ada1a
URL: http://cgit.haiku-os.org/haiku/commit/?id=a6ada82
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Sat Dec 22 03:31:29 2012 UTC
----------------------------------------------------------------------------
2 files changed, 191 insertions(+)
docs/user/interface/BDragger_example.png | Bin 0 -> 5415 bytes
docs/user/interface/Dragger.dox | 191 +++++++++++++++++++++++++++
----------------------------------------------------------------------------
diff --git a/docs/user/interface/BDragger_example.png
b/docs/user/interface/BDragger_example.png
new file mode 100644
index 0000000..11693a2
Binary files /dev/null and b/docs/user/interface/BDragger_example.png differ
diff --git a/docs/user/interface/Dragger.dox b/docs/user/interface/Dragger.dox
new file mode 100644
index 0000000..d211bcc
--- /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@xxxxxxxxx
+ *
+ * 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.
+*/
Other related posts:
- » [haiku-commits] haiku: hrev45051 - docs/user/interface - jscipione
