From cc19e7c0ffc8b52c397d854c894193b3e69c022b Mon Sep 17 00:00:00 2001 From: Alex Wilson Date: Sat, 23 Oct 2010 02:33:08 +0000 Subject: [PATCH] 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 --- docs/user/Doxyfile | 8 + docs/user/book.dox | 6 + docs/user/interface/AbstractLayout.dox | 122 +++++ docs/user/interface/GridLayout.dox | 193 +++++++ docs/user/interface/GroupLayout.dox | 146 ++++++ docs/user/interface/Layout.dox | 525 +++++++++++++++++++ docs/user/interface/LayoutBuilder.Group.dox | 346 ++++++++++++ docs/user/interface/LayoutBuilder.dox | 224 ++++++++ docs/user/interface/LayoutItem.dox | 312 +++++++++++ docs/user/interface/TwoDimensionalLayout.dox | 153 ++++++ docs/user/interface/_interface_intro.dox | 31 ++ docs/user/interface/_layout_intro.dox | 161 ++++++ docs/user/interface/layout_tips.dox | 36 ++ 13 files changed, 2263 insertions(+) create mode 100644 docs/user/interface/AbstractLayout.dox create mode 100644 docs/user/interface/GridLayout.dox create mode 100644 docs/user/interface/GroupLayout.dox create mode 100644 docs/user/interface/Layout.dox create mode 100644 docs/user/interface/LayoutBuilder.Group.dox create mode 100644 docs/user/interface/LayoutBuilder.dox create mode 100644 docs/user/interface/LayoutItem.dox create mode 100644 docs/user/interface/TwoDimensionalLayout.dox create mode 100644 docs/user/interface/_interface_intro.dox create mode 100644 docs/user/interface/_layout_intro.dox create mode 100644 docs/user/interface/layout_tips.dox diff --git a/docs/user/Doxyfile b/docs/user/Doxyfile index cb54f5411d..a9698fdd92 100644 --- a/docs/user/Doxyfile +++ b/docs/user/Doxyfile @@ -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 \ diff --git a/docs/user/book.dox b/docs/user/book.dox index 35ac30e13a..cb23cc1697 100644 --- a/docs/user/book.dox +++ b/docs/user/book.dox @@ -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 */ diff --git a/docs/user/interface/AbstractLayout.dox b/docs/user/interface/AbstractLayout.dox new file mode 100644 index 0000000000..bf1629edfe --- /dev/null +++ b/docs/user/interface/AbstractLayout.dox @@ -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. +*/ + + +//@} diff --git a/docs/user/interface/GridLayout.dox b/docs/user/interface/GridLayout.dox new file mode 100644 index 0000000000..bea3595786 --- /dev/null +++ b/docs/user/interface/GridLayout.dox @@ -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. +*/ diff --git a/docs/user/interface/GroupLayout.dox b/docs/user/interface/GroupLayout.dox new file mode 100644 index 0000000000..4d283d8e96 --- /dev/null +++ b/docs/user/interface/GroupLayout.dox @@ -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. +*/ diff --git a/docs/user/interface/Layout.dox b/docs/user/interface/Layout.dox new file mode 100644 index 0000000000..a346ae2cc2 --- /dev/null +++ b/docs/user/interface/Layout.dox @@ -0,0 +1,525 @@ +/* + * Copyright 2010, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Alex Wilson + * 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 + LayoutArea().LeftTop() == B_ORIGIN . +*/ + + +/*! + \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. +*/ + + +//@} + diff --git a/docs/user/interface/LayoutBuilder.Group.dox b/docs/user/interface/LayoutBuilder.Group.dox new file mode 100644 index 0000000000..fec1bbea41 --- /dev/null +++ b/docs/user/interface/LayoutBuilder.Group.dox @@ -0,0 +1,346 @@ +/*! + \class BLayoutBuilder::Group<> + \ingroup interface + \ingroup layout + \brief BLayoutBuilder::Base subclass for building BGroupLayouts. +*/ + + +/*! + \typedef BLayoutBuilder::Group::GroupBuilder + \brief Shorthand for builders returned by this builder's AddGroup() methods. +*/ + + +/*! + \typedef BLayoutBuilder::Group::GridBuilder + \brief Shorthand for builders returned by this builder's AddGrid() methods. +*/ + + +/*! + \typedef BLayoutBuilder::Group::SplitBuilder + \brief Shorthand for builders returned by this builder's AddSplit() methods. +*/ + + +/*! + \typedef BLayoutBuilder::Group::ThisBuilder + \brief Shorthand representing the type of \c this. +*/ + + +/*! + \name Constructors + + @{ +*/ + + +/*! + \fn BLayoutBuilder::Group::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::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::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 BLayoutBuilder::Group::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::Layout() const + \brief Get the BGroupLayout this builder represents. +*/ + + +/*! + \fn BView* BLayoutBuilder::Group::View() const + \brief Get the BView this builder's BGroupLayout is attached to. +*/ + + +/*! + \fn ThisBuilder& BLayoutBuilder::Group::GetLayout( + BGroupLayout** _layout) + \brief Get the BGroupLayout this builder represents. + \param[out] _layout The BGroupLayout this builder represents. +*/ + + +/*! + \fn ThisBuilder& BLayoutBuilder::Group::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::operator BGroupLayout*() + \brief Cast this builder into the BGroupLayout it represents. +*/ + +//!@} diff --git a/docs/user/interface/LayoutBuilder.dox b/docs/user/interface/LayoutBuilder.dox new file mode 100644 index 0000000000..ae899bb9ab --- /dev/null +++ b/docs/user/interface/LayoutBuilder.dox @@ -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::SetParent(ParentBuilder* + parent) + Internal method for use by BLayoutBuilder::Base subclasses, this is + essential to the builder stack semantics +*/ + + +/*! + \fn ParentBuilder& BLayoutBuilder::Base::End() + \brief Returns this builder's parent. +*/ + + + +/* + + +template +class Grid : public Base { +public: + typedef Grid ThisBuilder; + typedef Group GroupBuilder; + typedef Grid GridBuilder; + typedef Split 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 +class Split : public Base { +public: + typedef Split ThisBuilder; + typedef Group GroupBuilder; + typedef Grid GridBuilder; + typedef Split 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; +}; diff --git a/docs/user/interface/LayoutItem.dox b/docs/user/interface/LayoutItem.dox new file mode 100644 index 0000000000..bab2552507 --- /dev/null +++ b/docs/user/interface/LayoutItem.dox @@ -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. +*/ + + +//@} diff --git a/docs/user/interface/TwoDimensionalLayout.dox b/docs/user/interface/TwoDimensionalLayout.dox new file mode 100644 index 0000000000..97b13798c9 --- /dev/null +++ b/docs/user/interface/TwoDimensionalLayout.dox @@ -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. +*/ + + +//@} diff --git a/docs/user/interface/_interface_intro.dox b/docs/user/interface/_interface_intro.dox new file mode 100644 index 0000000000..9133fd605b --- /dev/null +++ b/docs/user/interface/_interface_intro.dox @@ -0,0 +1,31 @@ +/* + * Copyright 2010, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Alex Wilson + */ + + +/*! + \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. +*/ diff --git a/docs/user/interface/_layout_intro.dox b/docs/user/interface/_layout_intro.dox new file mode 100644 index 0000000000..67dc7240ed --- /dev/null +++ b/docs/user/interface/_layout_intro.dox @@ -0,0 +1,161 @@ +/* + * Copyright 2010, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Alex Wilson + */ + + +/*! + \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 delete group 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. + +*/ + diff --git a/docs/user/interface/layout_tips.dox b/docs/user/interface/layout_tips.dox new file mode 100644 index 0000000000..891ca1abae --- /dev/null +++ b/docs/user/interface/layout_tips.dox @@ -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. +*/