haiku/docs/user/interface/SpaceLayoutItem.dox

/*
 * Copyright 2020 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Niels Sascha Reedijk, niels.reedijk@gmail.com
 *
 * Corresponds to:
 *		headers/os/interface/SpaceLayoutItem.h	hrev43514
 *		src/kits/interface/SpaceLayoutItem.cpp	hrev44346
 */


/*!
	\file SpaceLayoutItem.h
	\ingroup layout
	\brief Provides the BSpaceLayoutItem class.

	\since Haiku R1
*/


/*!
	\class BSpaceLayoutItem
	\ingroup layout
	\ingroup libbe
	\brief An empty layout item that expands into empty space based on its size
		configuration.

	This class is a specialized layout item, that is used to distribute space
	within one of the layouts. The layout item can be manually configured, but
	there are also two default varieties.

	The first variety is the \b glue variety. Glue is an element that expands
	to the maximum space that is available. Let's say, you have a horizontal
	BGroupLayout. You want a button on the left, and a button on the right,
	with empty space in the middle. The middle element can be a glue element.
	The glue will push the right button all the way to the end of the available
	space. If the host view gets larger, the glue will expand. You can use the
	static method BSpaceLayoutItem::CreateGlue() to easily create a glue
	element.

	Another variety is the \b strut. A is a layout item with no minimum size,
	and a maximum size. This means that the item might be smaller than the
	maximum size, but it will never be larger than the maximum size. You can
	use the static methods BSpaceLayoutItem::CreateVerticalStrut() and
	BSpaceLayoutItem::CreateHorizontalStrut() to create a strut item.

	The default constructor allows you to create a layout item with custom
	minimum sizes, maximum sizes, preferred sizes and alignments.

	\see Where applicable, the layout builder classes have convenience methods
		to add glue or struts. See
		BLayoutBuilder::Group<ParentBuilder>::AddGlue() or
		BLayoutBuilder::Group<ParentBuilder>::AddStrut().

	\since Haiku R1
*/


/*!
	\fn BSpaceLayoutItem::BSpaceLayoutItem(BSize minSize, BSize maxSize,
		BSize preferredSize, BAlignment alignment)
	\brief Create a space layout item with specific properties.

	See the CreateGlue(), CreateVerticalStrut() and CreateHorizontalStruct
	static methods to create common space items.

	\param minSize The minimum size for this item.
	\param maxSize The maximum size for this item.
	\param preferredSize The preferred size for this item.
	\param alignment The alignment of this item.

	\since Haiku R1
*/


/*!
	\fn BSpaceLayoutItem::BSpaceLayoutItem(BMessage *archive)
	\brief Constructs a BSpaceLayoutItem from an \a archive message.

	This method is usually not called directly, if you want to build a
	space layout item from an archived message you should call Instantiate()
	instead because it can handle errors properly.

	\param archive The \ref BMessage that contains the space layout item.

	\since Haiku R1
*/


/*!
	\fn virtual BSpaceLayoutItem::~BSpaceLayoutItem()
	\brief Destructor.

	\since Haiku R1
*/


/*!
	\fn virtual BSize BSpaceLayoutItem::MinSize()
	\copydoc BLayoutItem::MinSize()
*/


/*!
	\fn virtual BSize BSpaceLayoutItem::MaxSize()
	\copydoc BLayoutItem::MaxSize()
*/


/*!
	\fn virtual BSize BSpaceLayoutItem::PreferredSize()
	\copydoc BLayoutItem::PreferredSize()
*/


/*!
	\fn virtual BAlignment BSpaceLayoutItem::Alignment()
	\copydoc BLayoutItem::Alignment()
*/


/*!
	\fn virtual void BSpaceLayoutItem::SetExplicitMinSize(BSize size)
	\copydoc BLayoutItem::SetExplicitMinSize()
*/


/*!
	\fn virtual void BSpaceLayoutItem::SetExplicitMaxSize(BSize size)
	\copydoc BLayoutItem::SetExplicitMaxSize()
*/


/*!
	\fn virtual void BSpaceLayoutItem::SetExplicitPreferredSize(
		BSize size)
	\copydoc BLayoutItem::SetExplicitPreferredSize()
*/


/*!
	\fn virtual void BSpaceLayoutItem::SetExplicitAlignment(
		BAlignment alignment)
	\copydoc BLayoutItem::SetExplicitAlignment()
*/


/*!
	\fn virtual virtual bool BSpaceLayoutItem::IsVisible()
	\brief Return the current local visibility of this item.

	The visibility is set explicitly through SetVisible(). By default, the
	layout item is visible.

	\since Haiku R1
*/


/*!
	\fn virtual void BSpaceLayoutItem::SetVisible(bool visible)
	\brief Set the visibility of this space layout item.

	\param visible The desired visibility of the layout item.

	\since Haiku R1
*/


/*!
	\fn virtual BRect BSpaceLayoutItem::Frame()
	\copydoc BLayoutItem::Frame()
*/


/*!
	\fn virtual void BSpaceLayoutItem::SetFrame(BRect frame)
	\copydoc BLayoutItem::SetFrame()
*/


/*!
	\fn static BSpaceLayoutItem* BSpaceLayoutItem::CreateGlue()
	\brief Create a layout item that acts like glue.

	This type of space layout item has no minimum size, and expands to the
	maximum available space in all directions.

	\return Creates a new BSpaceLayoutItem and returns ownership to the caller.

	\since Haiku R1
*/


/*!
	\fn static BSpaceLayoutItem* BSpaceLayoutItem::CreateHorizontalStrut(
		float width)
	\brief Create a layout item that horizontally expands to a maximum
		\a width.

	The item has no minimum size, meaning that if the total available width is
	smaller than the maximum \a width, the strut will use the available space.

	\param width The maximum width.

	\return Creates a new BSpaceLayoutItem and returns ownership to the caller.

	\since Haiku R1
*/


/*!
	\fn static static BSpaceLayoutItem* BSpaceLayoutItem::CreateVerticalStrut(float height)
	\brief Create a layout item that vertically expands to a maximum
		\a height.

	The item has no minimum size, meaning that if the total available height is
	smaller than the maximum \a width, the strut will use the available space.

	\param height The maximum height.

	\return Creates a new BSpaceLayoutItem and returns ownership to the caller.

	\since Haiku R1
*/


/*!
	\fn static BArchivable* BSpaceLayoutItem::Instantiate(BMessage *from)
	\brief Instantiate the item from the message \a from.

	\since Haiku R1
*/