6758018a21
This is the final contribution to #15368 * Tried to share more documentation in the various BLayoutBuilder classes * Add missing GridView, GroupView, SpaceLayoutItem * Also added AbstractLayoutItem, but hide the actual documentation behind an `INTERNAL` conditional block. This block identifier can be used to document parts of the API, to then hide them during a regular Doxygen run. * Do some cleanup on other layout classes; add missing members, etc. * The actual generated BLayoutBuilder::* html is a mess. I should investigate this at a later time. Especially the copied members seem to mix type definitions with member documentation. It is odd. Not unlikely to be a Doxygen bug. * The general documentation for the layout system could use an overhaul as well, but this is for later. Change-Id: I6db9ef105b4ae6de0f1ebb917f86f8b1c0d4ea2e Reviewed-on: https://review.haiku-os.org/c/haiku/+/2491 Reviewed-by: waddlesplash <waddlesplash@gmail.com>
235 lines
5.8 KiB
Plaintext
235 lines
5.8 KiB
Plaintext
/*
|
|
* 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
|
|
*/
|