Aren/haiku
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
1a88b571ca
haiku/docs/user/interface/SplitView.dox
Niels Sascha Reedijk 6758018a21 HaikuBook: add remaining layout class documentation 
This is the final contribution to #15368

* Tried to share more documentation in the various BLayoutBuilder classes
* Add missing GridView, GroupView, SpaceLayoutItem
* Also added AbstractLayoutItem, but hide the actual documentation behind
  an `INTERNAL` conditional block. This block identifier can be used to
  document parts of the API, to then hide them during a regular Doxygen run.
* Do some cleanup on other layout classes; add missing members, etc.
* The actual generated BLayoutBuilder::* html is a mess. I should investigate
  this at a later time. Especially the copied members seem to mix type
  definitions with member documentation. It is odd. Not unlikely to be a
  Doxygen bug.
* The general documentation for the layout system could use an overhaul as
  well, but this is for later.

Change-Id: I6db9ef105b4ae6de0f1ebb917f86f8b1c0d4ea2e
Reviewed-on: https://review.haiku-os.org/c/haiku/+/2491
Reviewed-by: waddlesplash <waddlesplash@gmail.com>
2020-04-18 18:24:51 +00:00

577 lines
14 KiB
Plaintext
Raw Blame History

/*
* Copyright 2020 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, niels.reedijk@gmail.com
*
* Reviewers:
* Adrien Destugues, pulkomandy@pulkomandy.tk
*
* Corresponds to:
* headers/os/interface/SplitView.h hrev49977
* src/kits/interface/SplitView.cpp hrev43279
*/
/*!
\file SplitView.h
\ingroup layout
\ingroup libbe
\brief Provides the BSplitView class.
\since Haiku R1
*/
/*!
\class BSplitView
\ingroup layout
\ingroup libbe
\brief A container with two or more sections, with dividers in between,
so that a user can manipulate the size of the sections by dragging
a slider.
This container view consists one of more items, that are laid out
horizontally or vertically. Between two adjoining items, there is a
splitter. This splitter allows the user to change how the space between the
individual items is divided.
The screenshot below shows the BSplitView being used in HaikuDepot. The
BSplitView is the main container of the window, in this case with a
\ref B_VERTICAL layout. The top part contains the list of packages, and
some filter tools. At the bottom are individual package details. In between
the two visual elements there is a dotted line, indicating the draggable
separator. At the right hand of this separator, above the \b Install
button, you can see that the mouse cursor changed into the double arrow,
indicating the user that the element is dragable.
\image html BSplitView_HaikuDepot.png
Because of the dynamic nature of the size of the sections within the
split view, it is best to use this container with the \link layout layout
system\endlink. It is fully supported by the layout builder utilities. See
the \ref BLayoutBuilder::Split<> documentation for the builder that
accompanies this view.
The container has the following properties:
- \b Insets are the padding for the split view.
- \b Spacing is the spacing between the components.
- \b Orientation is whether the splits are horizontal or vertical.
- \b Splitter \b size is the size of the splitter.
Specifically for individual elements, the following properties may also
be set:
- \b Weight for the weight of the item within the split view (determines
how space is allocated between the items).
- \b Collapsible determines if an element is collapsible, meaning the user
can drag the splitter as such as to hide the item completely. If an item
is not collapsible, at least a part of the item will always be visible
to the user.
\related The \ref BGroupView essentially has the same properties for
organizing the layout items, though it does not offer the functionality
for users to change the size of the elements.
\since Haiku R1
*/
/*!
\fn BSplitView::BSplitView(orientation orientation=B_HORIZONTAL, float spacing=B_USE_DEFAULT_SPACING)
\brief Creates a new split view.
\param orientation The orientation of the splits.
\param spacing The spacing in between the elements.
\since Haiku R1
*/
/*!
\fn BSplitView::BSplitView(BMessage *from)
\brief Unarchive a split view.
This method is usually not called directly, if you want to build a
split view from an archived message you should call Instantiate() instead
because it can handle errors properly.
\param from The \ref BMessage that contains the split view.
\since Haiku R1
*/
/*!
\fn virtual BSplitView::~BSplitView()
\brief Destructor.
\since Haiku R1
*/
/*!
\fn void BSplitView::SetInsets(float left, float top, float right, float bottom)
\brief Set the insets between the bounds of the view and the inner
elements.
\param left The left inset.
\param top The top inset.
\param right The right inset.
\param bottom The bottom inset.
\since Haiku R1
*/
/*!
\fn void BSplitView::SetInsets(float horizontal, float vertical)
\brief Set the insets between the bounds of the view and the inner
elements.
\param horizontal The left and right inset.
\param vertical The top and bottom inset.
\since Haiku R1
*/
/*!
\fn void BSplitView::SetInsets(float insets)
\brief Set the insets between the bounds of the view and the inner
elements.
\param insets The value for the left, top, right and bottom inset.
\since Haiku R1
*/
/*!
\fn void BSplitView::GetInsets(float *left, float *top, float *right, float *bottom) const
\brief Get the insets that apply to this view.
You may pass \c NULL for any of the parameters, if you do not wish to
retrieve their value.
\param[out] left Will be set to the left inset.
\param[out] top Will be set to the top inset.
\param[out] right Will be set to the right inset.
\param[out] bottom Will be set to the bottom inset.
\since Haiku R1
*/
/*!
\fn float BSplitView::Spacing() const
\brief Get the spacing between elements in this view.
\return The spacing between elements as a \c float.
\since Haiku R1
*/
/*!
\fn void BSplitView::SetSpacing(float spacing)
\brief Set the spacing between elements in this view.
\param spacing The desired spacing between elements. This will apply to all
elements.
\since Haiku R1
*/
/*!
\fn orientation BSplitView::Orientation() const
\brief Get the orientation of the elements in this view.
\retval B_HORIZONTAL The elements are ordered left-to-right.
\retval B_VERTICAL The elements are ordered top-to-bottom.
\since Haiku R1
*/
/*!
\fn void BSplitView::SetOrientation(orientation orientation)
\brief Set the orientation of the elements in this view.
\param orientation May be \ref B_HORIZONTAL or \ref B_VERTICAL.
\since Haiku R1
*/
/*!
\fn float BSplitView::SplitterSize() const
\brief Get the size of the splitter(s) in this view.
\return The size of the splitter(s).
\since Haiku R1
*/
/*!
\fn void BSplitView::SetSplitterSize(float size)
\brief Set the size of the splitter(s) in this view.
\param size The size as a \c float that will be applied to all splitters
in this view.
\since Haiku R1
*/
/*!
\fn int32 BSplitView::CountItems() const
\brief The number of items in this view.
\return Returns the number of items in this view. The splitters themselves
are not included in this number.
\since Haiku R1
*/
/*!
\fn float BSplitView::ItemWeight(int32 index) const
\brief Get the item weight for the item at the \a index.
\param index The index of the item (zero-based).
\return The weight of the item, or \c 0.0 if there is no item at \a index.
\since Haiku R1
*/
/*!
\fn float BSplitView::ItemWeight(BLayoutItem *item) const
\brief Get the item weight for an existing \a item.
\param item An existing layout item object.
\return The weight of the \a item, or \c 0.0 if the item is not associated
with this view.
\since Haiku R1
*/
/*!
\fn void BSplitView::SetItemWeight(int32 index, float weight, bool invalidateLayout)
\brief Set the weight of the item at \a index.
The weight is relative to all other items in the layout, and determines how
the available space is distributed over the items in the layout.
\param index The index of the item (zero-based).
\param weight The weight of the item.
\param invalidateLayout When \c true, calls
\ref BLayout::InvalidateLayout() to recalculate the layout.
\since Haiku R1
*/
/*!
\fn void BSplitView::SetItemWeight(BLayoutItem *item, float weight)
\brief Set the weight of the \a item.
The weight is relative to all other items in the layout, and determines how
the available space is distributed over the items in the layout.
\param item The item within this view that the weight applies to.
\param weight The weight of the item.
\since Haiku R1
*/
/*!
\fn bool BSplitView::IsCollapsible(int32 index) const
\brief Get whether the item at \a index is collapsible.
\param index The index of the item (zero-based).
\retval true The user can collapse the item.
\retval false The user cannot collapse the item.
\since Haiku R1
*/
/*!
\fn void BSplitView::SetCollapsible(bool collapsible)
\brief Set the whether all the layout items in this view are collapsible.
\param collapsible \c true if all items in this layout are collapsible,
\c false if they are not.
\since Haiku R1
*/
/*!
\fn void BSplitView::SetCollapsible(int32 index, bool collapsible)
\brief Set whether the item at \a index is collapsible.
\param index The index of the item (zero-based).
\param collapsible \c true if the user may collaps the item, \c false if
they may not.
\since Haiku R1
*/
/*!
\fn void BSplitView::SetCollapsible(int32 first, int32 last, bool collapsible)
\brief Set whether the items from \a first to \a last are collapsible.
\param first The index of the first item that you want the setting to apply
to (zero-based).
\param last The index of the last item that you want the setting to apply
to (zero-based).
\param collapsible \c true if the user may collaps the item, \c false if
they may not.
\since Haiku R1
*/
/*!
\fn bool BSplitView::IsItemCollapsed(int32 index) const
\brief Check whether the item at \a index is collapsed.
\param index The index of the item (zero-based).
\retval true The item is collapsed.
\retval false The item is not collapsed.
\since Haiku R1
*/
/*!
\fn void BSplitView::SetItemCollapsed(int32 index, bool collapsed)
\brief Set whether the item at \a index is displayed as collapsed.
\param index The index of the item (zero-based).
\param collapsed \c true if the item should be rendered collapsed, \c
false if it needs to be visible.
\since Haiku R1
*/
/*!
\fn void BSplitView::AddChild(BView *child, BView *sibling=NULL)
\brief Add a \a child to the view.
Passthrough for \ref BView::AddChild(BView *child, BView *sibling). This
bypasses the layout system, so only use it when you know what you are
doing.
\since Haiku R1
*/
/*!
\fn bool BSplitView::AddChild(BView *child, float weight)
\brief Add a \a child with a \a weight.
The view will be added at the end of the existing layout items, meaning it
will be placed to the right or bottom of existing items.
\param child The view that should be added as a child. The ownership is
transferred to this view.
\param weight The weight of the item.
\return \c true when succesfully, \c false if there was an error.
\since Haiku R1
*/
/*!
\fn bool BSplitView::AddChild(int32 index, BView *child, float weight)
\brief Add a \a child at \a index with a \a weight.
\param index The desired position for the \a child. Existing items will be
shifted to the right or down based on the orientation. If the index is
higher than the number of items, the item will be added after farmost
item. The index is zero-based.
\param child The view that should be added as a child. The ownership is
transferred to this view.
\param weight The weight of the item.
\return \c true when succesfully, \c false if there was an error.
\since Haiku R1
*/
/*!
\fn bool BSplitView::AddChild(BLayoutItem *child)
\brief Add a \a child.
The child will be added at the end of the existing layout items, meaning it
will be placed to the right or bottom of existing items.
\param child The layout item to add.
\return \c true when succesfully, \c false if there was an error.
\since Haiku R1
*/
/*!
\fn bool BSplitView::AddChild(BLayoutItem *child, float weight)
\brief Add a \a child with a \a weight.
The child will be added at the end of the existing layout items, meaning it
will be placed to the right or bottom of existing items.
\param child The layout item to add.
\param weight The weight of the item.
\return \c true when succesfully, \c false if there was an error.
\since Haiku R1
*/
/*!
\fn bool BSplitView::AddChild(int32 index, BLayoutItem *child, float weight)
\brief Add a \a child at \a index with a \a weight.
\param index The desired position for the \a child. Existing items will be
shifted to the right or down based on the orientation. If the index is
higher than the number of items, the item will be added after farmost
item. The index is zero-based.
\param child The layout item to add.
\param weight The weight of the item.
\return \c true when succesfully, \c false if there was an error.
\since Haiku R1
*/
/*!
\fn virtual void BSplitView::AttachedToWindow()
\brief Hook method overridden from BView.
\since Haiku R1
*/
/*!
\fn virtual void BSplitView::Draw(BRect updateRect)
\brief Hook method overridden from BView.
\since Haiku R1
*/
/*!
\fn virtual void BSplitView::DrawAfterChildren(BRect updateRect)
\brief Hook method overridden from BView.
\since Haiku R1
*/
/*!
\fn virtual void BSplitView::MouseDown(BPoint where)
\brief Hook method overridden from BView.
\since Haiku R1
*/
/*!
\fn virtual void BSplitView::MouseUp(BPoint where)
\brief Hook method overridden from BView.
\since Haiku R1
*/
/*!
\fn virtual void BSplitView::MouseMoved(BPoint where, uint32 transit, const BMessage *message)
\brief Hook method overridden from BView.
\since Haiku R1
*/
/*!
\fn virtual void BSplitView::MessageReceived(BMessage *message)
\brief Hook method overridden from BView.
\since Haiku R1
*/
/*!
\fn virtual void BSplitView::SetLayout(BLayout *layout)
\brief Hook method overridden from BView.
\since Haiku R1
*/
/*!
\fn virtual status_t BSplitView::Archive(BMessage *into, bool deep=true) const
\copydoc BArchivable::Archive()
*/
/*!
\fn virtual status_t BSplitView::Perform(perform_code d, void *arg)
\brief Hook method overridden from BView.
\since Haiku R1
*/
/*!
\fn static BArchivable* BSplitView::Instantiate(BMessage *from)
\brief Instantiate the view from the message \a from.
\since Haiku R1
*/
/*!
\fn virtual status_t BSplitView::AllArchived(BMessage *into) const
\brief Hook method overridden from BArchivable.
\since Haiku R1
*/
/*!
\fn virtual status_t BSplitView::AllUnarchived(const BMessage *from)
\brief Hook method overridden from BArchivable.
\since Haiku R1
*/
/*!
\fn virtual void BSplitView::DrawSplitter(BRect frame, const BRect &updateRect, orientation orientation, bool pressed)
\brief Hook method called when the splitter needs to be drawn.
This method is called in the context of a \ref BView::Draw() operation.
Derived classes can override this to draw a splitter.
\since Haiku R1
*/
Reference in New Issue View Git Blame Copy Permalink