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/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.
+*/