i2p/haiku-beta6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add initial documentation for Layout API, not everything is documented, and it's not perfect, but its time to commit this.

Browse Source 
git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@39055 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Alex Wilson
2010-10-23 02:33:08 +00:00
parent a46d62a268
commit cc19e7c0ff
13 changed files with 2263 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/Doxyfile
+8
View File
@@ -465,6 +465,7 @@ WARN_LOGFILE =
INPUT = . \
app \
drivers \
interface \
locale \
midi \
midi2 \
@@ -473,6 +474,13 @@ INPUT = . \
../../headers/os/drivers/fs_interface.h \
../../headers/os/drivers/USB3.h \
../../headers/os/drivers/USB_spec.h \
../../headers/os/interface/AbstractLayout.h \
../../headers/os/interface/GridLayout.h \
../../headers/os/interface/GroupLayout.h \
../../headers/os/interface/Layout.h \
../../headers/os/interface/LayoutBuilder.h \
../../headers/os/interface/LayoutItem.h \
../../headers/os/interface/TwoDimensionalLayout.h \
../../headers/os/locale \
../../headers/os/midi2 \
../../headers/os/support \
docs/user/book.dox
+6
View File
@@ -5,6 +5,7 @@
- \ref app | \link app_intro \em Introduction \endlink
- \ref drivers
- \ref interface | \link interface_intro \em Introduction \endlink
- \ref locale | \link locale_intro \em Introduction \endlink
- \ref midi1
- \ref midi2 | \link midi2_intro \em Introduction \endlink
@@ -21,6 +22,8 @@
/*!
\defgroup app Application Kit
\defgroup drivers Drivers
\defgroup interface Interface Kit
\brief API for displaying a graphical user interface.
\defgroup midi2 MIDI 2 Kit
\brief API for producing and consuming MIDI events.
\defgroup libmidi2 (libmidi2.so)
@@ -37,4 +40,7 @@
/*!
\defgroup support_globals Global functions in the support kit
\ingroup support
\defgroup layout Layout classes in the Interface Kit
\ingroup interface
*/
docs/user/interface/AbstractLayout.dox
+122
View File
@@ -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.
*/
//@}
docs/user/interface/GridLayout.dox
+193
View File
@@ -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.
*/
docs/user/interface/GroupLayout.dox
+146
View File
@@ -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.
*/
docs/user/interface/Layout.dox
+525
View File
@@ -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.
*/
//@}
docs/user/interface/LayoutBuilder.Group.dox
+346
View File
@@ -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.
*/
//!@}
docs/user/interface/LayoutBuilder.dox
+224
View File
@@ -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;
};
docs/user/interface/LayoutItem.dox
+312
View File
@@ -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.
*/
//@}
docs/user/interface/TwoDimensionalLayout.dox
+153
View File
@@ -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.
*/
//@}
docs/user/interface/_interface_intro.dox
+31
View File
@@ -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.
*/
docs/user/interface/_layout_intro.dox
+161
View File
@@ -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.
*/
docs/user/interface/layout_tips.dox
+36
View File
@@ -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.
*/