haiku/docs/user/interface/Box.dox

/*
 * Copyright 2010, Haiku inc.
 * Distributed under the terms of the MIT Licence.
 *
 * Documentation by:
 *		Clark Gaeble
 *		Adrien Destugues <pulkomandy@pulkomandy.ath.cx>
 *		John Scipione <jscipione@gmail.com>
 * Corresponds to:
 *		/trunk/headers/os/interface/Box.h	 rev 42274
 *		/trunk/src/kits/interface/Box.cpp	 rev 42274


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


/*!
	\class BBox
	\ingroup interface
	\brief The BBox class is used to draw a square box in a window with an
	optional label to group related subviews.

	A BBox is an organizational interface element used to group related views 
	together visually. A basic BBox looks like this:

	\image html B_FANCY_BORDER.png

	A box's label can either be text or it can be another control such
	as a checkbox or dropdown box. See SetLabel() for more details on setting
	the label on a BBox.
*/


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

	\note This is the only constructor that can be used if the BBox is to be
		inserted in a window that doesn't use the layout system.

	\param frame The bounds of the BBox.
	\param name The name of the BBox.
	\param resizingMode Defines the behavior of the BBox as the parent view
		resizes.
	\param flags Behavior flags for the BBox. See BView for details.
	\param border The border_style of the BBox.
*/


/*!
	\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 with dimensions defined automatically by the
		Layout Kit.

	\param name The name of the BBox.
	\param flags Behavior flags for the BBox. See BView for details.
	\param border The border_style of the BBox.
	\param child Adds an initial child to the BBox. See the Layout Kit for
		details.
*/


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

	There can only be a single child view in the BBox. This view can, however,
	act as a nesting container if you need more things to show inside the BBox.
*/


/*!
	\fn BBox::BBox(BMessage* archive)
	\brief For archive restoration, allows a BBox to be constructed from an
		\a archive message.

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

	If the \a archive is a deep one, the BBox will also unarchive all
	of its children recursively.

	\param archive The \a archive to restore from.
*/


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

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


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

	If the message is a valid BBox then an instance of BBox 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 BBox if the \a archive is valid or \c NULL.
*/


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

	\param archive The target \a archive which the BBox data will go
		into.
	\param deep Whether or not to recursively archive the children.
	\returns A status flag indicating if the archive operation was successful.
	
	\retval B_OK The archive operation was successful.
	\retval B_BAD_VALUE The archive operation failed.
*/


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

	Possible values are \c B_PLAIN_BORDER (a single 1-pixel line border),
	\c B_FANCY_BORDER (the default, beveled look), and \c B_NO_BORDER, which
	is used to make an invisible box. See border_style for more details.
*/


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

	\returns The border_style flag that is currently set to the BBox.
*/


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

	\warning This method is not part of the BeOS R5 API and 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. You can
	use this value to line up two boxes visually if one has a label and the
	other does not.

	\returns The distance offset of the BBox as a \c float.
*/


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

	\warning This method is not part of the BeOS R5 API and is not yet
		finalized.

	\returns A BRect of the dimensions of the box's inside border.
*/


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

	Below is an example of a BBox with a simple text label:

	\image html BBox_example.png

	The code to create a BBox 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.
*/


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

	This version of SetLabel() allows building a BBox with a control as a
	label widget. You can pass in any type of BView derived control for this
	such as a BPopupMenu or BCheckBox.

	An example of a BBox with a BCheckBox control attached is shown below:

	\image html BBox_with_checkbox.png

	The code to create such a BBox 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
*/


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

	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.

	\returns The label text of the BBox as a <tt>const char*</tt> if the BBox
		has a text label or \c NULL otherwise.
*/


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


/*!
	\fn virtual	void BBox::Draw(BRect updateRect)
	\brief Draws onto the parent window the part of the BBox that intersects
		the dirty area.

	This is an hook method called by the interface kit. You don't have to call
	it yourself. If you need to force redrawing of (part of) the BBox, consider
	using Invalidate instead.

	\param updateRect The area that needs to be redrawn. Note the box may draw
		more around the rectangle.
*/


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

	This method sets the box's background color to the background of the
	parent view.

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


/*!
	\fn virtual void BBox::FrameResized(float width, float height)
	\brief Called when the BBox needs to change its size.

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

	It recomputes the layout of the BBox (including label and contents) and
	makes it redraw as necessary.
*/


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

	This only works in the non-layout mode, as it forces the resizing.
*/


/*!
	\fn virtual void BBox::GetPreferredSize(float* _width, float* _height)
	\brief Gets the dimensions that the BBox would prefer to be.

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

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

	\param[out] _width The width of the preferred size is placed in here.
	\param[out] _height The height of the preferred size is placed in here.
*/


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

	Drawing the BBox 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.
*/


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

	The maximum size depends on the child view's one.

	\returns A BSize of the maximum possible size of the BBox.
*/


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

	This is the same as GetPreferredSize, but using the more convenient BSize
	struct.

	\returns A BSize of the minimum possible size of the BBox.
*/


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

	This only works if the BBox uses the layout system from the Layout Kit,
	i.e. it was created with one of the BRect-less constructors.

	Once the size of the BBox is known, from layouting of the parent views,
	this method is called so the BBox 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.
*/