haiku/docs/user/interface/Box.dox

/*
 * Copyright 2011 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Clark Gaeble
 *		Adrien Destugues <pulkomandy@pulkomandy.ath.cx>
 *		John Scipione <jscipione@gmail.com>
 *
 * Corresponds to:
 *		headers/os/interface/Box.h	 rev 42274
 *		src/kits/interface/Box.cpp	 rev 42274
 */


/*!
	\file Box.h
	\ingroup interface
	\ingroup libbe
	\brief Defines the BBox class
*/


/*!
	\class BBox
	\ingroup interface
	\ingroup libbe
	\brief A rectangular view with a border and an optional label to group
		related subviews visually.

	A basic BBox looks like this:
	\image html B_FANCY_BORDER.png

	A box's label can either be composed of text or it can be a view such
	as a checkbox or dropdown box. See SetLabel() for more details on setting
	the box's label.

	\since BeOS R3
*/


/*!
	\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 named BBox object from a set of dimensions.

	\note 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.
	\param resizingMode Defines the behavior of the box as the parent view
	       resizes. See BView for details.
	\param flags Behavior flags for the box. See BView for details.
	\param border The border_style of the box.

	\since BeOS R3
*/


/*!
	\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)
	\brief Constructs a named BBox object with its dimensions defined
		automatically by the Layout API.

	\param name The name of the box.
	\param flags Behavior flags for the box. See BView for details.
	\param border The border_style of the box.
	\param child Adds an initial child to the Box object. See the Layout
		API for details.

	\since Haiku R1
*/


/*!
	\fn BBox::BBox(border_style border, BView* child)
	\brief Constructs an anonymous BBox object with a defined border style
		and child view.

	There can only be a single child view. This view can, however, act as a
	nesting container if you need to show more items inside the box.

	\since Haiku R1
*/


/*!
	\fn BBox::BBox(BMessage* archive)
	\brief Constructs a BBox object from an \a archive message.

	This method is usually not called directly. If you want to build a BBox
	object from a message you should call Instantiate() which can
	handle errors properly.

	If the \a archive deep, the BBox object will also unarchive each of its
	child views recursively.

	\param archive The \a archive message to restore from.

	\since BeOS R3
*/


/*!
	\fn BBox::~BBox()
	\brief Destructor method.

	Calling the destructor will also free the memory used by the box's label
	if it has one.

	\since BeOS R3
*/


/*!
	\name Archiving
*/


//! @{


/*!
	\fn static BArchivable* BBox::Instantiate(BMessage* archive)
	\brief Creates a new object from an \a archive.

	If the message is a valid object then the instance created from the
	passed in \a archive will be returned. Otherwise this method will
	return \c NULL.

	\param archive The \a archive message.

	\returns An instance of the object if \a archive is valid or \c NULL.

	\sa BArchivable::Instantiate()

	\since BeOS R3
*/


/*!
	\fn virtual status_t BBox::Archive(BMessage* archive,
		bool deep = true) const;
	\brief Archives the object into \a archive.

	\param archive The target \a archive that the data will go into.
	\param deep Whether or not to recursively archive child views.

	\retval B_OK The archive operation was successful.
	\retval B_BAD_VALUE \c NULL \a archive message.
	\retval B_ERROR The archive operation failed.

	\sa BArchivable::Archive()

	\since BeOS R3
*/


//! @}


/*!
	\fn virtual void BBox::SetBorder(border_style border)
	\brief Sets the #border_style.

	Possible #border_style values include:
		- \c B_PLAIN_BORDER A single 1-pixel line border.
		- \c B_FANCY_BORDER The default, beveled look.
		- \c B_NO_BORDER Used to make a borderless box.

	\param border The #border_style to set.

	\since BeOS R3
*/


/*!
	\fn border_style BBox::Border() const
	\brief Gets the current #border_style.

	Possible #border_style values include:
		- \c B_PLAIN_BORDER A single 1-pixel line border.
		- \c B_FANCY_BORDER The default, beveled look.
		- \c B_NO_BORDER Used to make a borderless box.

	\returns The #border_style of the box.

	\since BeOS R3
*/


/*!
	\fn float BBox::TopBorderOffset()
	\brief Gets the distance from the very top of the box to the top border
		line in pixels.

	\warning This method is not yet finalized.

	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. This
	method can be used to line up two boxes visually if one has a label and
	the other does not.

	\returns The distance from the very top of the box to the top border
		line in pixels as a \c float.

	\since Haiku R1
*/


/*!
	\fn BRect BBox::InnerFrame()
	\brief Gets the frame rectangle just inside the border of the box.

	\warning This method is not yet finalized.

	\returns A BRect set to the dimensions of the box's inside border.

	\since Haiku R1
*/


/*!
	\fn void BBox::SetLabel(const char* string)
	\brief Sets the box's label text.

	Below is an example of a box with some simple text label:

	\image html BBox_example.png

	The code to create a box with a text label looks like this:
	\code
fIconBox = new BBox("Icon Box");
fIconBox->SetLabel("Icon");
	\endcode

	\param string The label text string to set as the box's title.

	\since BeOS R3
*/


/*!
	\fn status_t BBox::SetLabel(BView* viewLabel)
	\brief Sets the label from a BView.

	This version of SetLabel() provides for building a BBox object with a
	control used in place of the text label. You can pass in any type of
	BView derived control for this such as a BPopupMenu or BCheckBox.

	An example of a box with a checkbox view is shown below:
	\image html BBox_with_checkbox.png

	The code to create such a box looks like this:
	\code
fVirtualMemoryEnabledCheckBox = new BCheckBox("Virtual memory check box",
	"Enable virtual memory", new BMessage(kVirtualMemoryEnabled));

BBox* fVirtualMemoryBox = new BBox("Virtual memory box");
fVirtualMemoryBox->SetLabel(fVirtualMemoryEnabledCheckBox);
	\endcode

	\param viewLabel A BView.

	\returns \c B_OK

	\since BeOS R3
*/


/*!
	\fn const char* BBox::Label() const
	\brief Gets the text of the box's label.

	This only works if the label is set as text. If you set the label to a
	BView, you have to get the text by other means, likely starting with
	LabelView.

	\returns The label text of the BBox if the box has a text label or
		\c NULL otherwise.

	\since BeOS R3
*/


/*!
	\fn BView* BBox::LabelView() const
	\brief Gets the BView representing the label.

	\returns a pointer to a BView object.

	\since BeOS R4
*/


/*!
	\fn virtual void BBox::Draw(BRect updateRect)
	\brief Draws the area of the box that intersects \a updateRect.

	This is an hook method called by the Interface Kit, you don't have to
	call it yourself. If you need to forcefully redraw the view,
	consider calling Invalidate() instead.

	\param updateRect The rectangular area to be drawn.

	\since BeOS R3
*/


/*!
	\fn virtual void BBox::AttachedToWindow()
	\brief Hook method that is called when the object is attached to a
		window.

	This method overrides BView::AttachedToWindow() to set the background
	color of the box to the background of its parent view.

	If you are using the layout system, the BBox is also resized according to
	the layout of the parent view.

	\sa BView::AttachedToWindow()

	\since BeOS R3
*/


/*!
	\fn virtual void BBox::FrameResized(float width, float height)
	\brief Hook method that gets called when the BBox object is resized.

	This method may be called either because the window in which the BBox
	object was resized, or because the window layout was otherwise altered.

	This method recomputes the layout of the BBox (including label and
	contents) and makes it redraw as necessary.

	\since BeOS R3
*/


/*!
	\fn virtual void BBox::ResizeToPreferred()
	\brief Resizes the box to its preferred dimensions.

	\note This only works in the non-layout mode, as it forces the resizing.

	\since BeOS R3
*/


/*!
	\fn virtual void BBox::GetPreferredSize(float* _width, float* _height)
	\brief Fill out the preferred width and height of the box
		into the \a _width and \a _height parameters.

	\note Either the \a _width or \a _height parameter may be set to \c NULL
		if you only want to get the other one.

	The size is computed from the child view sizes, unless it was explicitly
	set for the BBox (which can be done only if the BBox is configured to
	use the Layout API).

	\param[out] _width Pointer to a \c float to store the width of the view.
	\param[out] _height Pointer to a \c float to store the height of the view.

	\since BeOS R3
*/


/*!
	\fn virtual BSize BBox::MinSize()
	\brief Gets the minimum possible size of the BBox object.

	Drawing the box at this size ensures the label and the child view are
	visible. Reducing the size even more would mean that a view would not
	be visible.

	\since Haiku R1
*/


/*!
	\fn virtual BSize BBox::MaxSize()
	\brief Gets the maximum possible size of the BBox object.

	The maximum size depends on the maximize size of the child views.

	\returns The maximum possible size of the BBox as a BSize.

	\since Haiku R1
*/


/*!
	\fn virtual BSize BBox::PreferredSize()
	\brief Returns the preferred size of the box.

	This method works the same as GetPreferredSize, but uses the more
	convenient BSize object.

	\returns The minimum possible size of the BBox as a BSize.

	\since Haiku R1
*/


/*!
	\fn virtual void BBox::DoLayout()
	\brief Lays out the box moving everything into its appropriate position.

	This only works if the BBox object was constructed using the Layout API,
	i.e. it was created with one of the BRect-less constructors.

	Once the size of the box is known from laying out its parent views,
	this method is called so the box can adjust the position and size of the
	label, eventually truncating the label text if there is not enough space.
	The exact border positions are also computed, then the child view is also
	laid out if its size constraints change.

	\since Haiku R1
*/