Add initial documentation for Layout API, not everything is documented, and it's not perfect, but its time to commit this.

git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@39055 a95241bf-73f2-0310-859d-f6bbb57e9c96

docs/user/Doxyfile

@@ -465,6 +465,7 @@ WARN_LOGFILE           =
 INPUT                  = . \
 						 app \
                          drivers \
+						 interface \
 						 locale \
                          midi \
                          midi2 \
@@ -473,6 +474,13 @@ INPUT                  = . \
                          ../../headers/os/drivers/fs_interface.h \
                          ../../headers/os/drivers/USB3.h \
                          ../../headers/os/drivers/USB_spec.h \
+						 ../../headers/os/interface/AbstractLayout.h \
+						 ../../headers/os/interface/GridLayout.h \
+						 ../../headers/os/interface/GroupLayout.h \
+						 ../../headers/os/interface/Layout.h \
+						 ../../headers/os/interface/LayoutBuilder.h \
+						 ../../headers/os/interface/LayoutItem.h \
+						 ../../headers/os/interface/TwoDimensionalLayout.h \
                          ../../headers/os/locale \
                          ../../headers/os/midi2 \
                          ../../headers/os/support \

docs/user/book.dox

@@ -5,6 +5,7 @@
 
   - \ref app | \link app_intro \em Introduction \endlink
   - \ref drivers
+  - \ref interface | \link interface_intro \em Introduction \endlink
   - \ref locale | \link locale_intro \em Introduction \endlink
   - \ref midi1
   - \ref midi2 | \link midi2_intro \em Introduction \endlink
@@ -21,6 +22,8 @@
 /*!
   \defgroup app Application Kit
   \defgroup drivers Drivers
+  \defgroup interface Interface Kit
+  \brief API for displaying a graphical user interface.
   \defgroup midi2 MIDI 2 Kit
   \brief API for producing and consuming MIDI events.
   \defgroup libmidi2 (libmidi2.so)
@@ -37,4 +40,7 @@
 /*!
   \defgroup support_globals Global functions in the support kit
   \ingroup support
+
+  \defgroup layout Layout classes in the Interface Kit
+  \ingroup interface
 */

docs/user/interface/AbstractLayout.dox

@@ -0,0 +1,122 @@
+/*!
+	\class BAbstractLayout
+	\ingroup interface
+	\ingroup layout
+	\ingroup libbe
+
+	\brief BLayout subclass providing convenience methods for derived
+	implementations.
+	
+	This class is designed to reduce the amount of boilerplate code required to
+	write a BLayout subclass. In most cases, you classes should derive from
+	BAbstractLayout rather than BLayout.
+
+	When a BAbstractLayout is attached to a BView, many of the methods provided
+	by the BAbstractLayout class are forwarded to the BAbstractLayout's
+	owner BView. When a BAbstractLayout is viewless, these methods are handled
+	locally.
+
+	\warning This class is not yet finalized, if you use it in your software
+	assume that it will break some time in the future.
+*/
+
+
+/*!
+	\name Constructors
+
+	@{
+*/
+
+
+/*!
+	\fn BAbstractLayout::BAbstractLayout()
+	\brief Construct a BAbstractLayout.
+*/
+
+
+/*!
+	\fn BAbstractLayout::BAbstractLayout(BMessage* from);
+	\brief Archive constructor.
+*/
+
+
+//@}
+
+
+/*!
+	\fn BSize BAbstractLayout::MinSize()
+	\copydoc BLayoutItem::MinSize()
+
+	The return value for this method is composed (using
+	BLayoutUtils::ComposeSize()) from the values returned by BaseMinSize() and
+	ExplicitMinSize().
+*/
+
+
+/*!
+	\fn BSize BAbstractLayout::MaxSize()
+	\copydoc BLayoutItem::MaxSize()
+
+	The return value for this method is composed (using
+	BLayoutUtils::ComposeSize()) from the values returned by BaseMaxSize() and
+	ExplicitMaxSize().
+*/
+
+
+/*!
+	\fn BSize BAbstractLayout::PreferredSize()
+	\copydoc BLayoutItem::PreferredSize()
+
+	The return value for this method is composed (using
+	BLayoutUtils::ComposeSize()) from the values returned by BasePreferredSize()
+	and ExplicitPreferredSize().
+*/
+
+
+/*!
+	\fn BAlignment BAbstractLayout::Alignment()
+	\copydoc BLayoutItem::Alignment()
+
+	The return value for this method is composed (using
+	BLayoutUtils::ComposeAlignment()) from the values returned by
+	BaseAlignment() and
+	ExplicitAlignment()
+*/
+
+
+/*!
+	\name BAbstractLayout hooks
+
+	@{
+*/
+
+
+/*!
+	\fn BSize BAbstractLayout::BaseMinSize()
+	\brief Method to be implemented in derived classes return the minimum size
+	constraint for this BAbstractLayout.
+*/
+
+
+/*!
+	\fn BSize BAbstractLayout::BaseMaxSize()
+	\brief Method to be implemented in derived classes return the maximum size
+	constraint for this BAbstractLayout.
+*/
+
+
+/*!
+	\fn BSize BAbstractLayout::BasePreferredSize()
+	\brief Method to be implemented in derived classes return the preferred size
+	constraint for this BAbstractLayout.
+*/
+
+
+/*!
+	\fn BAlignment BAbstractLayout::BaseAlignment()
+	\brief Method to be implemented in derived classes return the preferred
+	alignment for this BAbstractLayout.
+*/
+
+
+//@}

docs/user/interface/GridLayout.dox

@@ -0,0 +1,193 @@
+/*!
+	\class BGridLayout
+	\ingroup interface
+	\ingroup layout
+	\ingroup libbe
+
+	\brief The BGridLayout class a BLayout subclass that arranges the items it
+	holds in a grid.
+
+	Each item in a BGridLayout receives a rectangular area which can span more
+	than a single row or column. The indexing of columns and rows is zero based,
+	starting in the top-left.
+
+	\warning This class is not yet finalized, if you use it in your software
+	assume that it will break some time in the future.
+*/
+
+
+/*!
+	\fn BGridLayout::BGridLayout(float horizontal = 0.0f, float vertical = 0.0f)
+	\brief Create a BGridLayout with \c horizontal space between columns and
+		\c vertical space between rows.
+*/
+
+
+/*!
+	\fn BGridLayout::BGridLayout(BMessage* from)
+	\brief Archive constructor.
+*/
+
+
+/*!
+	\fn int32 BGridLayout::CountColumns() const
+	\brief Returns the number of active columns in this layout.
+*/
+
+
+/*!
+	\fn int32 BGridLayout::CountRows() const
+	\brief Returns the number of active rows in this layout.
+*/
+
+
+/*!
+	\fn float BGridLayout::HorizontalSpacing() const
+	\brief Returns the spacing between columns for this layout.
+*/
+
+
+/*!
+	\fn float BGridLayout::VerticalSpacing() const
+	\brief Returns the spacing between rows for this layout.
+*/
+
+
+/*!
+	\fn void BGridLayout::SetHorizontalSpacing(float spacing);
+	\brief Set the spacing between columns for this layout.
+*/
+
+
+/*!
+	\fn void BGridLayout::SetVerticalSpacing(float spacing)
+	\brief Set the spacing between rows for this layout.
+*/
+
+
+/*!
+	\fn	void BGridLayout::SetSpacing(float horizontal, float vertical)
+	\brief Set the spacing between columns and rows for this layout.
+*/
+
+
+/*!
+	\fn float BGridLayout::ColumnWeight(int32 column) const
+	\brief Returns the weight for \c column.
+*/
+
+
+/*!
+	\fn void BGridLayout::SetColumnWeight(int32 column, float weight)
+	\brief Set the weight for \c column to \c weight.
+*/
+
+
+/*!
+	\fn float BGridLayout::MinColumnWidth(int32 column) const
+	\brief Returns the minimum width for \c column.
+*/
+
+
+/*!
+	\fn void BGridLayout::SetMinColumnWidth(int32 column, float width)
+	\brief Sets the minimum width for \c column to \c width.
+*/
+
+
+/*!
+	\fn float BGridLayout::MaxColumnWidth(int32 column) const
+	\brief Returns the maximum width for \c column.
+*/
+
+
+/*!
+	\fn void BGridLayout::SetMaxColumnWidth(int32 column, float width)
+	\brief Sets the maximum width for \c column to \c width.
+*/
+
+
+/*!
+	\fn float BGridLayout::RowWeight(int32 row) const
+	\brief Returns the weight for \c row.
+*/
+
+
+/*!
+	\fn void BGridLayout::SetRowWeight(int32 row, float weight)
+	\brief Set the weight for \c row to \c weight.
+*/
+
+
+/*!
+	\fn float BGridLayout::MinRowHeight(int32 row) const
+	\brief Returns the minimum height for \c row.
+*/
+
+
+/*!
+	\fn void BGridLayout::SetMinRowHeight(int32 row, float height)
+	\brief Sets the minimum height for \c row to \c width.
+*/
+
+
+/*!
+	\fn float BGridLayout::MaxRowHeight(int32 row) const
+	\brief Returns the maximum height for \c row.
+*/
+
+
+/*!
+	\fn void BGridLayout::SetMaxRowHeight(int32 row, float height)
+	\brief Sets the maximum height for \c row to \c width.
+*/
+
+
+/*!
+	\fn BLayoutItem* BGridLayout::AddView(BView* child)
+	\brief Adds \c child to this layout in the first empty cell available, or
+		in a new column in the first row if there are no emtpy cells.
+*/
+
+
+/*!
+	\fn BLayoutItem* BGridLayout::AddView(int32 index, BView* child);
+	\copybrief BGridLayout::AddView(BView*)
+*/
+
+
+/*!
+	\fn BLayoutItem* BGridLayout::AddView(BView* child, int32 column, int32 row,
+			int32 columnCount = 1, int32 rowCount = 1);
+	\brief Adds \c child to this layout at \c column and \c row. \c child may
+		also occupy additional cells if \c columnCount or \c rowCount are
+		greater than 1.
+
+	Fails and returns NULL if the requested area is occupied, or if internal
+	memory allocations fail.
+*/
+
+
+/*!
+	\fn BLayoutItem* BGridLayout::AddItem(BLayoutItem* item)
+	\brief Adds \c item to this layout in the first empty cell available, or
+		in a new column in the first row if there are no emtpy cells.
+*/
+
+
+/*!
+	\fn BLayoutItem* BGridLayout::AddItem(int32 index, BLayoutItem* item);
+	\copybrief BGridLayout::AddItem(BLayoutItem*)
+*/
+
+
+/*!
+	\fn BLayoutItem* BGridLayout::AddItem(BLayoutItem* item, int32 column,
+		int32 row, int32 columnCount = 1, int32 rowCount = 1);
+	\brief Adds \c item to this layout at \c column and \c row. \c item may
+		also occupy additional cells if \c columnCount or \c rowCount are
+		greater than 1.
+
+	Fails and returns NULL if the requested area is occupied, or if internal
+	memory allocations fail.
+*/

docs/user/interface/GroupLayout.dox

@@ -0,0 +1,146 @@
+/*! \class BGroupLayout
+	\ingroup interface
+	\ingroup layout
+	\ingroup libbe
+	\brief The BGroupLayout class is a simple BLayout subclass that
+	arranges the items it holds within a vertical or horizontal box.
+
+	In a horizontal BGroupLayout, each BLayoutItem is given the same vertical
+	area, but different horizontal areas. In a vertical BGroupLayout, each
+	BLayoutItem is given the same horizontal area, but different vertical areas.
+	Despite this, because of alignment and size constraints, the items in a
+	BGroupLayout may not all use the same vertical or horizontal area on screen.
+	Some BLayoutItems may have alignments that cause them to sit at the bottom
+	of the area they are given, for example. This is not a flaw or bug, but
+	something that you may come across when using this class.
+
+	In a BGroupLayout, each BLayoutItem or BView has a weight, the default
+	weight is \c 1.0f. When a BGroupLayout is not given enough space to satisfy
+	the minimum sizes of all items, then space is distributed according to
+	weight, while still attempting to satisfy minimum size constraints.
+	Weighting is scaled over the sum weight of all the items in this layout.
+	If a particular item has half of the sum weight of all items, it
+	will get half of the total space, unless this exceeds that item's maximum
+	size. If the space for an item exceeds the items maximum size, the excess
+	will be distributed to other items.
+
+	\warning This class is not yet finalized, if you use it in your software
+	assume that it will break some time in the future.
+*/
+
+
+/*!
+	\fn BGroupLayout::BGroupLayout(enum orientation, float spacing)
+	\brief Creates a new BGroupLayout.
+
+	\param orientation The orientation of this BGroupLayout.
+	\param spacing The spacing between BLayoutItems in this BGroupLayout.
+*/
+
+
+/*!
+	\fn BGroupLayout::BGroupLayout(BMessage* from)
+	\brief Archive constructor.
+*/
+
+
+/*!
+	\fn float BGroupLayout::Spacing() const
+	\brief Get the amount of spacing (in pixels) between each item.
+*/
+
+
+/*!
+	\fn void BGroupLayout::SetSpacing(float spacing)
+	\brief Set the amount of spacing (in pixels) between each item.
+*/
+
+
+/*!
+	\fn orientation BGroupLayout::Orientation() const
+	\brief Get the orientation of this BGroupLayout.
+*/
+
+
+/*!
+	\fn void BGroupLayout::SetOrientation(enum orientation)
+	\brief Set the orientation of this BGroupLayout.
+	\param orientation The new orientation of this BGroupLayout.
+*/
+
+
+/*!
+	\fn float BGroupLayout::ItemWeight(int32 index) const
+	\brief Get the weight of the item at \c index.
+*/
+
+
+/*!
+	\fn void BGroupLayout::SetItemWeight(int32 index, float weight)
+	\brief Set the weight of the item at \c index.
+*/
+
+
+/*!
+	\fn BLayoutItem* BGroupLayout::AddView(BView* child)
+	\brief Adds \a child to this layout as the last item. In a vertical
+		BGroupLayout, \c child will be on the right, in a horizontal
+		BGroupLayout, \c child will be at the bottom.
+
+	\c child will have a weight of 1.0f.
+*/
+
+
+/*!
+	\fn BLayoutItem* BGroupLayout::AddView(int32 index, BView* child)
+	\brief Adds \c child to this layout at \c index.
+
+	\c child will have a weight of 1.0f.
+*/
+
+
+/*!
+	\fn BLayoutItem* BGroupLayout::AddView(BView* child, float weight)
+	\brief Adds \c child to the end of this layout with a weight of
+		\c weight.
+*/ 
+
+
+/*!	
+	\fn BLayoutItem* BGroupLayout::AddView(int32 index, BView* child,
+		float weight)
+	\brief Adds \c child this layout at \c index with a weight of
+		\c weight.
+*/
+
+
+/*!
+	\fn bool BGroupLayout::AddItem(BLayoutItem* item)
+	\brief Adds \a item to this layout as the last item. In a vertical
+		BGroupLayout, \c item will be on the right, in a horizontal
+		BGroupLayout, \c item will be at the bottom.
+
+	\c item will have a weight of 1.0f.
+*/
+
+
+/*!
+	\fn bool BGroupLayout::AddItem(int32 index, BLayoutItem* item)
+	\brief Adds \c item to this layout at \c index.
+
+	\c item will have a weight of 1.0f.
+*/
+
+
+/*!
+	\fn bool BGroupLayout::AddItem(BLayoutItem* item, float weight)
+	\brief Adds \c item to the end of this layout with a weight of
+		\c weight.
+*/
+
+
+/*!
+	\fn bool BGroupLayout::AddItem(int32 index, BLayoutItem* item, float weight)
+	\brief Adds \c item this layout at \c index with a weight of
+		\c weight.
+*/

docs/user/interface/Layout.dox

@@ -0,0 +1,525 @@
+/*
+ * Copyright 2010, Haiku, Inc. All Rights Reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Documentation by:
+ *  Alex Wilson <[email protected]>
+ * Corresponds to:
+ *   /trunk/headers/os/interface/Layout.h  rev 38207
+ *   /trunk/src/kits/interface/Layout.cpp  rev 38207
+ */
+
+
+/*!
+\file Layout.h
+\brief Defines the BLayout class.
+*/
+
+
+/*! \class BLayout
+	\ingroup interface
+	\ingroup layout
+	\ingroup libbe
+	\brief The BLayout class provides an interface, and some basic
+		implementation to manage the positioning and sizing of BLayoutItems.
+
+	BLayouts can be attached to a BView, managing the BLayoutItems and BViews
+	that reside in that view, or can be nested within another BLayout as a
+	BLayoutItem.
+
+	Before adding a BLayoutItem to a BLayout, that layout must have a target
+	view. When a BLayout is attached directly to a BView via BView::SetLayout()
+	then that BView becomes the target of the layout. When a BLayout is nested
+	in another BLayout (via BLayout::AddItem()) the nested BLayout inherits the
+	target of the layout it's nested in, if it does not have a target already.
+	You can retrieve the target view for a layout with the TargetView() method.
+	When adding a BLayoutItem to a BLayout, the item's view (as returned by
+	BLayoutItem::View()) is added to the layout's target view.
+
+\code
+BView* topView = new BGroupView();
+BLayout* topLayout = topView->GetLayout();
+
+BLayout* nestedLayout = new BGroupLayout(B_HORIZONTAL);
+topLayout->AddItem(nestedLayout);
+
+BLayout* veryNestedLayout = new BGroupLayout(B_VERTICAL);
+nestedLayout->AddItem(veryNestedLayout);
+\endcode
+
+	After executing this code, \c veryNestedLayout, \c nestedLayout, and
+	\c topLayout all have the same target view: \c topView.
+
+	Continuing with the same objects...
+
+\code
+BLayout* nestedLayoutWithView = (new BGroupView())->GetLayout();
+topLayout->AddItem(nestedLayoutWithView);
+\endcode
+
+	\c nestedLayoutWithView does have a target view of \c topView. This is
+	because \c nestedLayoutWithView is attached directly to a BView.
+
+	\warning This class is not yet finalized, if you use it in your software
+	assume that it will break some time in the future.
+*/
+
+								
+/*! \fn BLayout::BLayout()
+	\brief Default constructor.
+
+	After this constructor has finished, this BLayout holds no BLayoutItems and
+	does not have a target BView.
+	
+	\warning Because a new BLayout does not have a target BView, calls to the
+		AddItem() and AddView() will fail methods will fail.
+*/
+
+
+/*! \fn BLayout::BLayout(BMessage* archive)
+	\brief Archive constructor.
+*/
+
+
+/*! \fn BLayout::~BLayout()
+	\brief Destructor, deletes all BLayoutItems that this layout manages,
+		and detaches from this BLayout's owner view if there is one.
+
+	Each BLayoutItem's BView (as returned by BLayoutItem::View()) is also
+	removed from their parent.
+
+	\note Because nested BLayouts are treated as BLayoutItems, any layouts
+	nested in this BLayout will be deleted.
+*/
+
+
+/*!
+	\name BView targeting and attachment information.
+
+	@{
+*/
+
+
+/*! \fn BView* BLayout::Owner() const
+	\brief Returns the Owner of this layout, i.e. the view this layout manages.
+*/
+
+
+/*! \fn BView* BLayout::TargetView() const
+	\brief Returns the target view of this layout.
+
+	The target view of a layout becomes the parent of any BViews in this layout,
+	as well as the BViews returned by BLayoutItem::View() for each BLayoutItem
+	in this layout.
+*/
+
+
+/*! \fn BView* BLayout::View()
+	\brief Returns the same BView* as BLayout::Owner(), this method is inherited
+		 from BLayoutItem.
+*/
+
+
+//@}
+
+
+/*!
+	\name Adding, removing, counting and accessing BViews and BLayoutItems in \
+		this BLayout.
+
+	@{
+*/
+
+
+/*!
+	\fn BLayoutItem* BLayout::AddView(BView* child)
+	\brief Creates a BLayoutItem to represent a BView, and adds that item to
+		this layout.
+		
+	\a child is added to this layout's target view.
+	
+	\returns The BLayoutItem created to represent \a child is, or NULL if there
+		was an error.
+
+	\param child The BView to be added to this BLayout. 
+*/
+
+
+/*! \fn	BLayoutItem* BLayout::AddView(int32 index, BView* child)
+	\brief Creates a BLayoutItem to represent \a child, and adds that item at
+		\a index to	this layout. \a child is added to this layout's target view.
+*/
+
+
+/*!
+	\fn bool BLayout::AddItem(BLayoutItem* item)
+	\brief Adds a BLayoutItem to this layout, and adds the BView it represents
+		to this layout's target view.
+
+	\param item The BLayoutItem to be added.
+	\retval true success
+	\retval false failure
+*/
+
+
+/*!
+	\fn bool BLayout::AddItem(int32 index, BLayoutItem* item)
+	\brief Adds \a item to this layout, and adds the BView \a item represents
+		to this layout's target view.
+
+	\param item The BLayoutItem to be added.
+	\param index The index at which to add \c item.
+
+	If \a index is out of bounds, \a item will be added at the end. If \a index
+	is somewhere between the first and last indices, then items from \a index
+	to the end will be shuffled over by one.
+
+	\retval true success
+	\retval false failure
+*/
+
+
+/*!
+	\fn bool BLayout::RemoveView(BView* child)
+	\brief Removes and deletes all BLayoutItems representing a BView from this
+		layout.
+
+	\param child The BView to be removed.
+
+	\retval true success
+	\retval false failure
+*/
+
+
+/*!
+	\fn	bool BLayout::RemoveItem(BLayoutItem* item)
+	\brief Removes a BLayoutITem from this layout, and also removes the view 
+		it represents from this layout's target view.
+
+	\param item The BLayoutitem to be removed
+	
+	\warning \a item is not deleted, you must delete it manually, or add it	to
+		another BLayout.
+
+	\retval true success
+	\retval false failure
+*/
+
+
+/*! \fn BLayoutItem* BLayout::RemoveItem(int32 index)
+	\brief Remove the BLayoutItem at \a index.
+
+	\see RemoveItem(BLayoutItem*)
+
+	\returns The BLayoutItem that was removed.
+*/
+
+
+/*!
+	\fn BLayoutItem* BLayout::ItemAt(int32 index) const
+	\brief Get the BLayoutItem at \a index. Returns \c NULL if \a index is
+		out of bounds.
+*/
+
+
+/*!
+	\fn int32 BLayout::CountItems() const
+	\brief Get the number of BLayoutItems in this layout.
+*/
+
+
+/*!
+	\fn int32 BLayout::IndexOfItem(const BLayoutItem* item) const
+	\brief Get the index of a BLayoutItem in this layout.
+
+	\param item The BLayoutItem whose index you want.
+
+	\retval -1 \a item was not found in this BLayout.
+*/
+
+
+/*!
+	\fn int32 BLayout::IndexOfView(BView* child) const
+	\brief Get the index of \a child in this layout.
+	
+	\note This finds the index of views added through BLayout::AddView(), not
+		the index of an item which represents \a child that was added through
+		BLayout::AddItem().
+*/
+
+
+//@}
+
+
+/*!
+	\name Subclass helpers.
+	\brief These methods are meant to ease the development of BLayout
+		subclasses.
+
+	@{
+*/
+
+
+/*! \fn bool BLayout::AncestorsVisible()
+	\brief Get the visibility of the ancestors of this layout.
+
+	If a BLayout is connected to a BView, this will always return \c true.
+	If a BLayout is nested in another layout (it was passed to AddItem()), then
+	this will reflect the visibility of this layout's parent layout. If any
+	layout is hidden (by BLayout::SetVisible()) between this layout and its
+	target view's layout, then this method will return \c false.
+*/
+
+
+/*!
+	\fn BRect BLayout::LayoutArea()
+	\brief Returns the on-screen area this layout has received to lay out its
+		items in.
+
+	The return value is in the coordinate space of this layout's target view.
+	If this BLayout is attached directly to a BView, then
+	<tt> LayoutArea().LeftTop() == B_ORIGIN </tt>.
+*/
+
+
+/*!
+	\fn void BLayout::VisibilityChanged(bool show)
+	\brief Method to be called by derived classes in their SetVisible()
+		implementation. Calls AncestorVisibilityChanged() on the items in this
+		BLayout.
+*/
+
+
+//@}
+
+
+/*!
+	\name Methods triggering or related to laying out this BLayout.
+
+//@{
+*/
+
+
+/*!	\fn void BLayout::Relayout(bool immediate = false)
+	\brief Request this BLayout to reposition and resize its items as required.
+
+	If \a immediate is \c false, and there is already a request to have the
+	window this layout resides in re-laid-out, then the layout will happen at
+	that time. If \a immediate is \c true, and there is no such pending
+	request, nor is this layout's parent layout in the process of laying out
+	its items, then this BLayout will now layout its items.
+*/
+
+
+/*!
+	\fn void BLayout::LayoutItems(bool force = false)
+	\brief If there is no layout currently ongoing, and \a force is \c false,
+		creates a new BLayoutContext and calls the DerivedLayoutItems() method
+		of this BLayout and any BLayouts nested in this BLayout.
+	
+	If method also guarantees that the owner view of this layout (as returned
+	by BLayout::Owner()) performs a layout as well (if it is suitable to do so).
+*/
+
+
+/*!
+	\fn BLayoutContext* BLayout::LayoutContext()
+	\brief Returns the BLayoutContext this BLayout is currently operating in,
+		or \c NULL.
+*/
+
+
+//@}
+
+
+/*!
+	\name Invalidation and state mutators and accessors.
+
+	@{
+*/
+
+
+/*!
+	\fn void BLayout::RequireLayout()
+	\brief Flag this layout as stale, i.e. any cached data may still be valid,
+		but the items need to be repositioned or resized.
+*/
+
+
+/*!
+	\fn void BLayout::InvalidateLayout(bool children = false)
+	\brief Invalidate this layout and any cached data this layout has relating
+		to positioning and sizing of its items.
+
+	Invalidating a BLayout also invalidates the view it is connected to
+	(if there is one) and the BLayout this layout (or this layout's view)
+	resides in.
+
+	This method should be called whenever the layout becomes invalid. This might
+	happen if the size constraints of an item in this layout change, this layout
+	is given more or less space than it previously had, or an object in this
+	layout has had its InvalidateLayout() method called.
+
+	\see BView::InvalidateLayout() BLayoutItem::InvalidateLayout()
+*/
+
+
+/*!
+	\fn bool BLayout::IsValid()
+	\brief Returns whether this layout has been invalidated (via
+		BLayout::InvalidateLayout()) and has not yet been validated (by doing a
+		layout, or by its ResetLayoutInvalidation() method.
+*/
+
+
+/*!
+	\fn void BLayout::EnableLayoutInvalidation()
+	\brief Re-enable layout invalidation after a call to
+		DisableLayoutInvalidation().
+*/
+
+
+/*! \fn void BLayout::DisableLayoutInvalidation()
+	\brief Disable layout invalidation notifications, i.e. calls to
+		this object's InvalidateLayout() method.
+*/
+
+
+/*!
+	\fn void BLayout::ResetLayoutInvalidation()
+	\brief Reset layout invalidation, causing InvalidateLayout calls to proceed
+		again. This method should be called once any cached data has been
+		validated, or updated to valid values.
+*/
+
+
+//@}
+
+
+/*!
+	\name Archiving methods
+	\brief These methods relate to the archiving or unarchiving of this object
+		and the BLayoutItems it contains
+
+	@{
+*/
+
+	
+/*!
+	\fn status_t BLayout::Archive(BMessage* archive, bool deep = true) const
+	\brief Archives this layout into \a archive. If deep is true, also archives
+		the items in this layout, calling ItemArchived() for each one.
+*/
+
+
+/*!
+	\fn status_t BLayout::AllUnarchived(const BMessage* from)
+	\brief Unarchives the BLayoutItems for this layout, calling ItemUnarchived()
+		for each one.
+*/
+
+
+/*!
+	\fn status_t BLayout::ItemArchived(BMessage* into, BLayoutItem* item,
+		int32 index) const
+	\brief Hook for derived classes to add data specific to \a item to the
+		\a into BMessage. \a item resides at \a index.
+
+	\note The same archive is passed to BLayout::ItemArchived() for all items,
+	so any data added for each item will be stored in an array.
+*/
+
+
+/*!
+	\fn status_t BLayout::ItemUnarchived(const BMessage* from,
+		BLayoutItem* item, int32 index)
+	\brief Hook for derived classes to retrieve data specific to \a item from
+		the \a from BMessage. \a item resides at \a index.
+
+	\note The same archive is passed to BLayout::ItemArchived() for all items,
+	so any data added for each item will be stored in an array. You should pass
+	\a index to the BMessage methods you will be using in this method.
+*/
+
+
+//@}
+
+
+/*!
+	\name BLayout Hook methods
+
+	@{
+*/
+
+
+/*!
+	\fn bool BLayout::ItemAdded(BLayoutItem* item, int32 atIndex)
+	\brief Hook method called when \a item is added to this layout.
+
+	\param item The BLayoutItem that is being added.
+	\param atIndex The index of the BLayoutItem.
+
+	\retval true success
+	\retval false failure, \a item will not be added.
+
+	\note This is a good time to allocate data for a BLayoutItem and attach it
+	to \a item via BLayoutItem::SetLayoutData().
+*/
+
+
+/*!
+	\fn void BLayout::ItemRemoved(BLayoutItem* item, int32 fromIndex)
+	\brief Hook method called when \a item is removed from this layout.
+
+	\param item The BLayoutItem being removed.
+	\param fromIndex The index where \a item used to reside.
+
+	\note This is a good time to delete the data you've attached to \a item
+	via BLayoutItem::SetLayoutData().
+*/
+
+
+/*!
+	\fn void BLayout::DerivedLayoutItems() = 0
+	\brief Implemented by derived classes to position and resize the items in
+		this layout.
+*/
+
+
+/*!
+	\fn void BLayout::OwnerChanged(BView* was)
+	\brief Hook method called when this layout is attached to a BView.
+
+	\param was The previous owner of this BLayout, for new BLayouts, this will
+	be NULL.
+*/
+
+
+/*!
+	\fn void BLayout::AttachedToLayout()
+	\brief Hook method inherited from BLayoutItem, classes derived from BLayout
+		must include the BLayout version of this method in their
+		implementation.
+*/
+
+
+/*!
+	\fn void BLayout::DetachedFromLayout(BLayout* layout)
+	\brief Hook method inherited from BLayoutItem, classes derived from BLayout
+		must include the BLayout version of this method in their
+		implementation.
+
+	\param layout The BLayout that this BLayout was detached from.
+*/
+
+
+/*!
+	\fn void BLayout::AncestorVisibilityChanged(bool shown)
+	\brief Hook method inherited from BLayoutItem, classes derived from BLayout
+		must include the BLayout version of this method in their
+		implementation.
+*/
+
+
+//@}
+

docs/user/interface/LayoutBuilder.Group.dox

@@ -0,0 +1,346 @@
+/*!
+	\class BLayoutBuilder::Group<>
+	\ingroup interface
+	\ingroup layout
+	\brief BLayoutBuilder::Base subclass for building BGroupLayouts.
+*/
+
+
+/*!
+	\typedef BLayoutBuilder::Group<ParentBuilder>::GroupBuilder
+	\brief Shorthand for builders returned by this builder's AddGroup() methods.
+*/
+
+
+/*!
+	\typedef BLayoutBuilder::Group<ParentBuilder>::GridBuilder
+	\brief Shorthand for builders returned by this builder's AddGrid() methods.
+*/
+
+
+/*!
+	\typedef BLayoutBuilder::Group<ParentBuilder>::SplitBuilder
+	\brief Shorthand for builders returned by this builder's AddSplit() methods.
+*/
+
+
+/*!
+	\typedef BLayoutBuilder::Group<ParentBuilder>::ThisBuilder
+	\brief Shorthand representing the type of \c this.
+*/
+
+
+/*!
+	\name Constructors
+
+	@{
+*/
+
+
+/*!
+	\fn BLayoutBuilder::Group<ParentBuilder>::Group(BWindow* window,
+		enum orientation, float spacing)
+	\brief Creates a new BGroupLayout, and attaches it to a BWindow.
+
+	\note The top BView* in \a window has its ViewColor set to
+		B_PANEL_BACKGROUND_COLOR.
+	\param window Thew BWindow* to attach the newly created BGroupLayout to.
+	\param orientation The orientation for the new BGroupLayout.
+	\param spacing The spacing for the new BGroupLayout.
+*/
+
+
+/*!
+	\fn BLayoutBuilder::Group<ParentBuilder>::Group(BGroupLayout* layout)
+	\brief Creates a builder targeting a BGroupLayout.
+
+	Methods called on this builder will be directed to \a layout.
+	\param layout The BGroupLayout to target with this builder.
+*/
+
+
+/*!
+	\fn BLayoutBuilder::Group<ParentBuilder>::Group(BGroupView* view)
+	\brief Creates a builder targeting a BGroupView.
+
+	Methods called on this builder will be directed to
+	\c view->GroupLayout().
+
+	\param view The BGroupView this builder will target.
+*/
+
+
+/*!
+	\fn template <ParentBuilder> BLayoutBuilder::Group<ParentBuilder>::Group(
+		enum orientation, float spacing)
+	\brief Creates a new BGroupView and targets it.
+
+	Methods called on this builder will be directed to the new BGroupView's
+	BGroupLayout.
+
+	\param orientation The orientation for the new BGroupView.
+	\param spacing The spacing for the new BGroupView.
+*/
+
+
+//@}
+
+
+/*!
+	\name Adding BViews and BLayoutItems
+
+	@{
+*/
+
+/*!
+	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::Add(BView* view)
+	\brief Add a BView to the BGroupLayout this builder represents.
+
+	\param view The BView to be added.
+	\see BGroupLayout::AddView(BView*)
+*/
+
+
+/*!
+	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::Add(BView* view,
+		float weight)
+	\brief Add BView to the BGroupLayout this builder represents.
+
+	\param view The BView to be added.
+	\param weight The weight to give \a view.
+	\see BGroupLayout::AddView(BView* view, float weight)
+*/
+
+
+/*!
+	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::Add(
+		BLayoutItem* item)
+	\brief Add a BLayoutItem to the BGroupLayout this builder represents.
+
+	\param item The BLayoutItem to be added.
+	\see BGroupLayout::AddItem(BLayoutItem*)
+*/
+
+
+/*!
+	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::Add(BLayoutItem*
+		item, float weight)
+	\brief Add a BLayoutItem the BGroupLayout this builder represents.
+
+	\param item The BLayoutItem to be added.
+	\param weight The weight to give \a item.
+	\see BGroupLayout::AddItem(BLayoutItem* item, float weight)
+*/
+
+
+//@}
+
+
+/*!
+	\name Adding BLayouts and their BView pairs
+	\brief 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::Group<ParentBuilder>::AddGroup(
+		enum 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.
+*/
+
+
+/*!
+	\fn GroupBuilder BLayoutBuilder::Group<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.
+*/
+
+
+/*!
+	\fn GroupBuilder BLayoutBuilder::Group<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.
+*/
+
+
+/*!
+	\fn GridBuilder	BLayoutBuilder::Group<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 BGroupLayout in the BGroupLayout this
+		builder represents.
+	\returns A GridBuilder representing the newly created BGridLayout.
+*/
+
+
+/*!
+	\fn GridBuilder BLayoutBuilder::Group<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 groupLayout in the BGroupLayout this builder
+		represents.
+	\returns a GridBuilder representing \a gridLayout.
+*/
+
+
+/*!
+	\fn GridBuilder	BLayoutBuilder::Group<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 groupLayout in the BGroupLayout this builder
+		represents.
+
+	\returns a GridBuilder representing \a gridView.
+*/
+
+
+/*!
+	\fn SplitBuilder BLayoutBuilder::Group<ParentBuilder>::AddSplit(
+		enum 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 BGroupLayout for the new BSplitView.
+
+	\returns a SplitBuilder representing the new BSplitView.
+*/
+
+
+/*!
+	\fn SplitBuilder BLayoutBuilder::Group<ParentBuilder>::AddSplit(
+		BSplitView* splitView, float weight = 1.0f)
+	\brief Add a BSplitView to the BGroupLayout 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 BGroupLayout this builder
+		represents.
+*/
+
+
+//@}
+
+
+/*!
+	\name Adding BSpaceLayoutItems
+	Some convenience methods for adding special BSpaceLayoutItems.
+
+	@{
+*/
+
+
+/*!
+	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::AddGlue(
+		float weight = 1.0f)
+	\brief Add a BSpaceLayoutItem created by BSpaceLayoutItem::CreateGlue()
+		to the BGroupLayout this builder represents.
+
+	\param weight The weight of the BSpaceLayoutItem in the BGroupLayout this
+		builder represents
+*/
+
+
+/*!
+	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::AddStrut(float size)
+	\brief Add a BSpaceLayoutItem created by
+		BSpaceLayoutItem::CreateHorizontalStrut() or
+		BSpaceLayoutItem::CreateVerticalStrut()	to the BGroupLayout this builder
+		 represents.
+
+	\param size The width or height of the strut to be created (depending on
+		the orientation of the BGroupLayout this builder represents).
+*/
+
+
+//!@}
+
+
+/*!
+	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::SetInsets(float left,
+		 float top, float right, float bottom)
+	\brief Call the BTwoDimensionalLayout::SetInsets() method on the
+		BGroupLayout this builder represents.
+*/
+
+
+/*!
+	\name Accessors
+
+	@{
+*/
+
+
+/*!
+	\fn BGroupLayout* BLayoutBuilder::Group<ParentBuilder>::Layout() const
+	\brief Get the BGroupLayout this builder represents.
+*/
+
+
+/*!
+	\fn	BView* BLayoutBuilder::Group<ParentBuilder>::View() const
+	\brief Get the BView this builder's BGroupLayout is attached to.
+*/
+
+
+/*!
+	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::GetLayout(
+		BGroupLayout** _layout)
+	\brief Get the BGroupLayout this builder represents.
+	\param[out] _layout The BGroupLayout this builder represents.
+*/
+
+
+/*!
+	\fn	ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::GetView(
+	BView** _view)
+	\brief Get the BView this builder's BGroupLayout is attached to.
+	\param[out] _view The BView this builder's BGroupLayout is attached to.
+*/
+
+
+/*!
+	\fn BLayoutBuilder::Group<ParentBuilder>::operator BGroupLayout*()
+	\brief Cast this builder into the BGroupLayout it represents.
+*/
+
+//!@}

docs/user/interface/LayoutBuilder.dox

@@ -0,0 +1,224 @@
+/*!
+	\class BLayoutBuilder::Base<>
+	\ingroup interface
+	\ingroup layout
+	\brief Base for all other layout builders in the BLayoutBuilder namespace.
+
+	This class provides the stack-like semantics for its subclasses. The
+	BLayoutBuilder::Group, BLayoutBuilder::Grid and BLayoutBuilder::Split all
+	provide methods such as AddGrid() AddGroup() and AddSplit(), which 
+	make a new builder, place it on top of your builder stack and return it.
+	Now you are operating on the new builder. When you call	the End() method on
+	the new builder, you are returned the one you had previously been using. At
+	any point, you are calling methods on whatever builder currently resides on
+	the top of the stack. Here's an example of how these classes work.
+
+\code
+BLayoutBuilder::Group<>(B_HORIZONTAL)
+\endcode
+
+	At this point our stack just contains a single builder, it looks like this:
+		\li Group<>
+
+\code
+	.AddGrid()
+\endcode
+
+	Now there is a Grid builder on top of the stack, so it looks like this \li Group<>::GridBuilder
+		\li Group<>
+
+	Notice that the Grid on top of the stack is not a plain Grid<>, but a nested
+	type from the Group<> class. This is an essential part of the builder
+	classes, as this is what allows you to pop builders off the stack and get
+	the correct type in return.
+
+\code
+		.AddSplit()
+\endcode
+
+	Now our stack looks like this:
+		\li Group<>::GridBuilder::SplitBuilder
+		\li Group<>::GridBuilder
+		\li Group<>
+
+	This could continue ad. nauseam, but at some point, you may finish with a
+	builder, and you might want to continue manipulating the builder below it
+	on the stack. To do this, you simply call the End() method like so:
+
+\code
+			.End()
+\endcode
+
+	And now the stack is back to this:
+		\li Group<>::GridBuilder
+		\li Group<>
+
+	So you are again working with the grid builder. You can add more
+	BLayoutItems or BViews, or even more builders. Here's how it will all look
+	together.
+
+\code
+BLayoutBuilder::Group<>(B_HORIZONTAL)
+	// working with the Group builder
+	.AddGrid()
+		// working with the Group<>::GridBuilder
+		.AddSplit()
+			// working with the Group<>::GridBuilder::SplitBuilder
+		.End()
+		// back to the Group<>::GridBuilder
+\endcode
+*/
+
+
+/*!
+	\fn void BLayoutBuilder::Base<ParentBuilder>::SetParent(ParentBuilder*
+		parent)
+	Internal method for use by BLayoutBuilder::Base subclasses, this is
+	essential to the builder stack semantics
+*/
+
+
+/*!
+	\fn ParentBuilder& BLayoutBuilder::Base<ParentBuilder>::End()
+	\brief Returns this builder's parent.
+*/
+
+
+
+/*
+
+
+template<typename ParentBuilder>
+class Grid : public Base<ParentBuilder> {
+public:
+	typedef Grid<ParentBuilder>		ThisBuilder;
+	typedef Group<ThisBuilder>		GroupBuilder;
+	typedef Grid<ThisBuilder>		GridBuilder;
+	typedef Split<ThisBuilder>		SplitBuilder;
+
+public:
+	inline						Grid(float horizontalSpacing = 0.0f,
+									float verticalSpacing = 0.0f);
+	inline						Grid(BWindow* window,
+									float horizontalSpacing = 0.0f,
+									float verticalSpacing = 0.0f);
+	inline						Grid(BGridLayout* layout);
+	inline						Grid(BGridView* view);
+
+	inline	BGridLayout*		Layout() const;
+	inline	BView*				View() const;
+	inline	ThisBuilder&		GetLayout(BGridLayout** _layout);
+	inline	ThisBuilder&		GetView(BView** _view);
+
+	inline	ThisBuilder&		Add(BView* view, int32 column, int32 row,
+									int32 columnCount = 1, int32 rowCount = 1);
+	inline	ThisBuilder&		Add(BLayoutItem* item, int32 column, int32 row,
+									int32 columnCount = 1, int32 rowCount = 1);
+	inline	ThisBuilder&		AddMenuField(BMenuField* menuField,
+									int32 column, int32 row,
+									alignment labelAlignment
+										= B_ALIGN_HORIZONTAL_UNSET,
+									int32 columnCount = 1, int32 rowCount = 1);
+	inline	ThisBuilder&		AddTextControl(BTextControl* textControl,
+									int32 column, int32 row,
+									alignment labelAlignment
+										= B_ALIGN_HORIZONTAL_UNSET,
+									int32 columnCount = 1, int32 rowCount = 1);
+
+	inline	GroupBuilder		AddGroup(enum orientation orientation,
+									float spacing, int32 column, int32 row,
+									int32 columnCount = 1, int32 rowCount = 1);
+	inline	GroupBuilder		AddGroup(BGroupView* groupView,	int32 column,
+									int32 row, int32 columnCount = 1,
+									int32 rowCount = 1);
+	inline	GroupBuilder		AddGroup(BGroupLayout* groupLayout, 
+									int32 column, int32 row,
+									int32 columnCount = 1, int32 rowCount = 1);
+
+	inline	GridBuilder			AddGrid(float horizontalSpacing,
+									float verticalSpacing, int32 column,
+									int32 row, int32 columnCount = 1,
+									int32 rowCount = 1);
+	inline	GridBuilder			AddGrid(BGridLayout* gridLayout,
+									int32 column, int32 row,
+									int32 columnCount = 1, int32 rowCount = 1);
+	inline	GridBuilder			AddGrid(BGridView* gridView,
+									int32 column, int32 row,
+									int32 columnCount = 1, int32 rowCount = 1);
+
+	inline	SplitBuilder		AddSplit(enum orientation orientation,
+									float spacing, int32 column, int32 row,
+									int32 columnCount = 1, int32 rowCount = 1);
+	inline	SplitBuilder		AddSplit(BSplitView* splitView, int32 column,
+									int32 row, int32 columnCount = 1,
+									int32 rowCount = 1);
+
+	inline	ThisBuilder&		SetColumnWeight(int32 column, float weight);
+	inline	ThisBuilder&		SetRowWeight(int32 row, float weight);
+
+	inline	ThisBuilder&		SetInsets(float left, float top, float right,
+									float bottom);
+
+	inline						operator BGridLayout*();
+
+private:
+			BGridLayout*		fLayout;
+};
+
+
+template<typename ParentBuilder>
+class Split : public Base<ParentBuilder> {
+public:
+	typedef Split<ParentBuilder>	ThisBuilder;
+	typedef Group<ThisBuilder>		GroupBuilder;
+	typedef Grid<ThisBuilder>		GridBuilder;
+	typedef Split<ThisBuilder>		SplitBuilder;
+
+public:
+	inline						Split(enum orientation orientation
+										= B_HORIZONTAL,
+									float spacing = 0.0f);
+	inline						Split(BSplitView* view);
+
+	inline	BSplitView*			View() const;
+	inline	ThisBuilder&		GetView(BView** _view);
+	inline	ThisBuilder&		GetSplitView(BSplitView** _view);
+
+	inline	ThisBuilder&		Add(BView* view);
+	inline	ThisBuilder&		Add(BView* view, float weight);
+	inline	ThisBuilder&		Add(BLayoutItem* item);
+	inline	ThisBuilder&		Add(BLayoutItem* item, float weight);
+
+	inline	GroupBuilder		AddGroup(enum orientation orientation,
+									float spacing = 0.0f, float weight = 1.0f);
+	inline	GroupBuilder		AddGroup(BGroupView* groupView,
+									float weight = 1.0f);
+	inline	GroupBuilder		AddGroup(BGroupLayout* groupLayout,
+									float weight = 1.0f);
+
+	inline	GridBuilder			AddGrid(float horizontalSpacing = 0.0f,
+									float verticalSpacing = 0.0f,
+									float weight = 1.0f);
+	inline	GridBuilder			AddGrid(BGridView* gridView,
+									float weight = 1.0f);
+	inline	GridBuilder			AddGrid(BGridLayout* gridLayout,
+									float weight = 1.0f);
+
+	inline	SplitBuilder		AddSplit(enum orientation orientation,
+									float spacing = 0.0f, float weight = 1.0f);
+	inline	SplitBuilder		AddSplit(BSplitView* splitView,
+									float weight = 1.0f);
+
+	inline	ThisBuilder&		SetCollapsible(bool collapsible);
+	inline	ThisBuilder&		SetCollapsible(int32 index, bool collapsible);
+	inline	ThisBuilder&		SetCollapsible(int32 first, int32 last,
+									bool collapsible);
+
+	inline	ThisBuilder&		SetInsets(float left, float top, float right,
+									float bottom);
+
+	inline						operator BSplitView*();
+
+private:
+			BSplitView*			fView;
+};

docs/user/interface/LayoutItem.dox

@@ -0,0 +1,312 @@
+/*!
+	\class BLayoutItem
+	\ingroup interface
+	\ingroup layout
+	\ingroup libbe
+
+	\brief Abstract class representing things that are positionable and
+		resizable by objects of the BLayout class.
+
+	The BLayoutItem class provides an interface that is meant to be used almost
+	exclusively by objects of the BLayout class. Despite this, there are some
+	methods that are provided for other users of the class.
+
+	\warning This class is not yet finalized, if you use it in your software
+	assume that it will break some time in the future.
+*/
+
+
+/*!
+	\fn BLayoutItem::BLayoutItem(BMessage* archive)
+	\brief Archive constructor.
+
+	Creates a Bunarchiver for \a archive and calls its Finish() method.
+*/
+
+
+/*!
+	\fn BLayout* BLayoutItem::Layout() const
+	\brief Returns the BLayout this BLayoutItem resides in.
+*/
+
+
+/*!
+	\name Reporting size and alignment constraints to a BLayout
+	@{
+*/
+
+/*!
+	\fn BSize BLayoutItem::MinSize() = 0
+	\brief Returns the minimum desirable size for this item.
+*/
+
+
+/*!
+	\fn BSize BLayoutItem::MaxSize() = 0
+	\brief Returns the maximum desirable size for this item.
+*/
+
+
+/*!
+	\fn BSize BLayoutItem::PreferredSize() = 0
+	\brief Returns the preferred size for this item.
+*/
+
+
+/*!
+	\fn BAlignment BLayoutItem::Alignment() = 0
+	\brief Returns the requested alignment for this item.
+
+	The value returned from this method is used in BLayoutItem::AlignInFrame(),
+	which BLayouts use to position and resize items. In a vertical BGroupLayout,
+	for example, although each item recieves the same horizontal area, each item
+	can use that area differently, aligning to the left, right or center for
+	example.
+*/
+
+
+/*!
+	\fn bool BLayoutItem::HasHeightForWidth()
+	\brief Returns whether or not this BLayoutItem's height constraints are
+		dependent on its width.
+	
+	\note By default, this method returns \c false.
+*/
+
+
+/*!
+	\fn void BLayoutItem::GetHeightForWidth(float width, float* min,
+		float* max, float* preferred)
+	\brief Get this BLayoutItem's height constraints for a given \a width.
+
+	If a BLayoutItem does not have height for width constraints
+	(HasHeightForWidth() returns \c false) it does not need to implement this
+	method.
+
+	\note It is prudent to compare \a min, \a max, \a preferred to NULL before
+	dereferencing them.
+*/
+
+
+//@}
+
+
+/*!
+	\name Overriding size constraints and alignment.
+
+	Although the explicit constraints placed on an item are not enforced by the
+	BLayoutItem class, all Haiku BLayoutItem subclasses will use the
+	BLayoutUtils::ComposeSize() or BLayoutUtils::ComposeAlignment() functions
+	in when reporting these constraints. It is recommended that all subclasses
+	do this as well, the BAbstractLayoutItem class provides any easy way to
+	include this behaviour in your class.
+
+	@{
+*/
+
+
+/*!
+	\fn void BLayoutItem::SetExplicitMinSize(BSize size) = 0
+	\brief Set this item's explicit min size, to be used in MinSize().
+*/
+
+
+/*!
+	\fn void BLayoutItem::SetExplicitMaxSize(BSize size) = 0
+	\brief Set this item's explicit max size, to be used in MaxSize().
+*/
+
+
+/*!
+	\fn void BLayoutItem::SetExplicitPreferredSize(BSize size) = 0
+	\brief Set this item's explicit preferred size, to be used in
+		PreferredSize().
+*/
+
+
+/*!
+	\fn void BLayoutItem::SetExplicitAlignment(BAlignment alignment) = 0
+	\brief Set this item's explicit alignment, to be used in Alignment().
+*/
+
+
+//@}
+
+
+/*!
+	\name Getting and setting the visiblity of a BLayoutItem.
+
+	These methods take into account only the local visibility of this
+	item, not the visibility of its ancestors. \n
+
+	@{
+*/
+
+
+/*!
+	\fn bool BLayoutItem::IsVisible() = 0
+	\brief Return the current local visibility of this item. If an item is not
+		visible, it will not be given space by the BLayout it resides in.
+
+	A simple implementation would return the last thing passed to SetVisible().
+	A more complex implementation may deal with a BView that could
+	be hidden in any number of ways.
+*/
+
+
+/*!
+	\fn void BLayoutItem::SetVisible(bool visible) = 0
+	\brief Set the local visibility of this item.
+*/
+
+
+//@}
+
+
+/*!
+	\name Getting and setting the current on-screen positioning of \
+		a BLayoutItem.
+
+	@{
+*/
+
+
+/*!
+	\fn void BLayoutItem::AlignInFrame(BRect frame)
+	\brief Position this BLayoutItem within \a frame, given the value returned
+		by Alignment(), and the size constraints for this item.
+*/
+
+
+/*!
+	\fn BRect BLayoutItem::Frame() = 0
+	\brief Return the bounding frame of this item.
+
+	The returned BRect is in the coordinate system of the target view of the 
+	BLayout this item belongs to.
+*/
+
+
+/*!
+	\fn void BLayoutItem::SetFrame(BRect frame) = 0
+	\brief Set the bounding frame of this item.
+
+	\a frame is in the coordinate system of the target view of the 
+	BLayout this item belongs to.
+*/
+
+
+//@}
+
+
+/*!
+	\fn BView* BLayoutItem::View()
+	\brief Return the BView this item is representing, or NULL if it does not
+		represent any view.
+
+	When a BLayoutItem is added to a BLayout, this method is called, and the
+	returned BView will be added to the BLayout's target view.
+*/
+
+
+/*!
+	\name Layout events and requests.
+
+	\brief These methods represent events or requests originating from a
+	BLayout. In some implementations they may be handled directly by this
+	BLayoutItem, but many implementations will forward these events to
+	another object.
+
+	@{
+*/
+
+
+/*!
+	\fn void BLayoutItem::InvalidateLayout(bool children = false)
+	\brief Invalidate the layout of this item, or the object it represents.
+
+	If \a children is \c true, then you should also invalidate any child
+	objects.
+*/
+
+
+/*!
+	\fn void BLayoutItem::Relayout(bool immediate = false)
+	\brief Relayout any children or onscreen data this item contains. Often
+		this request is forwarded to another object.
+*/
+
+
+//@}
+
+
+/*!
+	\name Utility methods for BLayout subclasses
+	\brief Utility methods for the BLayout class to attach and retrieve
+		arbitrary data for a BLayoutItem.
+
+	@{
+*/
+
+
+/*!
+	\fn void* BLayoutItem::LayoutData() const
+	\brief Retrieve arbitrary data attached to this BLayoutItem.
+
+	\note This method should only be called by a BLayout subclass.
+*/
+
+
+/*!
+	\fn void BLayoutItem::SetLayoutData(void* data)
+	\brief Attach arbitrary data to this BLayoutItem.
+
+	\note This method should only be called by a BLayout subclass.
+*/
+
+
+//@}
+
+
+/*! \name Hook methods
+
+	@{
+*/
+
+
+/*!
+	\fn void BLayoutItem::AttachedToLayout()
+	\brief Hook called when this object is attached to a BLayout (via
+		BLayout::AddItem())
+
+	\note You can find the BLayout you've been attached to with the Layout()
+		method.
+*/
+
+
+/*!
+	\fn void BLayoutItem::DetachedFromLayout(BLayout* layout)
+	\brief Hook called when this object is attached to a BLayout (via
+		BLayout::RemoveItem())
+	\param layout The BLayout you were previously attached to.
+
+	\warning You should not use this hook to reattach \c this to \a BLayout,
+		doing so will cause undefined behaviour (probably a crash).
+*/
+
+
+/*!
+	\fn void BLayoutItem::AncestorVisibilityChanged(bool shown)
+	\brief Hook called when this BLayoutItem's ancestors change visibility,
+		effectively hiding or showing this item.
+
+	Implementations of this method should alter the onscreen visibility of this
+	item. I.E. if \a shown is \c false, nothing should be drawn to represent
+	this item.
+
+	\note This method should not effect the value returned by this object's
+		IsVisible() method.
+*/
+
+
+//@}

docs/user/interface/TwoDimensionalLayout.dox

@@ -0,0 +1,153 @@
+/*!
+	\class BTwoDimensionalLayout
+	\ingroup interface
+	\ingroup layout
+	\ingroup libbe
+
+	\brief Abstract BLayout subclass arranging items within rows and columns.
+
+	This class manages all the tricky work of actually positioning/resizing
+	items, as well as calculating size constraints and providing extra features,
+	such as spacing/insets and alignment of multiple BTwoDimensionalLayouts.
+	Derived classes need only implement a few hook methods to get a working
+	layout.
+
+	\warning This class is not yet finalized, if you use it in your software
+	assume that it will break some time in the future.
+*/
+
+
+/*!
+	\struct BTwoDimensionalLayout::ColumnRowConstraints
+	\brief Used by BTwoDimensionalLayout derived classes to communicate the
+		size constraints for a given column or row to the 
+		BTwoDimensionalLayout class.
+*/
+
+
+/*!
+	\struct BTwoDimensionalLayout::Dimensions
+	\brief Used by BTwoDimensionalLayout derived classes to communicate the
+		positioning and size of a BLayoutItem, in terms of columns and rows to
+		the BTwoDimensionalLayout class.
+*/
+
+
+/*!
+	\fn void BTwoDimensionalLayout::AlignLayoutWith(
+		BTwoDimensionalLayout* other, enum orientation)
+	\brief Align the BLayoutItems in two BTwoDimensionalLayouts with each other
+		within a certain orientation.
+
+	When two (or more) BTwoDimensionalLayouts are aligned within a certain
+	orientation, then the BLayoutItems within those BTwoDimensionalLayouts will
+	have identical widths or heights (depending on how the
+	BTwoDimensionalLayouts are aligned).
+
+	If you align two BGroupLayouts horizontally, for example, then the
+	BLayoutItems at index 0 in both BGroupLayouts will be given the same
+	horizontal area. The same is true for the BLayoutItems at index 1, 2, etc..
+	Not all BTwoDimensionalLayouts have to have an item at each index for the
+	alignment to proceed.
+
+	\param other The BTwoDimensionalLayout to be aligned with.
+	\param orientation The orientation on which to be aligned.
+*/
+
+
+/*!
+	\fn void BTwoDimensionalLayout::SetInsets(float left, float top,
+		float right, float bottom)
+	\brief Set the insets for this BTwoDimensionalLayout (in pixels).
+
+	Set the spacing around the edges of this BTwoDimensionalLayout. If you
+	pass B_USE_DEFAULT_SPACING for a certain parameter, that parameter will
+	be replaced with the value returned by BControlLook::DefaultItemSpacing().
+
+	\see BTwoDimensionalLayout::GetInsets();
+*/
+
+
+/*!
+	\fn void BTwoDimensionalLayout::GetInsets(float* left, float* top,
+		float* right, float* bottom) const
+	\brief Get the insets for this BTwoDimensionalLayout (in pixels).
+
+	Passing NULL for any paramater is not an error, such parameters will
+	be ignored.
+
+	\see BTwoDimensionalLayout::SetInsets();
+*/
+
+
+/*!
+	\name BTwoDimensionalLayout Hook methods
+
+	These methods are called automatically as needed during layout, and
+	provide the BTwoDimensionalLayout class with the necessary information
+	to properly layout the BLayoutItems in this BTwoDimensionalLayout.
+
+	@{
+*/
+
+
+/*!
+	\fn void BTwoDimensionalLayout::PrepareItems(enum orientation)
+	\brief Prepare the BLayoutItems in this BTwoDimensionalLayout subclass
+		for layout within a certain orientation.
+
+	This is a good place to update cache information that will be used in
+	other hook methods, for example.
+*/
+
+
+/*!
+	\fn bool BTwoDimensionalLayout::HasMultiColumnItems()
+	\brief Tests whether or not this BTwoDimensionalLayout contains any
+		BLayoutItems spanning more than one column.
+
+	The BTwoDimensionalLayout implementation returns false.
+*/
+
+
+/*!
+	\fn bool BTwoDimensionalLayout::HasMultiRowItems()
+	\brief Tests whether or not this BTwoDimensionalLayout contains any
+		BLayoutItems spanning more than one row.
+
+	The BTwoDimensionalLayout implementation returns false.
+*/
+
+
+/*!
+	\fn int32 BTwoDimensionalLayout::InternalCountColumns()
+	\brief Return the number of columns in this BTwoDimensionalLayout.
+*/
+
+
+/*!
+	\fn int32 BTwoDimensionalLayout::InternalCountRows()
+	\brief Return the number of rows in this BTwoDimensionalLayout.
+*/
+
+
+/*!
+	\fn void BTwoDimensionalLayout::GetColumnRowConstraints(enum orientation,
+		int32 index, ColumnRowConstraints* constraints)
+	\brief Fill in the ColumnRowConstraints for a certain column or row in
+		this BTwoDimensionalLayout.
+
+	This method is used to communicate the size constraints and weight for
+	a given row/column in this BTwoDimensionalLayout.
+*/
+
+
+/*!
+	\fn void BTwoDimensionalLayout::GetItemDimensions(BLayoutItem* item,
+		Dimensions* dimensions)
+	\brief Tell the base class what column and row a BLayoutItem is in, as
+		well as how many columns and rows it covers.
+*/
+
+
+//@}

docs/user/interface/_interface_intro.dox

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2010, Haiku, Inc. All Rights Reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Documentation by:
+ *		Alex Wilson <[email protected]>
+ */
+
+
+/*!
+	\page interface_intro Introduction to the Interface Kit.
+  
+	The Interface Kit holds all the classes you'll need to develop a GUI.
+	Building on the messaging facilities provided by the Application Kit,
+	the Inteface Kit can be used to create a responsive and attractive graphical
+	user interface.
+
+ 	The most important class in the Interface Kit is the BView class, which
+	handles drawing and user interaction. Pointer and keyboard events are
+	processed in this class. 
+
+	Another important class is the BWindow class, which holds BViews and makes
+	them visibile to the user. The BWindow class also handles BView focusing
+	and BMessage dispatching, among other things.
+
+	A new addition Haiku has added over the BeOS API is the Layout API, which
+	is based around the BLayoutItem and BLayout classes. These classes will
+	take care of making sure all your GUI widgets end up where you want them,
+	with enough space to be useful. You can start learning the Layout API 
+	by reading the \link layout_intro introduction \endlink.
+*/

docs/user/interface/_layout_intro.dox

@@ -0,0 +1,161 @@
+/*
+ * Copyright 2010, Haiku, Inc. All Rights Reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Documentation by:
+ *		Alex Wilson <[email protected]>
+ */
+
+
+/*!
+	\page layout_intro Introducing the Layout API.
+
+	Haiku's Layout API is centered around the BLayoutItem and BLayout classes.
+	The BLayoutItem class represents thing that can be managed by a BLayout,
+	which is itself a BLayoutItem. Before we go any further, it is a good idea
+	to familiarize yourself with the different BLayouts available in Haiku:
+		\li BGroupLayout
+		\li BGridLayout
+		\li BCardLayout
+		\li BSplitView
+
+	You'll notice that BSplitView is not actually a BLayout, but a BView. The
+	BSplitView class uses a custom BLayout behind the scenes, but because it
+	must also be able to draw, a BView is required. Other BLayouts have
+	BViews that can be used for convenience.
+		\li BGroupLayout : BGroupView
+		\li BGridLayout : BGridView
+		\li BCardLayout : BTabView (also provides on-screen tabs)
+
+	Although it is not necessary to use these classes to make use of the
+	coresponding layouts, it does make things easier.
+
+	Once you have an understanding of what each BLayout does, you can start
+	designing an interface with them. Let's consider a very simple window,
+	with a single item in the center. For this, any of the layouts mentioned
+	above would work, but we'll use a BGroupLayout, because it suits this
+	purpose the best.
+
+	So, let's review the BGroupLayout constructor:
+
+\code
+BGroupLayout(enum orientation orientation, float spacing
+		= B_USE_DEFAULT_SPACING)
+\endcode
+
+	Because we only have one item in this layout, \c orientation and \c spacing
+	become irrelevant. Let's choose B_VERTICAL for \c orientation, and leave
+	\c spacing at its default.
+
+\code
+BGroupLayout* group = new BGroupLayout(B_VERTICAL);
+BWindow* window = MakeWindow();
+window->SetLayout(group);
+\endcode
+
+	Before we can add anything to our layout, we must attach it to something,
+	and here we've used the BWindow::SetLayout() method to accomplish that.
+	By doing this, \c window takes ownership of \c group, so there is no need
+	to manually  <tt> delete group </tt> when we're done with it.
+
+	Now that we've got our BGroupLayout in place, we can start adding things
+	to it, let's add a BStringView.
+
+\code
+group->AddView(MakeStringView("Haiku rocks!"));
+\endcode
+
+	That does it! Now we've got a BWindow with a horizontal BGroupLayout holding
+	a single BView. However, if we want to ensure that our BStringView is always
+	centered in the window, we should give it an explict BAlignment. So that
+	last line becomes:
+
+\code
+BLayoutItem* stringView = group->AddView(MakeStringView("Haiku rocks!"));
+stringView->SetExplicitAlignment(BAlignment(B_ALIGN_HORIZONTAL_CENTER,
+		B_ALIGN_VERTICAL_CENTER);
+\endcode
+
+	Now our BStringView will always be right in the middle of the space
+	alloted to it, which at the moment is the whole of \c window.
+
+	Now let's take things one step further, and add a BMenuBar into the mix.
+
+\code
+group->AddView(0, MakeMenuBar());
+group->SetInsets(0, 0, 0, 0);
+\endcode
+
+	Because we want our BMenuBar to appear at the very top of the window, we
+	have to insert it at index \c 0, above the BStringView we added earlier.
+	We also use BTwoDimensionalLayout::SetInsets() to make sure that our
+	BMenuBar is flush to the edges of \c window. We also want a bit of
+	space between our BMenuBar and our BStringView, but \c group's spacing has
+	already been set by the BGroupLayout constructor, so we don't need to do
+	that.
+ 
+	Now that we've put our BGroupLayout to good use, we can rest easy, assured
+	that GUI will always look nice, no matter what font is used, or how big or
+	little \c window is stretched. Of course, very few interfaces are as simple
+	as this one.
+
+	Luckily, the layout classes can deal with complex layouts. Suppose, for
+	example, that we wanted to add a grid of BButtons under our BStringView.
+	We could use a BGridLayout for this. Let's review the BGridLayout
+	constructor:
+
+\code
+BGridLayout(float horizontal = B_USE_DEFAULT_SPACING,
+	float vertical = B_USE_DEFAULT_SPACING);
+\endcode
+
+	Because we want a bit of breathing room between our buttons, we'll leave 
+	vertical and horizontal spacing as is.
+
+\code
+BGridLayout* grid = new BGridLayout();
+group->AddItem(grid);
+\endcode
+
+	You'll notice that we've added \c grid directly to \c group. This means that
+	any BViews we add to \c grid will become children of \c window, but will be
+	positioned by \c grid.
+
+\code
+grid->AddView(MakeSmallButton(), 0, 0);
+grid->AddView(MakeSmallButton(), 1, 0);
+grid->AddView(MakeBigButton(), 0, 1, 2, 1);
+grid->AddView(MakeSmallButton(), 1, 2);
+\endcode
+
+	Now we've got a nice grid of BButtons, let's go over it quickly:
+		\li \c grid has two columns and three rows.
+		\li The cells (0, 0), (1, 0), and (1, 2) hold small buttons
+		\li The cells (0, 1) and (1, 1) hold a single button that spans both
+			cells.
+		\li The cell (0, 2) is empty.
+
+	How easy was that? Very easy!
+
+	One of the features you'll find incredibly handy in the layout API is the
+	builders in LayoutBuilder.h. Here's how our whole layout would look if it
+	were done with these builders:
+
+\code
+BLayoutBuilder::Group<>(window, B_VERTICAL)
+	.SetInsets(0, 0, 0, 0)
+	.Add(MakeMenuBar())
+	.Add(MakeStringView("Haiku rocks!"))
+	.AddGrid()
+		.Add(MakeSmallButton(), 0, 0)
+		.Add(MakeSmallButton(), 1, 0)
+		.Add(MakeBigButton(), 0, 1, 2, 1)
+		.Add(MakeSmallButton(), 1, 2);
+\endcode
+
+	This is only one way that you could build this layout, but it is probably
+	the most succinct. Functionally, this is equivalent to all the previous
+	code in this introduction.
+
+*/
+

docs/user/interface/layout_tips.dox

@@ -0,0 +1,36 @@
+/*!
+	\page layout_tips
+
+	\section layout_window_tips BWindow Tips
+
+	\li You can use the BLayoutBuilder classes to build a layout directly into
+		a BWindow.
+	\li Passing the B_AUTO_UPDATE_SIZE_LIMITS flag to a BWindow with a BLayout
+		will make sure that window is always big enough to accomadate everything
+		in it.
+
+	\section layout_view_tips BView Tips
+
+	\li When the main purpose of a BView is to hold a BLayout, consider nesting
+		the BLayout directly (i.e. without a BView)
+
+	\li When the main purpose of a BView is to hold another BView which has
+		children added to it, consider adding directly to the first BView.
+
+	\li When the main purpose of a BView is to hold a BLayout, but you also wish
+		to have a view color set for that area, considering using one of the
+		layout-related convenience classes (eg. BGroupView for BGroupLayout).
+
+	\li When the main purpose of a BView is to hold a BLayout, but it must be
+		populated before being attached to another BView or a BWindow,
+		consider using one of the layout-related convenience classes (eg.
+		BGroupView for BGroupLayout).
+
+
+	\section layout_layout_tips BLayout Tips
+
+	\li It is generally better to add BViews and BLayoutItems directly to the
+		BLayout subclass attached to a BView, rather than the BView itself. This
+		way, you can make full use of the specific features the subclass you're
+		using provides.
+*/