313 lines
7.1 KiB
Plaintext
313 lines
7.1 KiB
Plaintext
/*!
|
|
\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.
|
|
*/
|
|
|
|
|
|
//@}
|