haiku/docs/user/interface/LayoutBuilder.Group.dox

/*
 * Copyright 2011, 2020 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		John Scipione, jscipione@gmail.com
 *		Ingo Weinhold, bonefish@cs.tu-berlin.de
 *		Niels Sascha Reedijk, niels.reedijk@gmail.com
 *
 * Corresponds to:
 *		headers/os/interface/LayoutBuilder.h	 rev 49977
 */


/*!
	\class BLayoutBuilder::Group<>
	\ingroup layout
	\ingroup libbe
	\brief BLayoutBuilder::Base subclass for building BGroupLayouts.

	\since Haiku R1
*/


/*!
	\typedef BLayoutBuilder::Group<ParentBuilder>::ThisBuilder
	\brief Shorthand representing the type of \c this.

	\since Haiku R1
*/


/*!
	\typedef BLayoutBuilder::Group<ParentBuilder>::GroupBuilder
	\brief Shorthand for builders returned by this builder's AddGroup() methods.

	\since Haiku R1
*/


/*!
	\typedef BLayoutBuilder::Group<ParentBuilder>::GridBuilder
	\brief Shorthand for builders returned by this builder's AddGrid() methods.

	\since Haiku R1
*/


/*!
	\typedef BLayoutBuilder::Group<ParentBuilder>::SplitBuilder
	\brief Shorthand for builders returned by this builder's AddSplit() methods.

	\since Haiku R1
*/


/*!
	\typedef BLayoutBuilder::Group<ThisBuilder>::CardBuilder
	\brief Shorthand for builders returned by this builder's AddCards()
		methods.

	\since Haiku R1
*/


/*!
	\name Constructors
*/


//! @{


/*!
	\fn BLayoutBuilder::Group<ParentBuilder>::Group(BWindow *window,
		orientation 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
	      \c B_PANEL_BACKGROUND_COLOR.
	\param window The BWindow* to attach the newly created BGroupLayout to.
	\param orientation The orientation for the new BGroupLayout.
	\param spacing The spacing for the new BGroupLayout.

	\since Haiku R1
*/


/*!
	\fn BLayoutBuilder::Group<ParentBuilder>::Group(BView* view,
		orientation orientation, float spacing)
	\brief Creates a builder targeting an existing \a view.

	\param view The BView* to attach the newly created BGroupLayout to.
	\param orientation The orientation for the new BGroupLayout.
	\param spacing The spacing for the new BGroupLayout.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\fn BLayoutBuilder::Group<ParentBuilder>::Group(
		orientation 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.

	\since Haiku R1
*/


//! @}


/*!
	\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*)

	\since Haiku R1
*/


/*!
	\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)

	\since Haiku R1
*/


/*!
	\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*)

	\since Haiku R1
*/


/*!
	\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)

	\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::Group<ParentBuilder>::AddGroup(
		orientation orientation, float spacing, float weight)
	\brief Add a new viewless BGroupLayout as a child to the layout that this
		builder represents and return a GroupBuilder representing the new
		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 this group layout.

	\returns A GroupBuilder representing the newly created BGroupLayout.

	\since Haiku R1
*/


/*!
	\fn GroupBuilder BLayoutBuilder::Group<ParentBuilder>::AddGroup(BGroupView*
		groupView, float weight)
	\brief Add an existing BGroupView as a child to the layout that this
		builder represents and return a GroupBuilder representing the layout of
		the added \a groupView.

	\param groupView The BGroupView to be added.
	\param weight The weight for \a groupView in this group layout.

	\returns A GroupBuilder representing the layout of the \a groupView.

	\since Haiku R1
*/


/*!
	\fn GroupBuilder BLayoutBuilder::Group<ParentBuilder>::AddGroup(
		BGroupLayout* groupLayout, float weight)
	\brief Add an existing BGroupLayout as a child to the layout that this
		builder represents and return a GroupBuilder to the added layout.

	\param groupLayout The BGroupLayout to be added.
	\param weight The weight for \a groupLayout in this group layout.

	\returns A GroupBuilder representing the \a groupLayout.

	\since Haiku R1
*/


/*!
	\fn GridBuilder BLayoutBuilder::Group<ParentBuilder>::AddGrid(
		float horizontalSpacing, float verticalSpacing, float weight)
	\brief Add a new viewless BGridLayout as a child to the layout that this
		builder represents and return a GridBuilder representing the new
		layout.

	\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.

	\since Haiku R1
*/


/*!
	\fn GridBuilder BLayoutBuilder::Group<ParentBuilder>::AddGrid(
		BGridLayout* gridLayout, float weight)
	\brief Add an existing BGridLayout as a child to the layout that this
		builder represents and return a GridBuilder to the added layout.

	\param gridLayout The BGridLayout to be added.
	\param weight The weight for \a gridLayout in the BGroupLayout this builder
		represents.

	\returns A GridBuilder representing \a gridLayout.

	\since Haiku R1
*/


/*!
	\fn GridBuilder	BLayoutBuilder::Group<ParentBuilder>::AddGrid(
		BGridView* gridView, float weight)
	\brief Add an existing BGridView as a child to the layout this builder
		represents and return a GridBuilder representing the layout of the
		added \a gridView.

	\param gridView The BGridView to be added.
	\param weight The weight for \a gridView in this BGroupLayout.

	\returns A GridBuilder representing the layout of the \a gridView.

	\since Haiku R1
*/


/*!
	\fn SplitBuilder BLayoutBuilder::Group<ParentBuilder>::AddSplit(
		orientation orientation, float spacing, float weight)
	\brief Add a new BSplitView as a child to the layout that this builder
		represents and 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.

	\since Haiku R1
*/


/*!
	\fn SplitBuilder BLayoutBuilder::Group<ParentBuilder>::AddSplit(
		BSplitView* splitView, float weight = 1.0f)
	\brief Add an existing BSplitView as a child to the layout this builder
		represents and return a SplitBuilder representing the layout of the
		added \a splitView.

	\param splitView The BSplitView to be added.
	\param weight The weight of the BSplitView in the BGroupLayout this builder
		represents.

	\returns A SplitBuilder representing the \a splitView.

	\since Haiku R1
*/


/*!
	\fn CardBuilder BLayoutBuilder::Group<ParentBuilder>::AddCards(
		float weight)
	\brief Add a new viewless BCardLayout as a child to the layout that this
		builder represents and return a CardBuilder representing the new layout.

	\param weight The weight of this new layout within the current group layout.

	\returns A CardBuilder representing the new BCardLayout.

	\since Haiku R1
*/


/*!
	\fn CardBuilder BLayoutBuilder::Group<ParentBuilder>::AddCards(
		BCardLayout* cardLayout, float weight)
	\brief Add an existing BCardLayout as a child to the layout that this builder
		represents and return a CardBuilder representing the added layout.

	\param cardLayout The existing layout to add to the current group layout.
	\param weight The weight of this new layout within the current group
		layout.

	\returns A CardBuilder representing the \a cardLayout.

	\since Haiku R1
*/


/*!
	\fn CardBuilder BLayoutBuilder::Group<ParentBuilder>::AddCards(
		BCardView* cardView, float weight)
	\brief Add an existing BCardView as a child to the layout that this builder
		represents and return a CardBuilder representing the layout of the
		added BCardView.

	\param cardView The existing BCardView to add to the current group layout.
	\param weight The weight of this new layout within the current group layout.

	\returns A CardBuilder representing the layout of the \a cardView.

	\since Haiku R1
*/


//! @}


/*!
	\name Adding BSpaceLayoutItems

	Some convenience methods for adding special BSpaceLayoutItems.
*/


//! @{


/*!
	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::AddGlue(
		float weight)
	\brief Add a BSpaceLayoutItem created by BSpaceLayoutItem::CreateGlue()
		to the builder's layout.

	\param weight The weight of the BSpaceLayoutItem in the BGroupLayout this
		builder represents

	\since Haiku R1
*/


/*!
	\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).

	\since Haiku R1
*/


//!@}


/*!
	\name Insets
*/


//! @{


/*!
	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::SetInsets(
		float left, float top, float right, float bottom)
	\copydoc BTwoDimensionalLayout::SetInsets(float, float, float, float)
*/


/*!
	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::SetInsets(
		float horizontal, float vertical)
	\copydoc BTwoDimensionalLayout::SetInsets(float, float)
*/


/*!
	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::SetInsets(
		float insets)
	\copydoc BTwoDimensionalLayout::SetInsets(float)
*/


//! @}


/*!
	\name Explicit Sizes and Alignment
*/


//! @{


/*!
	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::SetExplicitMinSize(
		BSize size)
	\brief Set the explicit minimum size of the underlying layout.

	\since Haiku R1
*/


/*!
	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::SetExplicitMaxSize(
		BSize size)
	\brief Set the explicit maximum size of the underlying layout.

	\since Haiku R1
*/


/*!
	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::SetExplicitPreferredSize(
		BSize size)
	\brief Set the explicit preferred size of the underlying layout.

	\since Haiku R1
*/


/*!
	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::SetExplicitAlignment(
		BAlignment alignment)
	\brief Set the explicit alignment of the underlying layout.

	\since Haiku R1
*/


//! @}


/*!
	\name Accessors
*/


//! @{


/*!
	\fn BGroupLayout* BLayoutBuilder::Group<ParentBuilder>::Layout() const
	\brief Get a pointer to the layout this builder represents.

	\since Haiku R1
*/


/*!
	\fn BView* BLayoutBuilder::Group<ParentBuilder>::View() const
	\brief Get a pointer to the BView this builder's layout is attached to.

	\since Haiku R1
*/


/*!
	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::GetLayout(
		BGroupLayout** _layout)
	\brief Get the layout this builder represents.

	\param[out] _layout The layout this builder represents.

	\since Haiku R1
*/


/*!
	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::GetView(
		BView** _view)
	\brief Get a pointer to the BView this builder's layout is attached to.

	\param[out] _view The BView this builder's layout is attached to.

	\since Haiku R1
*/


/*!
	\fn BLayoutBuilder::Group<ParentBuilder>::operator BGroupLayout*()
	\brief Cast this builder into the layout object it represents.

	\since Haiku R1
*/


//!@}