2010-12-01 00:06:09 +03:00
|
|
|
/*
|
|
|
|
* Copyright 2010, Haiku inc.
|
|
|
|
* Distributed under the terms of the MIT Licence.
|
|
|
|
*
|
|
|
|
* Documentation by:
|
|
|
|
* Clark Gaeble
|
|
|
|
* Adrien Destugues <pulkomandy@pulkomandy.ath.cx>
|
|
|
|
* Corresponds to:
|
|
|
|
* /trunk/headers/os/interface/Box.h rev 39685
|
|
|
|
* /trunk/src/kits/interface/Box.cpp rev 39685
|
|
|
|
|
|
|
|
/*!
|
|
|
|
\file Box.h
|
|
|
|
\brief Defines the BBox class
|
|
|
|
*/
|
|
|
|
|
|
|
|
/*! \class BBox
|
|
|
|
\ingroup interface
|
|
|
|
\brief Class just drawing a square box with a label in a window.
|
|
|
|
|
|
|
|
A Box represents a square on the interface with dimensions, an optional
|
|
|
|
name, and no interactivity.
|
|
|
|
|
|
|
|
This would be used to visually group elements together.
|
|
|
|
*/
|
|
|
|
|
|
|
|
/*! \fn BBox::BBox(BRect frame, const char *name = NULL, uint32 resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP, uint32 flags = B_WILL_DRAW | B_FRAME_EVENTS | B_NAVIGABLE_JUMP, border_style border = B_FANCY_BORDER)
|
|
|
|
\brief Constructs a Box from a set of dimensions.
|
|
|
|
|
|
|
|
This is the only constructor that can be used if the box is to be inserted
|
|
|
|
in a window that doesn't use the layout system.
|
|
|
|
|
|
|
|
\param frame The bounds of the box.
|
|
|
|
\param name The name of the box.
|
2010-12-01 23:12:28 +03:00
|
|
|
\param resizingMode Defines the behavior of the box as the parent view
|
|
|
|
resizes.
|
|
|
|
\param flags Behavior flags for the box. See BView page for more
|
|
|
|
info.
|
|
|
|
\param border Sets the initial style of the border. See SetBorder for
|
|
|
|
more details.
|
2010-12-01 00:06:09 +03:00
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
|
|
/*! \fn BBox::BBox(const char* name, uint32 flags = B_WILL_DRAW | B_FRAME_EVENTS | B_NAVIGABLE_JUMP, border_style border = B_FANCY_BORDER, BView* child = NULL)
|
2010-12-01 23:12:28 +03:00
|
|
|
\brief Constructs a named Box, with dimensions defined automatically by the
|
|
|
|
Layout Kit.
|
2010-12-01 00:06:09 +03:00
|
|
|
|
2010-12-01 23:12:28 +03:00
|
|
|
\param name The name of the box.
|
|
|
|
\param flags Behavior flags for the box.
|
|
|
|
\param border Defines the initial border style.
|
|
|
|
\param child Adds an initial child to the box. See: Layout Kit
|
2010-12-01 00:06:09 +03:00
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
|
|
|
|
/*! \fn BBox::BBox(border_style border, BView* child)
|
|
|
|
\brief Constructs an anonymous Box, with a defined border style and a child.
|
|
|
|
|
|
|
|
There can only be a single child view in the box. This view can, however,
|
|
|
|
act as a nesting container if you need more things to show inside the box.
|
|
|
|
|
|
|
|
\param border The initial border style of the box.
|
|
|
|
\param child The child of the Box.
|
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
|
|
|
|
/*! \fn BBox::BBox(BMessage* archive)
|
|
|
|
\brief For archive restoration, allows a box to be constructed from an
|
|
|
|
archive message.
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
You don't usually call this directly, if you want to build a BBox from a
|
2010-12-01 23:12:28 +03:00
|
|
|
message, prefer calling Instantiate, which can properly handle errors.
|
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
If the archive is a deep one, the box will also unarchive all of its
|
|
|
|
children recursively.
|
|
|
|
|
|
|
|
\param archive The archive to restore from.
|
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
/*! \fn static BArchivable* BBox::Instantiate(BMessage* archive)
|
|
|
|
\brief Creates a new BBox from an archive.
|
|
|
|
|
|
|
|
If the message is a valid box, an instance of BBox (created from the
|
|
|
|
archive) will be returned. Otherwise, this function will return NULL.
|
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
|
|
|
|
/*! \fn virtual status_t BBox::Archive(BMessage* archive, bool deep = true) const;
|
|
|
|
\brief Archives the box into archive.
|
|
|
|
|
|
|
|
\param archive The target archive which the box data will go into.
|
|
|
|
\param deep Whether or not to recursively archive the children.
|
|
|
|
\returns B_OK if the archive was successful.
|
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
/*! \fn virtual void BBox::SetBorder(border_style border)
|
|
|
|
\brief Sets the border style.
|
2010-12-01 23:12:28 +03:00
|
|
|
|
|
|
|
Possible values are B_PLAIN_BORDER (a single 1-pixel line border),
|
|
|
|
B_FANCY_BORDER (the default, slightly beveled look), and B_NO_BORDER, which
|
|
|
|
is used to make an invisible box.
|
2010-12-01 00:06:09 +03:00
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
|
|
|
|
/*! \fn border_style BBox::Border() const
|
|
|
|
\brief Gets the border style.
|
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
/*! \fn float BBox::TopBorderOffset()
|
2010-12-01 23:12:28 +03:00
|
|
|
\brief Gets the distance from the very top of the Box to the top border
|
|
|
|
line, in pixels.
|
|
|
|
|
|
|
|
The distance may vary depending on the text or view used as label, and the
|
|
|
|
font settings. The border is drawn center aligned with the label.
|
|
|
|
|
|
|
|
You can use this value to line up two boxes visually, if one has a label and
|
|
|
|
the other has not.
|
2010-12-01 00:06:09 +03:00
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
|
|
|
|
/*! \fn BRect BBox::InnerFrame()
|
|
|
|
\brief Returns the rectangle just inside the border.
|
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
/*! \fn void BBox::SetLabel(const char* string)
|
|
|
|
\brief Sets the label's text.
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
This text is shown as the box title on screen, so the user can identify the
|
|
|
|
purpose of it.
|
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
|
|
|
|
/*! \fn status_t BBox::SetLabel(BView* viewLabel)
|
|
|
|
\brief Sets the label from a pre-existing BView.
|
|
|
|
|
2010-12-01 23:12:28 +03:00
|
|
|
You can use any type of BView for this, such as a BPopupMenu.
|
2010-12-01 00:06:09 +03:00
|
|
|
This version of SetLabel is much more powerful than
|
|
|
|
SetLabel(const char* string). It allows building a box which contents can
|
|
|
|
be changed depending on the label widget.
|
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
/*! \fn const char* BBox::Label() const
|
|
|
|
\brief Gets the label's text.
|
2010-12-01 23:12:28 +03:00
|
|
|
|
|
|
|
This only works if the label was set as text. If you set another view as the
|
|
|
|
label, you have to get its text by other means, likely starting with
|
|
|
|
LabelView.
|
2010-12-01 00:06:09 +03:00
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
|
|
|
|
/*! \fn BView* BBox::LabelView() const
|
|
|
|
\brief Gets the BView representing the label.
|
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
/*! \fn virtual void BBox::Draw(BRect updateRect)
|
|
|
|
\brief Draws onto the parent window the part of the box that intersects
|
|
|
|
the dirty area.
|
2010-12-01 23:12:28 +03:00
|
|
|
|
|
|
|
This is an hook function called by the interface kit. You don't have to call
|
|
|
|
it yourself. If you need to force redrawing of (part of) the box, consider
|
|
|
|
using Invalidate instead.
|
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
\param updateRect The area that needs to be redrawn. Note the box may draw
|
2010-12-01 23:12:28 +03:00
|
|
|
more around the rectangle.
|
2010-12-01 00:06:09 +03:00
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
|
|
|
|
/*! \fn virtual void BBox::AttachedToWindow()
|
|
|
|
\brief Hook called when the box is attached to a window.
|
|
|
|
|
|
|
|
This function sets the box background color to the parent's one.
|
|
|
|
|
|
|
|
If you are using the layout system, the box is also resized depending
|
|
|
|
on the layout of the parent view.
|
|
|
|
*/
|
|
|
|
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
/*! \fn virtual void BBox::FrameResized(float width, float height)
|
|
|
|
\brief Called when the box needs to change its size.
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
This function may be called either because the window in which the box is
|
|
|
|
was resized, or because the window layout was otherwise altered.
|
2010-12-01 23:12:28 +03:00
|
|
|
|
|
|
|
It recomputes the layouting of the box (including label and contents) and
|
|
|
|
makes it redraw itself as needed.
|
2010-12-01 00:06:09 +03:00
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
|
|
|
|
/*! \fn virtual void BBox::ResizeToPreferred()
|
|
|
|
\brief Resizes the box to its preferred dimensions.
|
2010-12-01 23:12:28 +03:00
|
|
|
|
|
|
|
This only works in the non-layout mode, as it forces the resizing.
|
2010-12-01 00:06:09 +03:00
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
|
2010-12-02 21:40:15 +03:00
|
|
|
/*! \fn virtual void BBox::GetPreferredSize(float* _width, float* _height)
|
2010-12-01 00:06:09 +03:00
|
|
|
\brief Gets the dimensions the box would prefer to be.
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
The size is computed from the children sizes, unless it was explicitly set
|
2010-12-01 23:12:28 +03:00
|
|
|
for the box (which canbe done only in layouted mode).
|
|
|
|
|
|
|
|
\note Either one of the parameters may be set to NULL if you only want to
|
|
|
|
get the other one.
|
2010-12-01 00:06:09 +03:00
|
|
|
|
2010-12-01 23:12:28 +03:00
|
|
|
\param _width An output parameter. The width of the preferred size is
|
|
|
|
placed in here.
|
|
|
|
\param _height An output parameter. The height of the preferred size is
|
|
|
|
placed in here.
|
2010-12-01 00:06:09 +03:00
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
|
|
|
|
/*! \fn virtual BSize BBox::MinSize()
|
|
|
|
\brief Gets the minimum possible size of the Box.
|
2010-12-01 23:12:28 +03:00
|
|
|
|
|
|
|
Drawing the box at this size ensures the label and the child view are
|
|
|
|
visible. Going smaller means something may get invisible on screen for lack
|
|
|
|
of space.
|
2010-12-01 00:06:09 +03:00
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
|
|
|
|
/*! \fn virtual BSize BBox::MaxSize()
|
|
|
|
\brief Gets the maximum possible size of the Box.
|
2010-12-01 23:12:28 +03:00
|
|
|
|
|
|
|
The maximum size depends on the child view's one.
|
2010-12-01 00:06:09 +03:00
|
|
|
*/
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
|
|
|
|
/*! \fn virtual BSize BBox::PreferredSize()
|
|
|
|
\brief Returns the box's preferred size.
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
This is the same as GetPreferredSize, but using the more convenient BSize
|
|
|
|
struct.
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
|
|
/*! \fn virtual void BBox::DoLayout()
|
|
|
|
\brief Lays out the box. Moves everything to its appropriate position.
|
2010-12-01 23:12:28 +03:00
|
|
|
|
2010-12-01 00:06:09 +03:00
|
|
|
This only works if the box uses the layout system, ie., was created with
|
|
|
|
one of the BRect-less constructors.
|
2010-12-01 23:12:28 +03:00
|
|
|
|
|
|
|
Once the size of the box is known, from layouting of the parent views, this
|
|
|
|
function is called so the box can adjust the position and size of the label,
|
|
|
|
eventually truncating the text if there is not enough space. The exact
|
|
|
|
border positions are also computed, then the child view is also layouted if
|
|
|
|
its size constraints changed.
|
2010-12-01 00:06:09 +03:00
|
|
|
*/
|