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
This commit is contained in:
Alex Wilson
@@ -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.
|
||||
*/
|
||||
|
||||
|
||||
//@}
|
||||
@@ -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.
|
||||
*/
|
||||
@@ -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.
|
||||
*/
|
||||
@@ -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.
|
||||
*/
|
||||
|
||||
|
||||
//@}
|
||||
|
||||
@@ -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.
|
||||
*/
|
||||
|
||||
//!@}
|
||||
@@ -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;
|
||||
};
|
||||
@@ -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.
|
||||
*/
|
||||
|
||||
|
||||
//@}
|
||||
@@ -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.
|
||||
*/
|
||||
|
||||
|
||||
//@}
|
||||
@@ -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.
|
||||
*/
|
||||
@@ -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.
|
||||
|
||||
*/
|
||||
|
||||
@@ -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.
|
||||
*/
|
||||
Reference in New Issue
Block a user