[haiku-commits] haiku: hrev54020 - in docs/user/interface/images: . docs/user/interface

  • From: Niels Sascha Reedijk <niels.reedijk@xxxxxxxxx>
  • To: haiku-commits@xxxxxxxxxxxxx
  • Date: Fri, 3 Apr 2020 13:04:39 -0400 (EDT)

hrev54020 adds 1 changeset to branch 'master'
old head: c4f5ebc3df8cf3a00bb1b31cf5908c984272a0e6
new head: 96639729326361712a0b7d4325ee16b9e5af658d
overview: 
https://git.haiku-os.org/haiku/log/?qt=range&q=966397293263+%5Ec4f5ebc3df8c

----------------------------------------------------------------------------

966397293263: HaikuBook: Add documentation for BSplitView and 
BLayoutBuilder::Split<>
  
  Change-Id: I4cfb369d21097ff49a53ebfc52ca57cab7c8049b
  Reviewed-on: https://review.haiku-os.org/c/haiku/+/2443
  Reviewed-by: Adrien Destugues <pulkomandy@xxxxxxxxx>

                          [ Niels Sascha Reedijk <niels.reedijk@xxxxxxxxx> ]

----------------------------------------------------------------------------

Revision:    hrev54020
Commit:      96639729326361712a0b7d4325ee16b9e5af658d
URL:         https://git.haiku-os.org/haiku/commit/?id=966397293263
Author:      Niels Sascha Reedijk <niels.reedijk@xxxxxxxxx>
Date:        Sun Mar 29 08:26:50 2020 UTC

----------------------------------------------------------------------------

5 files changed, 722 insertions(+), 192 deletions(-)
docs/user/interface/LayoutBuilder.Grid.dox       |   2 +-
docs/user/interface/LayoutBuilder.Group.dox      |  15 +-
docs/user/interface/LayoutBuilder.Split.dox      | 517 +++++++++++++++++++
docs/user/interface/SplitView.dox                | 380 +++++++-------
.../interface/images/BSplitView_HaikuDepot.png   | Bin 0 -> 58055 bytes

----------------------------------------------------------------------------

diff --git a/docs/user/interface/LayoutBuilder.Grid.dox 
b/docs/user/interface/LayoutBuilder.Grid.dox
index 4701a9a060..99e9bdfda8 100644
--- a/docs/user/interface/LayoutBuilder.Grid.dox
+++ b/docs/user/interface/LayoutBuilder.Grid.dox
@@ -7,9 +7,9 @@
  *
  * Corresponds to:
  *             headers/os/interface/LayoutBuilder.h     rev 51359
- *             src/kits/interface/LayoutBuilder.cpp     rev 51359
  */
 
+
 /*!
        \class BLayoutBuilder::Grid<>
        \ingroup layout
diff --git a/docs/user/interface/LayoutBuilder.Group.dox 
b/docs/user/interface/LayoutBuilder.Group.dox
index 93f33cf141..c8a187ddda 100644
--- a/docs/user/interface/LayoutBuilder.Group.dox
+++ b/docs/user/interface/LayoutBuilder.Group.dox
@@ -12,16 +12,6 @@
  */
 
 
-/*!
-       \file GroupLayoutBuilder.h
-       \ingroup layout
-       \ingroup libbe
-       \brief Provides the BLayoutBuilder::Group<> class.
-
-       \since Haiku R1
-*/
-
-
 /*!
        \class BLayoutBuilder::Group<>
        \ingroup layout
@@ -137,6 +127,7 @@
 
 //! @{
 
+
 /*!
        \fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::Add(BView* view)
        \brief Add a BView to the BGroupLayout this builder represents.
@@ -278,7 +269,7 @@
 
        \param gridLayout The BGridLayout to be added and used to construct the
                returned GridBuilder.
-       \param weight The weight for \a groupLayout in the BGroupLayout this 
builder
+       \param weight The weight for \a gridLayout in the BGroupLayout this 
builder
                represents.
 
        \returns a GridBuilder representing \a gridLayout.
@@ -294,7 +285,7 @@
 
        \param gridView The BGridView to be added and used to construct the
                returned GridBuilder.
-       \param weight The weight for \a groupLayout in the BGroupLayout this 
builder
+       \param weight The weight for \a gridView in the BGroupLayout this 
builder
                represents.
 
        \returns a GridBuilder representing \a gridView.
diff --git a/docs/user/interface/LayoutBuilder.Split.dox 
b/docs/user/interface/LayoutBuilder.Split.dox
new file mode 100644
index 0000000000..f23cb3bc18
--- /dev/null
+++ b/docs/user/interface/LayoutBuilder.Split.dox
@@ -0,0 +1,517 @@
+/*
+ * Copyright 2020 Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *             Niels Sascha Reedijk, niels.reedijk@xxxxxxxxx
+ *
+ * Corresponds to:
+ *             headers/os/interface/LayoutBuilder.h     rev 49977
+ */
+
+
+/*!
+       \class BLayoutBuilder::Split<>
+       \ingroup layout
+       \ingroup libbe
+       \brief BLayoutBuilder::Base subclass for building BSplitViews.
+
+       \since Haiku R1
+
+       A BSplitView consists of elements, for which in between there are 
dividers
+       that the user can manipulate to alter the division of space between 
each of
+       the element.s
+
+       For a detailed view on the properties, see the \link BSplitView class
+       description\endlink.
+*/
+
+
+/*!
+       \typedef BLayoutBuilder::Split<ParentBuilder>::ThisBuilder
+       \brief Shorthand representing the type of \c this.
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \typedef BLayoutBuilder::Split<ThisBuilder>::GroupBuilder
+       \brief Shorthand for builders returned by this builder's AddGroup() 
methods.
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \typedef BLayoutBuilder::Split<ThisBuilder>::GridBuilder
+       \brief Shorthand for builders returned by this builder's AddGrid() 
methods.
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \typedef BLayoutBuilder::Split<ThisBuilder>::SplitBuilder
+       \brief Shorthand for builders returned by this builder's AddSplit() 
methods.
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \typedef BLayoutBuilder::Split<ThisBuilder>::CardBuilder
+       \brief Shorthand for builders returned by this builder's AddCards()
+               methods.
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \name Constructors
+*/
+
+
+//! @{
+
+
+/*!
+       \fn BLayoutBuilder::Split<ParentBuilder>::Split(orientation orientation,
+               float spacing)
+       \brief Creates a builder for a new BSplitView.
+
+       \param orientation The orientation for the new BSplitView.
+       \param spacing The spacing for the new BSplitView.
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \fn BLayoutBuilder::Split<ParentBuilder>::Split(orientation orientation,
+               float spacing)
+       \brief Creates a builder for a new BSplitView.
+
+       \param orientation The orientation for the new BSplitView.
+       \param spacing The spacing for the new BSplitView.
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \fn BLayoutBuilder::Split<ParentBuilder>::Split(BSplitView *view)
+       \brief Creates a builder for an existing BSplitView
+
+       \param view The existing view to operate on.
+
+       \since Haiku R1
+*/
+
+
+//! @}
+
+
+/*!
+       \name Accessors
+*/
+
+
+//! @{
+
+
+/*!
+       \fn BSplitView* BLayoutBuilder::Split<ParentBuilder>::View() const
+       \brief Get a borrowed pointer to the underlying BSplitView
+
+       \returns A borrowed pointer to the underlying BSplitView
+*/
+
+
+/*!
+       \fn ThisBuilder& BLayoutBuilder::Split<ParentBuilder>::GetView(
+               BView** _view)
+       \brief Get a borrowed pointer to the underlying view.
+
+       \param[out] _view Location to store the underlying BSplitView as a BView
+               reference.
+
+       \return The method returns a self reference, so that calls to the 
builder
+               may be chained.
+*/
+
+
+/*!
+       \fn ThisBuilder& BLayoutBuilder::Split<ParentBuilder>::GetSplitView(
+               BSplitView** _view)
+       \brief Get a borrowed pointer to the underlying view.
+
+       \param[out] _view Location to store the underlying BSplitView reference.
+
+       \return The method returns a self reference, so that calls to the 
builder
+               may be chained.
+*/
+
+
+/*!
+       \fn BLayoutBuilder::Split<ParentBuilder>::operator BSplitView*()
+       \brief Cast this builder into the BSplitView it represents.
+
+       \since Haiku R1
+*/
+
+
+//! @}
+
+
+/*!
+       \name Adding BViews and BLayoutItems
+*/
+
+
+//! @{
+
+
+/*!
+       \fn ThisBuilder& BLayoutBuilder::Split<ParentBuilder>::Add(BView* view)
+       \brief Add a \a view to the underlying BSplitView.
+
+       The \a view will be added to the right or the bottom of the existing
+       elements.
+
+       \param view The BView to be added. The underlying BSplitView will take
+               ownership of the object.
+
+       \see BSplitView::Add(BView*)
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \fn ThisBuilder& BLayoutBuilder::Split<ParentBuilder>::Add(BView* view,
+               float weight)
+       \brief Add a \a view with a \a weight to the underlying BSplitView.
+
+       The \a view will be added to the right or the bottom of the existing
+       elements.
+
+       \param view The BView to be added. The underlying BSplitView will take
+               ownership of the object.
+       \param weight The weight of the view.
+
+       \see BSplitView::Add(BView*, float)
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \fn ThisBuilder& BLayoutBuilder::Split<ParentBuilder>::Add(
+               BLayoutItem* item)
+       \brief Add a \a item to the underlying BSplitView.
+
+       The layout item will be added to the right or the bottom of the existing
+       elements.
+
+       \param item The BLayoutItem to be added. The underlying BSplitView will
+               take ownership of the object.
+
+       \see BSplitView::Add(BLayoutItem*)
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \fn ThisBuilder& BLayoutBuilder::Split<ParentBuilder>::Add(
+               BLayoutItem* item, float weight)
+       \brief Add an \a item with a \a weight to the underlying BSplitView.
+
+       The layout item will be added to the right or the bottom of the existing
+       elements.
+
+       \param item The BLayoutItem to be added. The underlying BSplitView will
+               take ownership of the object.
+       \param weight The weight of the item.
+
+       \see BSplitView::Add(BLayoutItem*, float)
+
+       \since Haiku R1
+*/
+
+
+//! @}
+
+
+/*!
+       \name Adding BLayouts and their BView Pairs
+
+       A set of methods that add a BLayout or BView subclass and return a
+       BLayoutBuilder::Base subclass representing the newly added object. These
+       methods push a new builder on top of the stack, you will not be using
+       \c this builder again until you call End().
+*/
+
+
+//! @{
+
+
+/*!
+       \fn GroupBuilder BLayoutBuilder::Split<ParentBuilder>::AddGroup(
+               orientation orientation, float spacing, float weight)
+       \brief Construct and add a viewless BGroupLayout, then return a 
GroupBuilder
+              representing the newly added layout.
+
+       \param orientation The orientation to use for the new BGroupLayout.
+       \param spacing The spacing to use for the new BGroupLayout.
+       \param weight The weight for the new BGroupLayout in the BGroupLayout 
this
+              builder represents.
+
+       \returns A GroupBuilder representing the newly created BGroupLayout.
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \fn GroupBuilder 
BLayoutBuilder::Split<ParentBuilder>::AddGroup(BGroupView*
+               groupView, float weight)
+       \brief Add BGroupView and return a builder representing the newly added
+              BGroupView.
+
+       \param groupView The BGroupView to be added.
+       \param weight The weight for \a groupView in the BGroupLayout this 
builder
+              represents.
+
+       \returns A GroupBuilder representing \a groupView.
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \fn GroupBuilder BLayoutBuilder::Split<ParentBuilder>::AddGroup(
+               BGroupLayout* groupLayout, float weight)
+       \brief Add a BGroupLayout and return a builder representing the newly 
added
+              BGroupLayout.
+
+       \param groupLayout The BGroupLayout to be added.
+       \param weight The weight for \a groupLayout in the BGroupLayout this 
builder
+               represents.
+
+       \returns A GroupBuilder representing \a groupLayout.
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \fn GridBuilder BLayoutBuilder::Split<ParentBuilder>::AddGrid(
+               float horizontalSpacing = 0.0f, float verticalSpacing = 0.0f,
+               float weight = 1.0f)
+       \brief Create and add a viewless BGridLayout, then return a builder
+              representing the newly created BGridLayout.
+
+       \param horizontalSpacing The horizontal spacing for the new BGridLayout.
+       \param verticalSpacing The vertical spacing for the new BGridLayout.
+       \param weight The weight for the new BGridLayout in the BSplitView this
+               builder represents.
+
+       \returns A GridBuilder representing the newly created BGridLayout.
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \fn GridBuilder BLayoutBuilder::Split<ParentBuilder>::AddGrid(
+               BGridLayout* gridLayout, float weight = 1.0f)
+       \brief Add a BGridLayout, then return a builder the newly added 
BGridLayout.
+
+       \param gridLayout The BGridLayout to be added and used to construct the
+               returned GridBuilder.
+       \param weight The weight for \a gridLayout in the BSplitView this 
builder
+               represents.
+
+       \returns A GridBuilder representing \a gridLayout.
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \fn GridBuilder BLayoutBuilder::Split<ParentBuilder>::AddGrid(
+               BGridView* gridView, float weight = 1.0f)
+       \brief Add a BGridView, then return a builder the newly added BGridView.
+
+       \param gridView The BGridView to be added and used to construct the
+               returned GridBuilder.
+       \param weight The weight for \a gridView in the BSplitView this builder
+               represents.
+
+       \returns A GridBuilder representing \a gridView.
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \fn SplitBuilder BLayoutBuilder::Split<ParentBuilder>::AddSplit(
+               orientation orientation, float spacing, float weight)
+       \brief Create and add a new BSplitView with a weight of \c weight, then
+               return a SplitBuilder representing the new BSplitView.
+
+       \param orientation The orientation of the new BSplitView.
+       \param spacing The spacing of the new BSplitView.
+       \param weight The weight, in this BSplitView for the new BSplitView.
+
+       \returns A SplitBuilder representing the new BSplitView.
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \fn SplitBuilder BLayoutBuilder::Split<ParentBuilder>::AddSplit(
+               BSplitView* splitView, float weight = 1.0f)
+       \brief Add a BSplitView to the BSplitView this builder represents and
+               return a SplitBuilder representing the BSplitView.
+
+       \param splitView The BSplitView to be added.
+       \param weight The weight of the BSplitView in the BSplitView this 
builder
+               represents.
+
+       \returns A SplitBuilder representing the new BSplitView.
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \fn CardBuilder BLayoutBuilder::Split<ParentBuilder>::AddCards(
+               float weight)
+       \brief Add a new BCardLayout to the BSplitView this builder represents 
and
+               return a CardBuilder representing the new layout.
+
+       \param weight The weight of the BCardLayout in the BSplitView this 
builder
+               represents.
+
+       \returns A CardBuilder representing the new BCardLayout.
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \fn CardBuilder BLayoutBuilder::Split<ParentBuilder>::AddCards(
+               BCardLayout* cardLayout, float weight)
+       \brief Add an existing BCardLayout to the BSplitView this builder
+               represents and return a CardBuilder representing this layout.
+
+       \param cardLayout The existing layout that will be added to the 
underlying
+               BSplitView.
+       \param weight The weight of the BCardLayout in the BSplitView this 
builder
+               represents.
+
+       \returns A CardBuilder representing the new BCardLayout.
+
+       \since Haiku R1
+*/
+
+
+/*!
+       \fn CardBuilder BLayoutBuilder::Split<ParentBuilder>::AddCards(
+               BCardView* cardView, float weight)
+       \brief Add an existing BCardView to the BSplitView this builder
+               represents and return a CardBuilder representing this layout.
+
+       \param cardView The existing view that will be added to the underlying
+               BSplitView.
+       \param weight The weight of the BCardLayout in the BSplitView this 
builder
+               represents.
+
+       \returns A CardBuilder representing the new BCardLayout.
+
+       \since Haiku R1
+*/
+
+
+//! @}
+
+
+/*!
+       \name Collapsability of elements
+*/
+
+
+//! @{
+
+
+/*!
+       \fn ThisBuilder& BLayoutBuilder::Split<ParentBuilder>::SetCollapsible(
+               bool collapsible)
+       \copydoc BSplitView::SetCollapsible(bool)
+
+       \see BSplitView::SetCollapsible(bool)
+*/
+
+
+/*!
+       \fn ThisBuilder& BLayoutBuilder::Split<ParentBuilder>::SetCollapsible(
+               int32 index, bool collapsible)
+       \copydoc BSplitView::SetCollapsible(int32, bool)
+
+       \see BSplitView::SetCollapsible(int32, bool)
+*/
+
+
+/*!
+       \fn ThisBuilder& BLayoutBuilder::Split<ParentBuilder>::SetCollapsible(
+               int32 first, int32 last, bool collapsible)
+       \copydoc BSplitView::SetCollapsible(int32, int32, bool)
+
+       \see BSplitView::SetCollapsible(int32, int32, bool)
+*/
+
+
+//! @}
+
+
+/*!
+       \name Insets
+*/
+
+
+//! @{
+
+
+/*!
+       \fn ThisBuilder& BLayoutBuilder::Split<ParentBuilder>::SetInsets(
+               float left, float top, float right, float bottom)
+       \copydoc BSplitView::SetInsets(float, float, float, float)
+
+       \see BSplitView::SetInsets(float, float, float, float)
+*/
+
+
+/*!
+       \fn ThisBuilder& BLayoutBuilder::Split<ParentBuilder>::SetInsets(
+               float horizontal, float vertical)
+       \copydoc BSplitView::SetInsets(float, float)
+
+       \see BSplitView::SetInsets(float, float)
+*/
+
+
+/*!
+       \fn ThisBuilder& BLayoutBuilder::Split<ParentBuilder>::SetInsets(
+               float insets)
+       \copydoc BSplitView::SetInsets(float)
+
+       \see BSplitView::SetInsets(float)
+*/
+
+
+//! @}
diff --git a/docs/user/interface/SplitView.dox 
b/docs/user/interface/SplitView.dox
index f037276caa..d64bfea1d2 100644
--- a/docs/user/interface/SplitView.dox
+++ b/docs/user/interface/SplitView.dox
@@ -1,9 +1,12 @@
 /*
- * Copyright 2019 Haiku, Inc. All rights reserved.
+ * Copyright 2020 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
- *             Name, email@xxxxxxxxx
+ *             Niels Sascha Reedijk, niels.reedijk@xxxxxxxxx
+ *
+ * Reviewers:
+ *             Adrien Destugues, pulkomandy@xxxxxxxxxxxxx
  *
  * Corresponds to:
  *             headers/os/interface/SplitView.h        hrev49977
@@ -14,7 +17,8 @@
 /*!
        \file SplitView.h
        \ingroup layout
-       \brief Undocumented file.
+       \ingroup libbe
+       \brief Provides the BSplitView class.
 
        \since Haiku R1
 */
@@ -24,7 +28,50 @@
        \class BSplitView
        \ingroup layout
        \ingroup libbe
-       \brief Undocumented class.
+       \brief A container with two or more sections, with dividers in between,
+               so that a user can manipulate the size of the sections by 
dragging
+               a slider.
+
+       This container view consists one of more items, that are laid out
+       horizontally or vertically. Between two adjoining items, there is a
+       splitter. This splitter allows the user to change how the space between 
the
+       individual items is divided.
+
+       The screenshot below shows the BSplitView being used in HaikuDepot. The
+       BSplitView is the main container of the window, in this case with a
+       \ref B_VERTICAL layout. The top part contains the list of packages, and
+       some filter tools. At the bottom are individual package details. In 
between
+       the two visual elements there is a dotted line, indicating the draggable
+       separator. At the right hand of this separator, above the \b Install
+       button, you can see that the mouse cursor changed into the double arrow,
+       indicating the user that the element is dragable.
+
+       \image html BSplitView_HaikuDepot.png
+
+       Because of the dynamic nature of the size of the sections within the
+       split view, it is best to use this container with the \link layout 
layout
+       system\endlink. It is fully supported by the layout builder utilities. 
See
+       the \ref BLayoutBuilder::Split<> documentation for the builder that
+       accompanies this view.
+
+       The container has the following properties:
+        - \b Insets are the padding for the split view.
+        - \b Spacing is the spacing between the components.
+        - \b Orientation is whether the splits are horizontal or vertical.
+        - \b Splitter \b size is the size of the splitter.
+
+       Specifically for individual elements, the following properties may also
+       be set:
+        - \b Weight for the weight of the item within the split view 
(determines
+          how space is allocated between the items).
+        - \b Collapsible determines if an element is collapsible, meaning the 
user
+          can drag the splitter as such as to hide the item completely. If an 
item
+          is not collapsible, at least a part of the item will always be 
visible
+          to the user.
+
+       \related The \ref BGroupView essentially has the same properties for
+               organizing the layout items, though it does not offer the 
functionality
+               for users to change the size of the elements.
 
        \since Haiku R1
 */
@@ -32,13 +79,10 @@
 
 /*!
        \fn BSplitView::BSplitView(orientation orientation=B_HORIZONTAL, float 
spacing=B_USE_DEFAULT_SPACING)
-       \brief Undocumented public method
-
-       \param orientation Undocumented
-       \param spacing Undocumented
+       \brief Creates a new split view.
 
-       \return Undocumented
-       \retval <value> Undocumented
+       \param orientation The orientation of the splits.
+       \param spacing The spacing in between the elements.
 
        \since Haiku R1
 */
@@ -46,12 +90,9 @@
 
 /*!
        \fn BSplitView::BSplitView(BMessage *from)
-       \brief Undocumented public method
+       \brief Unarchive a split view.
 
-       \param from Undocumented
-
-       \return Undocumented
-       \retval <value> Undocumented
+       \param from The \ref BMessage that contains the split view.
 
        \since Haiku R1
 */
@@ -59,10 +100,7 @@
 
 /*!
        \fn virtual virtual BSplitView::~BSplitView()
-       \brief Undocumented public method
-
-       \return Undocumented
-       \retval <value> Undocumented
+       \brief Destructor.
 
        \since Haiku R1
 */
@@ -70,12 +108,13 @@
 
 /*!
        \fn void BSplitView::SetInsets(float left, float top, float right, 
float bottom)
-       \brief Undocumented public method
+       \brief Set the insets between the bounds of the view and the inner
+               elements.
 
-       \param left Undocumented
-       \param top Undocumented
-       \param right Undocumented
-       \param bottom Undocumented
+       \param left The left inset.
+       \param top The top inset.
+       \param right The right inset.
+       \param bottom The bottom inset.
 
        \since Haiku R1
 */
@@ -83,10 +122,11 @@
 
 /*!
        \fn void BSplitView::SetInsets(float horizontal, float vertical)
-       \brief Undocumented public method
+       \brief Set the insets between the bounds of the view and the inner
+               elements.
 
-       \param horizontal Undocumented
-       \param vertical Undocumented
+       \param horizontal The left and right inset.
+       \param vertical The top and bottom inset.
 
        \since Haiku R1
 */
@@ -94,9 +134,10 @@
 
 /*!
        \fn void BSplitView::SetInsets(float insets)
-       \brief Undocumented public method
+       \brief Set the insets between the bounds of the view and the inner
+               elements.
 
-       \param insets Undocumented
+       \param insets The value for the left, top, right and bottom inset.
 
        \since Haiku R1
 */
@@ -104,12 +145,15 @@
 
 /*!
        \fn void BSplitView::GetInsets(float *left, float *top, float *right, 
float *bottom) const
-       \brief Undocumented public method
+       \brief Get the insets that apply to this view.
+
+       You may pass \c NULL for any of the parameters, if you do not wish to
+       retrieve their value.
 
-       \param left Undocumented
-       \param top Undocumented
-       \param right Undocumented
-       \param bottom Undocumented
+       \param[out] left Will be set to the left inset.
+       \param[out] top Will be set to the top inset.
+       \param[out] right Will be set to the right inset.
+       \param[out] bottom Will be set to the bottom inset.
 
        \since Haiku R1
 */
@@ -117,10 +161,9 @@
 
 /*!
        \fn float BSplitView::Spacing() const
-       \brief Undocumented public method
+       \brief Get the spacing between elements in this view.
 
-       \return Undocumented
-       \retval <value> Undocumented
+       \return The spacing between elements as a \c float.
 
        \since Haiku R1
 */
@@ -128,9 +171,10 @@
 
 /*!
        \fn void BSplitView::SetSpacing(float spacing)
-       \brief Undocumented public method
+       \brief Set the spacing between elements in this view.
 
-       \param spacing Undocumented
+       \param spacing The desired spacing between elements. This will apply to 
all
+               elements.
 
        \since Haiku R1
 */
@@ -138,10 +182,10 @@
 
 /*!
        \fn orientation BSplitView::Orientation() const
-       \brief Undocumented public method
+       \brief Get the orientation of the elements in this view.
 
-       \return Undocumented
-       \retval <value> Undocumented
+       \retval B_HORIZONTAL The elements are ordered left-to-right.
+       \retval B_VERTICAL The elements are ordered top-to-bottom.
 
        \since Haiku R1
 */
@@ -149,9 +193,9 @@
 
 /*!
        \fn void BSplitView::SetOrientation(orientation orientation)
-       \brief Undocumented public method
+       \brief Set the orientation of the elements in this view.
 
-       \param orientation Undocumented
+       \param orientation May be \ref B_HORIZONTAL or \ref B_VERTICAL.
 
        \since Haiku R1
 */
@@ -159,10 +203,9 @@
 
 /*!
        \fn float BSplitView::SplitterSize() const
-       \brief Undocumented public method
+       \brief Get the size of the splitter(s) in this view.
 
-       \return Undocumented
-       \retval <value> Undocumented
+       \return The size of the splitter(s).
 
        \since Haiku R1
 */
@@ -170,9 +213,10 @@
 
 /*!
        \fn void BSplitView::SetSplitterSize(float size)
-       \brief Undocumented public method
+       \brief Set the size of the splitter(s) in this view.
 
-       \param size Undocumented
+       \param size The size as a \c float that will be applied to all splitters
+               in this view.
 
        \since Haiku R1
 */
@@ -180,10 +224,10 @@
 
 /*!
        \fn int32 BSplitView::CountItems() const
-       \brief Undocumented public method
+       \brief The number of items in this view.
 
-       \return Undocumented
-       \retval <value> Undocumented
+       \return Returns the number of items in this view. The splitters 
themselves
+               are not included in this number.
 
        \since Haiku R1
 */
@@ -191,12 +235,11 @@
 
 /*!
        \fn float BSplitView::ItemWeight(int32 index) const
-       \brief Undocumented public method
+       \brief Get the item weight for the item at the \a index.
 
-       \param index Undocumented
+       \param index The index of the item (zero-based).
 
-       \return Undocumented
-       \retval <value> Undocumented
+       \return The weight of the item, or \c 0.0 if there is no item at \a 
index.
 
        \since Haiku R1
 */
@@ -204,12 +247,12 @@
 
 /*!
        \fn float BSplitView::ItemWeight(BLayoutItem *item) const
-       \brief Undocumented public method
+       \brief Get the item weight for an existing \a item.
 
-       \param item Undocumented
+       \param item An existing layout item object.
 
-       \return Undocumented
-       \retval <value> Undocumented
+       \return The weight of the \a item, or \c 0.0 if the item is not 
associated
+               with this view.
 
        \since Haiku R1
 */
@@ -217,11 +260,15 @@
 
 /*!
        \fn void BSplitView::SetItemWeight(int32 index, float weight, bool 
invalidateLayout)
-       \brief Undocumented public method
+       \brief Set the weight of the item at \a index.
 
-       \param index Undocumented
-       \param weight Undocumented
-       \param invalidateLayout Undocumented
+       The weight is relative to all other items in the layout, and determines 
how
+       the available space is distributed over the items in the layout.
+
+       \param index The index of the item (zero-based).
+       \param weight The weight of the item.
+       \param invalidateLayout When \c true, calls
+               \ref BLayout::InvalidateLayout() to recalculate the layout.
 
        \since Haiku R1
 */
@@ -229,10 +276,13 @@
 
 /*!
        \fn void BSplitView::SetItemWeight(BLayoutItem *item, float weight)
-       \brief Undocumented public method
+       \brief Set the weight of the \a item.
+
+       The weight is relative to all other items in the layout, and determines 
how
+       the available space is distributed over the items in the layout.
 
-       \param item Undocumented
-       \param weight Undocumented
+       \param item The item within this view that the weight applies to.
+       \param weight The weight of the item.
 
        \since Haiku R1
 */
@@ -240,12 +290,12 @@
 
 /*!
        \fn bool BSplitView::IsCollapsible(int32 index) const
-       \brief Undocumented public method
+       \brief Get whether the item at \a index is collapsible.
 
-       \param index Undocumented
+       \param index The index of the item (zero-based).
 
-       \return Undocumented
-       \retval <value> Undocumented
+       \retval true The user can collapse the item.
+       \retval false The user cannot collapse the item.
 
        \since Haiku R1
 */
@@ -253,9 +303,10 @@
 
 /*!
        \fn void BSplitView::SetCollapsible(bool collapsible)
-       \brief Undocumented public method
+       \brief Set the whether all the layout items in this view are 
collapsible.
 
-       \param collapsible Undocumented
+       \param collapsible \c true if all items in this layout are collapsible,
+               \c false if they are not.
 
        \since Haiku R1
 */
@@ -263,10 +314,11 @@
 
 /*!
        \fn void BSplitView::SetCollapsible(int32 index, bool collapsible)
-       \brief Undocumented public method
+       \brief Set whether the item at \a index is collapsible.
 
-       \param index Undocumented
-       \param collapsible Undocumented
+       \param index The index of the item (zero-based).
+       \param collapsible \c true if the user may collaps the item, \c false if
+               they may not.
 
        \since Haiku R1
 */
@@ -274,11 +326,14 @@
 
 /*!
        \fn void BSplitView::SetCollapsible(int32 first, int32 last, bool 
collapsible)
-       \brief Undocumented public method
+       \brief Set whether the items from \a first to \a last are collapsible.
 
-       \param first Undocumented
-       \param last Undocumented
-       \param collapsible Undocumented
+       \param first The index of the first item that you want the setting to 
apply
+               to (zero-based).
+       \param last The index of the last item that you want the setting to 
apply
+               to (zero-based).
+       \param collapsible \c true if the user may collaps the item, \c false if
+               they may not.
 
        \since Haiku R1
 */
@@ -286,12 +341,12 @@
 
 /*!
        \fn bool BSplitView::IsItemCollapsed(int32 index) const
-       \brief Undocumented public method
+       \brief Check whether the item at \a index is collapsed.
 
-       \param index Undocumented
+       \param index The index of the item (zero-based).
 
-       \return Undocumented
-       \retval <value> Undocumented
+       \retval true The item is collapsed.
+       \retval false The item is not collapsed.
 
        \since Haiku R1
 */
@@ -299,10 +354,11 @@
 
 /*!
        \fn void BSplitView::SetItemCollapsed(int32 index, bool collapsed)
-       \brief Undocumented public method
+       \brief Set whether the item at \a index is displayed as collapsed.
 
-       \param index Undocumented
-       \param collapsed Undocumented
+       \param index The index of the item (zero-based).
+       \param collapsed \c true if the item should be rendered collapsed, \c
+               false if it needs to be visible.
 
        \since Haiku R1
 */
@@ -310,10 +366,11 @@
 
 /*!
        \fn void BSplitView::AddChild(BView *child, BView *sibling=NULL)
-       \brief Undocumented public method
+       \brief Add a \a child to the view.
 
-       \param child Undocumented
-       \param sibling Undocumented
+       Passthrough for \ref BView::AddChild(BView *child, BView *sibling). This
+       bypasses the layout system, so only use it when you know what you are
+       doing.
 
        \since Haiku R1
 */
@@ -321,13 +378,16 @@
 
 /*!
        \fn bool BSplitView::AddChild(BView *child, float weight)
-       \brief Undocumented public method
+       \brief Add a \a child with a \a weight.
 
-       \param child Undocumented
-       \param weight Undocumented
+       The view will be added at the end of the existing layout items, meaning 
it
+       will be placed to the right or bottom of existing items.
 
-       \return Undocumented
-       \retval <value> Undocumented
+       \param child The view that should be added as a child. The ownership is
+               transferred to this view.
+       \param weight The weight of the item.
+
+       \return \c true when succesfully, \c false if there was an error.
 
        \since Haiku R1
 */
@@ -335,14 +395,17 @@
 
 /*!
        \fn bool BSplitView::AddChild(int32 index, BView *child, float weight)
-       \brief Undocumented public method
+       \brief Add a \a child at \a index with a \a weight.
 
-       \param index Undocumented
-       \param child Undocumented
-       \param weight Undocumented
+       \param index The desired position for the \a child. Existing items will 
be
+               shifted to the right or down based on the orientation. If the 
index is
+               higher than the number of items, the item will be added after 
farmost
+               item. The index is zero-based.
+       \param child The view that should be added as a child. The ownership is
+               transferred to this view.
+       \param weight The weight of the item.
 
-       \return Undocumented
-       \retval <value> Undocumented
+       \return \c true when succesfully, \c false if there was an error.
 
        \since Haiku R1
 */
@@ -350,12 +413,14 @@
 
 /*!
        \fn bool BSplitView::AddChild(BLayoutItem *child)
-       \brief Undocumented public method
+       \brief Add a \a child.
+
+       The child will be added at the end of the existing layout items, 
meaning it
+       will be placed to the right or bottom of existing items.
 
-       \param child Undocumented
+       \param child The layout item to add.
 
-       \return Undocumented
-       \retval <value> Undocumented
+       \return \c true when succesfully, \c false if there was an error.
 
        \since Haiku R1
 */
@@ -363,13 +428,15 @@
 
 /*!
        \fn bool BSplitView::AddChild(BLayoutItem *child, float weight)
-       \brief Undocumented public method
+       \brief Add a \a child with a \a weight.
 
-       \param child Undocumented
-       \param weight Undocumented
+       The child will be added at the end of the existing layout items, 
meaning it
+       will be placed to the right or bottom of existing items.
 
-       \return Undocumented
-       \retval <value> Undocumented
+       \param child The layout item to add.
+       \param weight The weight of the item.
+
+       \return \c true when succesfully, \c false if there was an error.
 
        \since Haiku R1
 */
@@ -377,14 +444,16 @@
 
 /*!
        \fn bool BSplitView::AddChild(int32 index, BLayoutItem *child, float 
weight)
-       \brief Undocumented public method
+       \brief Add a \a child at \a index with a \a weight.
 
-       \param index Undocumented
-       \param child Undocumented
-       \param weight Undocumented
+       \param index The desired position for the \a child. Existing items will 
be
+               shifted to the right or down based on the orientation. If the 
index is
+               higher than the number of items, the item will be added after 
farmost
+               item. The index is zero-based.
+       \param child The layout item to add.
+       \param weight The weight of the item.
 
-       \return Undocumented
-       \retval <value> Undocumented
+       \return \c true when succesfully, \c false if there was an error.
 
        \since Haiku R1
 */
@@ -392,7 +461,7 @@
 
 /*!
        \fn virtual virtual void BSplitView::AttachedToWindow()
-       \brief Undocumented public method
+       \brief Hook method overridden from BView.
 
        \since Haiku R1
 */
@@ -400,9 +469,7 @@
 
 /*!
        \fn virtual virtual void BSplitView::Draw(BRect updateRect)
-       \brief Undocumented public method
-
-       \param updateRect Undocumented
+       \brief Hook method overridden from BView.
 
        \since Haiku R1
 */
@@ -410,9 +477,7 @@
 
 /*!
        \fn virtual virtual void BSplitView::DrawAfterChildren(BRect updateRect)
-       \brief Undocumented public method
-
-       \param updateRect Undocumented
+       \brief Hook method overridden from BView.
 
        \since Haiku R1
 */
@@ -420,9 +485,7 @@
 
 /*!
        \fn virtual virtual void BSplitView::MouseDown(BPoint where)
-       \brief Undocumented public method
-
-       \param where Undocumented
+       \brief Hook method overridden from BView.
 
        \since Haiku R1
 */
@@ -430,9 +493,7 @@
 
 /*!
        \fn virtual virtual void BSplitView::MouseUp(BPoint where)
-       \brief Undocumented public method
-
-       \param where Undocumented
+       \brief Hook method overridden from BView.
 
        \since Haiku R1
 */
@@ -440,11 +501,7 @@
 
 /*!
        \fn virtual virtual void BSplitView::MouseMoved(BPoint where, uint32 
transit, const BMessage *message)
-       \brief Undocumented public method
-
-       \param where Undocumented
-       \param transit Undocumented
-       \param message Undocumented
+       \brief Hook method overridden from BView.
 
        \since Haiku R1
 */
@@ -452,9 +509,7 @@
 
 /*!
        \fn virtual virtual void BSplitView::MessageReceived(BMessage *message)
-       \brief Undocumented public method
-
-       \param message Undocumented
+       \brief Hook method overridden from BView.
 
        \since Haiku R1
 */
@@ -462,9 +517,7 @@
 
 /*!
        \fn virtual virtual void BSplitView::SetLayout(BLayout *layout)
-       \brief Undocumented public method
-
-       \param layout Undocumented
+       \brief Hook method overridden from BView.
 
        \since Haiku R1
 */
@@ -472,27 +525,13 @@
 
 /*!
        \fn virtual virtual status_t BSplitView::Archive(BMessage *into, bool 
deep=true) const
-       \brief Undocumented public method
-
-       \param into Undocumented
-       \param deep Undocumented
-
-       \return Undocumented
-       \retval <value> Undocumented
-
-       \since Haiku R1
+       \copydoc BArchivable::Archive()
 */
 
 
 /*!
        \fn virtual virtual status_t BSplitView::Perform(perform_code d, void 
*arg)
-       \brief Undocumented public method
-
-       \param d Undocumented
-       \param arg Undocumented
-
-       \return Undocumented
-       \retval <value> Undocumented
+       \brief Hook method overridden from BView.
 
        \since Haiku R1
 */
@@ -500,12 +539,7 @@
 
 /*!
        \fn static static BArchivable* BSplitView::Instantiate(BMessage *from)
-       \brief Undocumented public method
-
-       \param from Undocumented
-
-       \return Undocumented
-       \retval <value> Undocumented
+       \brief Instantiate the view from the message \a from.
 
        \since Haiku R1
 */
@@ -513,12 +547,7 @@
 
 /*!
        \fn virtual virtual status_t BSplitView::AllArchived(BMessage *into) 
const
-       \brief Undocumented protected method
-
-       \param into Undocumented
-
-       \return Undocumented
-       \retval <value> Undocumented
+       \brief Hook method overridden from BArchivable.
 
        \since Haiku R1
 */
@@ -526,12 +555,7 @@
 
 /*!
        \fn virtual virtual status_t BSplitView::AllUnarchived(const BMessage 
*from)
-       \brief Undocumented protected method
-
-       \param from Undocumented
-
-       \return Undocumented
-       \retval <value> Undocumented
+       \brief Hook method overridden from BArchivable.
 
        \since Haiku R1
 */
@@ -539,12 +563,10 @@
 
 /*!
        \fn virtual virtual void BSplitView::DrawSplitter(BRect frame, const 
BRect &updateRect, orientation orientation, bool pressed)
-       \brief Undocumented protected method
+       \brief Hook method called when the splitter needs to be drawn.
 
-       \param frame Undocumented
-       \param updateRect Undocumented
-       \param orientation Undocumented
-       \param pressed Undocumented
+       This method is called in the context of a \ref BView::Draw() operation.
+       Derived classes can override this to draw a splitter.
 
        \since Haiku R1
 */
diff --git a/docs/user/interface/images/BSplitView_HaikuDepot.png 
b/docs/user/interface/images/BSplitView_HaikuDepot.png
new file mode 100644
index 0000000000..546f58e487
Binary files /dev/null and 
b/docs/user/interface/images/BSplitView_HaikuDepot.png differ


Other related posts:

  • » [haiku-commits] haiku: hrev54020 - in docs/user/interface/images: . docs/user/interface - Niels Sascha Reedijk