xref: /haiku/docs/user/interface/Box.dox (revision 0044a8c39ab5721051b6279506d1a8c511e20453)
1/*
2 * Copyright 2010, Haiku inc.
3 * Distributed under the terms of the MIT Licence.
4 *
5 * Documentation by:
6 *		Clark Gaeble
7 *		Adrien Destugues <pulkomandy@pulkomandy.ath.cx>
8 *		John Scipione <jscipione@gmail.com>
9 * Corresponds to:
10 *		/trunk/headers/os/interface/Box.h	 rev 42274
11 *		/trunk/src/kits/interface/Box.cpp	 rev 42274
12
13
14/*!
15	\file Box.h
16	\brief Defines the BBox class
17*/
18
19
20/*!
21	\class BBox
22	\ingroup interface
23	\brief The BBox class is used to draw a square box in a window with an
24	optional label to group related subviews.
25
26	A BBox is an organizational interface element used to group related views
27	together visually. A basic BBox looks like this:
28
29	\image html B_FANCY_BORDER.png
30
31	A box's label can either be text or it can be another control such
32	as a checkbox or dropdown box. See SetLabel() for more details on setting
33	the label on a BBox.
34*/
35
36
37/*!
38	\fn BBox::BBox(BRect frame, const char *name = NULL,
39		uint32 resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP,
40		uint32 flags = B_WILL_DRAW | B_FRAME_EVENTS | B_NAVIGABLE_JUMP,
41		border_style border = B_FANCY_BORDER)
42	\brief Constructs a BBox from a set of dimensions.
43
44	\note This is the only constructor that can be used if the BBox is to be
45		inserted in a window that doesn't use the layout system.
46
47	\param frame The bounds of the BBox.
48	\param name The name of the BBox.
49	\param resizingMode Defines the behavior of the BBox as the parent view
50		resizes.
51	\param flags Behavior flags for the BBox. See BView for details.
52	\param border The border_style of the BBox.
53*/
54
55
56/*!
57	\fn BBox::BBox(const char* name,
58		uint32 flags = B_WILL_DRAW | B_FRAME_EVENTS | B_NAVIGABLE_JUMP,
59		border_style border = B_FANCY_BORDER, BView* child = NULL)
60	\brief Constructs a named BBox with dimensions defined automatically by the
61		Layout Kit.
62
63	\param name The name of the BBox.
64	\param flags Behavior flags for the BBox. See BView for details.
65	\param border The border_style of the BBox.
66	\param child Adds an initial child to the BBox. See the Layout Kit for
67		details.
68*/
69
70
71/*!
72	\fn BBox::BBox(border_style border, BView* child)
73	\brief Constructs an anonymous BBox, with a defined border style and
74		a child.
75
76	There can only be a single child view in the BBox. This view can, however,
77	act as a nesting container if you need more things to show inside the BBox.
78*/
79
80
81/*!
82	\fn BBox::BBox(BMessage* archive)
83	\brief For archive restoration, allows a BBox to be constructed from an
84		\a archive message.
85
86	This method is usually not called directly. If you want to build a BBox
87	from a message then you should call Instantiate() which can handle errors
88	properly.
89
90	If the \a archive is a deep one, the BBox will also unarchive all
91	of its children recursively.
92
93	\param archive The \a archive to restore from.
94*/
95
96
97/*!
98	\fn BBox::~BBox()
99	\brief Destructor method.
100
101	Calling the destructor will also free the memory used by the box's label
102	if it has one.
103*/
104
105
106/*!
107	\fn static BArchivable*	BBox::Instantiate(BMessage* archive)
108	\brief Creates a new BBox from an \a archive.
109
110	If the message is a valid BBox then an instance of BBox created from the
111	passed in \a archive will be returned. Otherwise this method will
112	return \c NULL.
113
114	\param archive The \a archive message.
115
116	\returns An instance of BBox if the \a archive is valid or \c NULL.
117*/
118
119
120/*!
121	\fn virtual	status_t BBox::Archive(BMessage* archive,
122		bool deep = true) const;
123	\brief Archives the BBox into \a archive.
124
125	\param archive The target \a archive which the BBox data will go
126		into.
127	\param deep Whether or not to recursively archive the children.
128	\returns A status flag indicating if the archive operation was successful.
129
130	\retval B_OK The archive operation was successful.
131	\retval B_BAD_VALUE The archive operation failed.
132*/
133
134
135/*!
136	\fn virtual	void BBox::SetBorder(border_style border)
137	\brief Sets the border style.
138
139	Possible values are \c B_PLAIN_BORDER (a single 1-pixel line border),
140	\c B_FANCY_BORDER (the default, beveled look), and \c B_NO_BORDER, which
141	is used to make an invisible box. See border_style for more details.
142*/
143
144
145/*!
146	\fn border_style BBox::Border() const
147	\brief Gets the current border_style of a BBox.
148
149	\returns The border_style flag that is currently set to the BBox.
150*/
151
152
153/*!
154	\fn float BBox::TopBorderOffset()
155	\brief Gets the distance from the very top of the BBox to the top border
156		line in pixels as a \c float.
157
158	\warning This method is not part of the BeOS R5 API and is not yet
159		finalized.
160
161	The distance may vary depending on the text or view used as label, and the
162	font settings. The border is drawn center aligned with the label. You can
163	use this value to line up two boxes visually if one has a label and the
164	other does not.
165
166	\returns The distance offset of the BBox as a \c float.
167*/
168
169
170/*!
171	\fn BRect BBox::InnerFrame()
172	\brief Gets the rectangle just inside the border of the BBox as a BRect.
173
174	\warning This method is not part of the BeOS R5 API and is not yet
175		finalized.
176
177	\returns A BRect of the dimensions of the box's inside border.
178*/
179
180
181/*!
182	\fn void BBox::SetLabel(const char* string)
183	\brief Sets the box's label text.
184
185	Below is an example of a BBox with a simple text label:
186
187	\image html BBox_example.png
188
189	The code to create a BBox with a text label looks like this:
190
191	\code
192fIconBox = new BBox("Icon Box");
193fIconBox->SetLabel("Icon");
194	\endcode
195
196	\param string The label text string to set as the box's title.
197*/
198
199
200/*!
201	\fn status_t BBox::SetLabel(BView* viewLabel)
202	\brief Sets the label from a pre-existing BView.
203
204	This version of SetLabel() allows building a BBox with a control as a
205	label widget. You can pass in any type of BView derived control for this
206	such as a BPopupMenu or BCheckBox.
207
208	An example of a BBox with a BCheckBox control attached is shown below:
209
210	\image html BBox_with_checkbox.png
211
212	The code to create such a BBox looks like this:
213
214	\code
215fVirtualMemoryEnabledCheckBox = new BCheckBox("Virtual memory check box",
216	"Enable virtual memory", new BMessage(kVirtualMemoryEnabled));
217
218BBox* fVirtualMemoryBox = new BBox("Virtual memory box");
219fVirtualMemoryBox->SetLabel(fVirtualMemoryEnabledCheckBox);
220	\endcode
221
222	\param viewLabel A BView.
223	\returns \c B_OK
224*/
225
226
227/*!
228	\fn const char*	BBox::Label() const
229	\brief Gets the label's text.
230
231	This only works if the label was set as text. If you set another view as the
232	label, you have to get its text by other means, likely starting with
233	LabelView.
234
235	\returns The label text of the BBox as a <tt>const char*</tt> if the BBox
236		has a text label or \c NULL otherwise.
237*/
238
239
240/*!
241	\fn BView*	BBox::LabelView() const
242	\brief Gets the BView representing the label.
243*/
244
245
246/*!
247	\fn virtual	void BBox::Draw(BRect updateRect)
248	\brief Draws onto the parent window the part of the BBox that intersects
249		the dirty area.
250
251	This is an hook method called by the interface kit. You don't have to call
252	it yourself. If you need to force redrawing of (part of) the BBox, consider
253	using Invalidate instead.
254
255	\param updateRect The area that needs to be redrawn. Note the box may draw
256		more around the rectangle.
257*/
258
259
260/*!
261	\fn virtual	void BBox::AttachedToWindow()
262	\brief Hook method called when the BBox is attached to a window.
263
264	This method sets the box's background color to the background of the
265	parent view.
266
267	If you are using the layout system, the BBox is also resized according to
268	the layout of the parent view.
269*/
270
271
272/*!
273	\fn virtual void BBox::FrameResized(float width, float height)
274	\brief Called when the BBox needs to change its size.
275
276	This method may be called either because the window in which the BBox is
277	was resized, or because the window layout was otherwise altered.
278
279	It recomputes the layout of the BBox (including label and contents) and
280	makes it redraw as necessary.
281*/
282
283
284/*!
285	\fn virtual void BBox::ResizeToPreferred()
286	\brief Resizes the BBox to its preferred dimensions.
287
288	This only works in the non-layout mode, as it forces the resizing.
289*/
290
291
292/*!
293	\fn virtual void BBox::GetPreferredSize(float* _width, float* _height)
294	\brief Gets the dimensions that the BBox would prefer to be.
295
296	The size is computed from the children sizes, unless it was explicitly set
297	for the BBox (which can be done only if the BBox is configured to
298	use the Layout Kit).
299
300	\note Either the \a _width or \a _height parameter may be set to \c NULL
301		if you only want to get the other one.
302
303	\param[out] _width The width of the preferred size is placed in here.
304	\param[out] _height The height of the preferred size is placed in here.
305*/
306
307
308/*!
309	\fn virtual	BSize BBox::MinSize()
310	\brief Gets the minimum possible size of the BBox.
311
312	Drawing the BBox at this size ensures the label and the child view are
313	visible. Going smaller means something may get invisible on screen for lack
314	of space.
315*/
316
317
318/*!
319	\fn virtual	BSize BBox::MaxSize()
320	\brief Gets the maximum possible size of the BBox.
321
322	The maximum size depends on the child view's one.
323
324	\returns A BSize of the maximum possible size of the BBox.
325*/
326
327
328/*!
329	\fn virtual	BSize BBox::PreferredSize()
330	\brief Returns the box's preferred size.
331
332	This is the same as GetPreferredSize, but using the more convenient BSize
333	struct.
334
335	\returns A BSize of the minimum possible size of the BBox.
336*/
337
338
339/*!
340	\fn virtual	void BBox::DoLayout()
341	\brief Lays out the BBox. Moves everything into its appropriate position.
342
343	This only works if the BBox uses the layout system from the Layout Kit,
344	i.e. it was created with one of the BRect-less constructors.
345
346	Once the size of the BBox is known, from layouting of the parent views,
347	this method is called so the BBox can adjust the position and size of the
348	label, eventually truncating the text if there is not enough space. The
349	exact border positions are also computed, then the child view is also
350	layouted if its size constraints changed.
351*/
352