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

IK documentation update

Browse Source 
* Add \since directive to each method.
* Add documentation for BScrollBar and BScrollView classes.
* Title Case group titles.
* Some other minor documentation updates.
This commit is contained in:
John Scipione
2014-06-13 17:44:22 -04:00
parent 1f424632be
commit 47852bff02
43 changed files with 5320 additions and 1277 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/interface/Layout.dox
+153 -67
View File
@@ -28,8 +28,8 @@
\brief The BLayout class provides an interface, and some basic
implementation to manage the positioning and sizing of BLayoutItem s.
BLayouts can be attached to a BView, managing the BLayoutItem's and
BView's that reside in that view, or can be nested within another
BLayouts can be attached to a BView, managing the BLayoutItem's and
BView's 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
@@ -39,7 +39,7 @@
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 BLayout's target view.
BLayoutItem::View()) is added to the BLayout's target view.
\code
BView* topView = new BGroupView();
@@ -67,6 +67,8 @@ topLayout->AddItem(nestedLayoutWithView);
\warning This class is not yet finalized, if you use it in your software
assume that it will break some time in the future.
\since Haiku R1
*/
@@ -75,10 +77,12 @@ topLayout->AddItem(nestedLayoutWithView);
\brief Default constructor.
After this constructor has finished, this BLayout holds no
BLayoutItem's and does not have a target BView.
BLayoutItem's 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.
\since Haiku R1
*/
@@ -87,24 +91,28 @@ topLayout->AddItem(nestedLayoutWithView);
\brief Archive constructor.
\param archive The archive message.
\since Haiku R1
*/
/*!
\fn BLayout::~BLayout()
\brief Destructor, deletes all BLayoutItem's that this layout manages,
and detaches from this BLayout's owner view if there is one.
\brief Destructor, deletes all BLayoutItem's 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
Each BLayoutItem's BView (as returned by BLayoutItem::View()) is also
removed from their parent.
\note Because nested BLayout's are treated as BLayoutItem's,
\note Because nested BLayout's are treated as BLayoutItem's,
any layouts nested in this BLayout will be deleted.
\since Haiku R1
*/
/*!
\name BView targeting and attachment information.
\name BView Targeting and Attachment Information
*/
@@ -114,6 +122,8 @@ topLayout->AddItem(nestedLayoutWithView);
/*!
\fn BView* BLayout::Owner() const
\brief Returns the Owner of this layout, i.e. the view this layout manages.
\since Haiku R1
*/
@@ -121,9 +131,11 @@ topLayout->AddItem(nestedLayoutWithView);
\fn BView* BLayout::TargetView() const
\brief Returns the target view of this layout.
The target view of a layout becomes the parent of any BView's in this
layout, as well as the BView's returned by BLayoutItem::View() for
The target view of a layout becomes the parent of any BView's in this
layout, as well as the BView's returned by BLayoutItem::View() for
each BLayoutItem in this layout.
\since Haiku R1
*/
@@ -131,6 +143,8 @@ topLayout->AddItem(nestedLayoutWithView);
\fn BView* BLayout::View()
\brief Returns the same BView* as BLayout::Owner(), this method is
inherited from BLayoutItem.
\since Haiku R1
*/
@@ -138,7 +152,7 @@ topLayout->AddItem(nestedLayoutWithView);
/*!
\name Adding, removing, counting and accessing BLayout children
\name Adding, Removing, Counting and Accessing Children
*/
@@ -149,38 +163,44 @@ topLayout->AddItem(nestedLayoutWithView);
\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 BLayout's target view.
\a child is added to this BLayout's target view.
\returns The BLayoutItem created to represent \a child is, or \c NULL if
there was an error.
\param child The BView to be added to this BLayout.
\since Haiku R1
*/
/*!
\fn BLayoutItem* BLayout::AddView(int32 index, BView* child)
\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 BLayout's target view.
\a index to this layout. \a child is added to this BLayout's target view.
\since Haiku R1
*/
/*!
\fn bool BLayout::AddItem(BLayoutItem* item)
\brief Adds a BLayoutItem to this layout, and adds the BView it represents
to this BLayout's target view.
to this BLayout's target view.
\param item The BLayoutItem to be added.
\retval true success
\retval false failure
\return \c true if the item was added, \c false otherwise.
\since Haiku R1
*/
/*!
\fn bool BLayout::AddItem(int32 index, BLayoutItem* item)
\brief Adds \a item to this layout, and adds the BView \a item represents
to this BLayout's target view.
to this BLayout's target view.
\param item The BLayoutItem to be added.
\param index The index at which to add \c item.
@@ -189,27 +209,29 @@ topLayout->AddItem(nestedLayoutWithView);
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
\return \c true if the item was added, \c false otherwise.
\since Haiku R1
*/
/*!
\fn bool BLayout::RemoveView(BView* child)
\brief Removes and deletes all BLayoutItem representing a BView from
this layout.
this layout.
\param child The BView to be removed.
\retval true success
\retval false failure
\return \c true if the item was removed, \c false otherwise.
\since Haiku R1
*/
/*!
\fn bool BLayout::RemoveItem(BLayoutItem* item)
\brief Removes a BLayoutItem from this layout, and also removes the view
it represents from this BLayout's target view.
\brief Removes a BLayoutItem from this layout, and also removes the view
it represents from this BLayout's target view.
\param item The BLayoutItem to be removed
@@ -218,8 +240,9 @@ topLayout->AddItem(nestedLayoutWithView);
\warning \a item->View(), even when it is removed from the target view,
is not deleted. If you want it deleted, you must delete it yourself!
\retval true success
\retval false failure
\return \c true if the item was removed, \c false otherwise.
\since Haiku R1
*/
@@ -230,19 +253,25 @@ topLayout->AddItem(nestedLayoutWithView);
\see RemoveItem(BLayoutItem*)
\returns The BLayoutItem that was removed.
\since Haiku R1
*/
/*!
\fn BLayoutItem* BLayout::ItemAt(int32 index) const
\brief Get the BLayoutItem at \a index. Returns \c NULL if \a index is
out of bounds.
out of bounds.
\since Haiku R1
*/
/*!
\fn int32 BLayout::CountItems() const
\brief Get the number of BLayoutItem s in this layout.
\since Haiku R1
*/
@@ -253,6 +282,8 @@ topLayout->AddItem(nestedLayoutWithView);
\param item The BLayoutItem whose index you want.
\retval -1 \a item was not found in this BLayout.
\since Haiku R1
*/
@@ -263,6 +294,8 @@ topLayout->AddItem(nestedLayoutWithView);
\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().
\since Haiku R1
*/
@@ -270,9 +303,10 @@ topLayout->AddItem(nestedLayoutWithView);
/*!
\name Subclass helpers.
\brief These methods are meant to ease the development of BLayout
subclasses.
\name Subclass Helpers
These methods are meant to ease the development of BLayout
subclasses.
*/
@@ -285,9 +319,11 @@ topLayout->AddItem(nestedLayoutWithView);
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 BLayout's parent layout. If
this will reflect the visibility of this BLayout's parent layout. If
any layout is hidden (by BLayout::SetVisible()) between this layout and its
target BView's layout, then this method will return \c false.
target BView's layout, then this method will return \c false.
\since Haiku R1
*/
@@ -296,9 +332,11 @@ topLayout->AddItem(nestedLayoutWithView);
\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 BLayout's target
The return value is in the coordinate space of this BLayout's target
view. If this BLayout is attached directly to a BView, then
<tt> LayoutArea().LeftTop() == B_ORIGIN </tt>.
\since Haiku R1
*/
@@ -309,6 +347,8 @@ topLayout->AddItem(nestedLayoutWithView);
BLayout.
\param show \c true to show, \c false to hide.
\since Haiku R1
*/
@@ -316,7 +356,7 @@ topLayout->AddItem(nestedLayoutWithView);
/*!
\name Methods triggering or related to laying out this BLayout.
\name Methods Triggering or Related to Laying Out the BLayout
*/
@@ -330,24 +370,28 @@ topLayout->AddItem(nestedLayoutWithView);
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 BLayout&apos;s parent layout in the process of laying
request, nor is this BLayout's parent layout in the process of laying
out its items, then this BLayout will now layout its items.
\param immediate Whether or not to Relayout immediately or wait for pending
requests first.
requests first.
\since Haiku R1
*/
/*!
\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 DoLayout() method
of this BLayout and any BLayout s nested in this BLayout.
creates a new BLayoutContext and calls the DoLayout() method
of this BLayout and any BLayout's nested in this BLayout.
This 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).
\param force Force the LayoutItems.
\since Haiku R1
*/
@@ -355,6 +399,8 @@ topLayout->AddItem(nestedLayoutWithView);
\fn BLayoutContext* BLayout::LayoutContext() const
\brief Returns the BLayoutContext this BLayout is currently operating in,
or \c NULL.
\since Haiku R1
*/
@@ -362,7 +408,7 @@ topLayout->AddItem(nestedLayoutWithView);
/*!
\name Invalidation and state mutators and accessors.
\name Invalidation and State Mutators and Accessors
*/
@@ -373,6 +419,8 @@ topLayout->AddItem(nestedLayoutWithView);
\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.
\since Haiku R1
*/
@@ -382,7 +430,7 @@ topLayout->AddItem(nestedLayoutWithView);
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 BLayout&apos;s view)
(if there is one) and the BLayout this layout (or this BLayout's view)
resides in.
Although this method is virtual, you should not override it, override the
@@ -395,13 +443,18 @@ topLayout->AddItem(nestedLayoutWithView);
\sa BView::InvalidateLayout(), BLayoutItem::InvalidateLayout(),
BLayout::LayoutInvalidated()
\since Haiku R1
*/
/*!
\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.
BLayout::InvalidateLayout()) and has not yet been validated
(by doing a layout, or by its ResetLayoutInvalidation() method.
\since Haiku R1
*/
@@ -409,21 +462,27 @@ topLayout->AddItem(nestedLayoutWithView);
\fn void BLayout::EnableLayoutInvalidation()
\brief Re-enable layout invalidation after a call to
DisableLayoutInvalidation().
\since Haiku R1
*/
/*!
\fn void BLayout::DisableLayoutInvalidation()
\brief Disable layout invalidation notifications, i.e. calls to
this object's InvalidateLayout() method.
this object's InvalidateLayout() method.
\since Haiku R1
*/
/*!
\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.
again. This method should be called once any cached data has been
validated, or updated to valid values.
\since Haiku R1
*/
@@ -431,9 +490,12 @@ topLayout->AddItem(nestedLayoutWithView);
/*!
\name Archiving methods
\brief These methods relate to the archiving or unarchiving of this object
and the BLayoutItem&apos;s it contains
\name Archiving
These methods relate to the archiving or unarchiving of this object
and the BLayoutItem's it contains
\since Haiku R1
*/
@@ -443,14 +505,18 @@ topLayout->AddItem(nestedLayoutWithView);
/*!
\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.
the items in this layout, calling ItemArchived() for each one.
\since Haiku R1
*/
/*!
\fn status_t BLayout::AllUnarchived(const BMessage* from)
\brief Unarchives the BLayoutItem&apos;s for this layout, calling
ItemUnarchived() for each one.
\brief Unarchives the BLayoutItem's for this layout, calling
ItemUnarchived() for each one.
\since Haiku R1
*/
@@ -458,10 +524,12 @@ topLayout->AddItem(nestedLayoutWithView);
\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.
\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.
\since Haiku R1
*/
@@ -472,8 +540,11 @@ topLayout->AddItem(nestedLayoutWithView);
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.
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.
\since Haiku R1
*/
@@ -481,7 +552,7 @@ topLayout->AddItem(nestedLayoutWithView);
/*!
\name BLayout Hook methods
\name Hook Methods
*/
@@ -495,11 +566,12 @@ topLayout->AddItem(nestedLayoutWithView);
\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.
\return \c true on succcess, false if \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().
\since Haiku R1
*/
@@ -517,6 +589,8 @@ topLayout->AddItem(nestedLayoutWithView);
\note This is a good time to delete the data you've attached to \a item
via BLayoutItem::SetLayoutData().
\since Haiku R1
*/
@@ -524,6 +598,8 @@ topLayout->AddItem(nestedLayoutWithView);
\fn void BLayout::DoLayout() = 0
\brief Implemented by derived classes to position and resize the items in
this layout.
\since Haiku R1
*/
@@ -534,6 +610,8 @@ topLayout->AddItem(nestedLayoutWithView);
to clear any caches your object might hold.
\param children Whether or not child layouts have also been invalidated.
\since Haiku R1
*/
@@ -542,33 +620,41 @@ topLayout->AddItem(nestedLayoutWithView);
\brief Hook method called when this layout is attached to a BView.
\param was The previous owner of this BLayout, for new BLayout s, this
will be \c NULL.
will be \c NULL.
\since Haiku R1
*/
/*!
\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.
BLayout must include the BLayout version of this method in their
implementation.
\since Haiku R1
*/
/*!
\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.
BLayout must include the BLayout version of this method in their
implementation.
\param layout The BLayout that this BLayout was detached from.
\since Haiku R1
*/
/*!
\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.
BLayout must include the BLayout version of this method in their
implementation.
\since Haiku R1
*/