1/*
2 * Copyright 2011, 2020 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
4 *
5 * Authors:
6 *		John Scipione, jscipione@gmail.com
7 *		Ingo Weinhold, bonefish@cs.tu-berlin.de
8 *		Niels Sascha Reedijk, niels.reedijk@gmail.com
9 *
10 * Corresponds to:
11 *		headers/os/interface/LayoutBuilder.h	 rev 49977
12 */
13
14
15/*!
16	\class BLayoutBuilder::Group<>
17	\ingroup layout
18	\ingroup libbe
19	\brief BLayoutBuilder::Base subclass for building BGroupLayouts.
20
21	\since Haiku R1
22*/
23
24
25/*!
26	\typedef BLayoutBuilder::Group<ParentBuilder>::ThisBuilder
27	\brief Shorthand representing the type of \c this.
28
29	\since Haiku R1
30*/
31
32
33/*!
34	\typedef BLayoutBuilder::Group<ParentBuilder>::GroupBuilder
35	\brief Shorthand for builders returned by this builder's AddGroup() methods.
36
37	\since Haiku R1
38*/
39
40
41/*!
42	\typedef BLayoutBuilder::Group<ParentBuilder>::GridBuilder
43	\brief Shorthand for builders returned by this builder's AddGrid() methods.
44
45	\since Haiku R1
46*/
47
48
49/*!
50	\typedef BLayoutBuilder::Group<ParentBuilder>::SplitBuilder
51	\brief Shorthand for builders returned by this builder's AddSplit() methods.
52
53	\since Haiku R1
54*/
55
56
57/*!
58	\typedef BLayoutBuilder::Group<ThisBuilder>::CardBuilder
59	\brief Shorthand for builders returned by this builder's AddCards()
60		methods.
61
62	\since Haiku R1
63*/
64
65
66/*!
67	\name Constructors
68*/
69
70
71//! @{
72
73
74/*!
75	\fn BLayoutBuilder::Group<ParentBuilder>::Group(BWindow *window,
76		orientation orientation, float spacing)
77	\brief Creates a new BGroupLayout, and attaches it to a BWindow.
78
79	\note The top BView* in \a window has its ViewColor set to
80	      \c B_PANEL_BACKGROUND_COLOR.
81	\param window The BWindow* to attach the newly created BGroupLayout to.
82	\param orientation The orientation for the new BGroupLayout.
83	\param spacing The spacing for the new BGroupLayout.
84
85	\since Haiku R1
86*/
87
88
89/*!
90	\fn BLayoutBuilder::Group<ParentBuilder>::Group(BView* view,
91		orientation orientation, float spacing)
92	\brief Creates a builder targeting an existing \a view.
93
94	\param view The BView* to attach the newly created BGroupLayout to.
95	\param orientation The orientation for the new BGroupLayout.
96	\param spacing The spacing for the new BGroupLayout.
97
98	\since Haiku R1
99*/
100
101
102/*!
103	\fn BLayoutBuilder::Group<ParentBuilder>::Group(BGroupLayout* layout)
104	\brief Creates a builder targeting a BGroupLayout.
105
106	Methods called on this builder will be directed to \a layout.
107
108	\param layout The BGroupLayout to target with this builder.
109
110	\since Haiku R1
111*/
112
113
114/*!
115	\fn BLayoutBuilder::Group<ParentBuilder>::Group(BGroupView* view)
116	\brief Creates a builder targeting a BGroupView.
117
118	Methods called on this builder will be directed to
119	\c view->GroupLayout().
120
121	\param view The BGroupView this builder will target.
122
123	\since Haiku R1
124*/
125
126
127/*!
128	\fn BLayoutBuilder::Group<ParentBuilder>::Group(
129		orientation orientation, float spacing)
130	\brief Creates a new BGroupView and targets it.
131
132	Methods called on this builder will be directed to the new BGroupView's
133	BGroupLayout.
134
135	\param orientation The orientation for the new BGroupView.
136	\param spacing The spacing for the new BGroupView.
137
138	\since Haiku R1
139*/
140
141
142//! @}
143
144
145/*!
146	\name Adding BViews and BLayoutItems
147*/
148
149
150//! @{
151
152
153/*!
154	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::Add(BView* view)
155	\brief Add a BView to the BGroupLayout this builder represents.
156
157	\param view The BView to be added.
158	\see BGroupLayout::AddView(BView*)
159
160	\since Haiku R1
161*/
162
163
164/*!
165	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::Add(BView* view,
166		float weight)
167	\brief Add BView to the BGroupLayout this builder represents.
168
169	\param view The BView to be added.
170	\param weight The weight to give \a view.
171
172	\see BGroupLayout::AddView(BView* view, float weight)
173
174	\since Haiku R1
175*/
176
177
178/*!
179	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::Add(
180		BLayoutItem* item)
181	\brief Add a BLayoutItem to the BGroupLayout this builder represents.
182
183	\param item The BLayoutItem to be added.
184
185	\see BGroupLayout::AddItem(BLayoutItem*)
186
187	\since Haiku R1
188*/
189
190
191/*!
192	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::Add(BLayoutItem*
193		item, float weight)
194	\brief Add a BLayoutItem the BGroupLayout this builder represents.
195
196	\param item The BLayoutItem to be added.
197	\param weight The weight to give \a item.
198	\see BGroupLayout::AddItem(BLayoutItem* item, float weight)
199
200	\since Haiku R1
201*/
202
203
204//! @}
205
206
207/*!
208	\name Adding BLayouts and their BView Pairs
209
210	A set of methods that add a BLayout or BView subclass and return a
211	BLayoutBuilder::Base subclass representing the newly added object. These
212	methods push a new builder on top of the stack, you will not be using
213	\c this builder again until you call End().
214*/
215
216
217//! @{
218
219
220/*!
221	\fn GroupBuilder BLayoutBuilder::Group<ParentBuilder>::AddGroup(
222		orientation orientation, float spacing, float weight)
223	\brief Add a new viewless BGroupLayout as a child to the layout that this
224		builder represents and return a GroupBuilder representing the new
225		layout.
226
227	\param orientation The orientation to use for the new BGroupLayout.
228	\param spacing The spacing to use for the new BGroupLayout.
229	\param weight The weight for the new BGroupLayout in this group layout.
230
231	\returns A GroupBuilder representing the newly created BGroupLayout.
232
233	\since Haiku R1
234*/
235
236
237/*!
238	\fn GroupBuilder BLayoutBuilder::Group<ParentBuilder>::AddGroup(BGroupView*
239		groupView, float weight)
240	\brief Add an existing BGroupView as a child to the layout that this
241		builder represents and return a GroupBuilder representing the layout of
242		the added \a groupView.
243
244	\param groupView The BGroupView to be added.
245	\param weight The weight for \a groupView in this group layout.
246
247	\returns A GroupBuilder representing the layout of the \a groupView.
248
249	\since Haiku R1
250*/
251
252
253/*!
254	\fn GroupBuilder BLayoutBuilder::Group<ParentBuilder>::AddGroup(
255		BGroupLayout* groupLayout, float weight)
256	\brief Add an existing BGroupLayout as a child to the layout that this
257		builder represents and return a GroupBuilder to the added layout.
258
259	\param groupLayout The BGroupLayout to be added.
260	\param weight The weight for \a groupLayout in this group layout.
261
262	\returns A GroupBuilder representing the \a groupLayout.
263
264	\since Haiku R1
265*/
266
267
268/*!
269	\fn GridBuilder BLayoutBuilder::Group<ParentBuilder>::AddGrid(
270		float horizontalSpacing, float verticalSpacing, float weight)
271	\brief Add a new viewless BGridLayout as a child to the layout that this
272		builder represents and return a GridBuilder representing the new
273		layout.
274
275	\param horizontalSpacing The horizontal spacing for the new BGridLayout.
276	\param verticalSpacing The vertical spacing for the new BGridLayout.
277	\param weight The weight for the new BGroupLayout in the BGroupLayout this
278		builder represents.
279
280	\returns A GridBuilder representing the newly created BGridLayout.
281
282	\since Haiku R1
283*/
284
285
286/*!
287	\fn GridBuilder BLayoutBuilder::Group<ParentBuilder>::AddGrid(
288		BGridLayout* gridLayout, float weight)
289	\brief Add an existing BGridLayout as a child to the layout that this
290		builder represents and return a GridBuilder to the added layout.
291
292	\param gridLayout The BGridLayout to be added.
293	\param weight The weight for \a gridLayout in the BGroupLayout this builder
294		represents.
295
296	\returns A GridBuilder representing \a gridLayout.
297
298	\since Haiku R1
299*/
300
301
302/*!
303	\fn GridBuilder	BLayoutBuilder::Group<ParentBuilder>::AddGrid(
304		BGridView* gridView, float weight)
305	\brief Add an existing BGridView as a child to the layout this builder
306		represents and return a GridBuilder representing the layout of the
307		added \a gridView.
308
309	\param gridView The BGridView to be added.
310	\param weight The weight for \a gridView in this BGroupLayout.
311
312	\returns A GridBuilder representing the layout of the \a gridView.
313
314	\since Haiku R1
315*/
316
317
318/*!
319	\fn SplitBuilder BLayoutBuilder::Group<ParentBuilder>::AddSplit(
320		orientation orientation, float spacing, float weight)
321	\brief Add a new BSplitView as a child to the layout that this builder
322		represents and return a SplitBuilder representing the new BSplitView.
323
324	\param orientation The orientation of the new BSplitView.
325	\param spacing The spacing of the new BSplitView.
326	\param weight The weight, in this BGroupLayout for the new BSplitView.
327
328	\returns A SplitBuilder representing the new BSplitView.
329
330	\since Haiku R1
331*/
332
333
334/*!
335	\fn SplitBuilder BLayoutBuilder::Group<ParentBuilder>::AddSplit(
336		BSplitView* splitView, float weight = 1.0f)
337	\brief Add an existing BSplitView as a child to the layout this builder
338		represents and return a SplitBuilder representing the layout of the
339		added \a splitView.
340
341	\param splitView The BSplitView to be added.
342	\param weight The weight of the BSplitView in the BGroupLayout this builder
343		represents.
344
345	\returns A SplitBuilder representing the \a splitView.
346
347	\since Haiku R1
348*/
349
350
351/*!
352	\fn CardBuilder BLayoutBuilder::Group<ParentBuilder>::AddCards(
353		float weight)
354	\brief Add a new viewless BCardLayout as a child to the layout that this
355		builder represents and return a CardBuilder representing the new layout.
356
357	\param weight The weight of this new layout within the current group layout.
358
359	\returns A CardBuilder representing the new BCardLayout.
360
361	\since Haiku R1
362*/
363
364
365/*!
366	\fn CardBuilder BLayoutBuilder::Group<ParentBuilder>::AddCards(
367		BCardLayout* cardLayout, float weight)
368	\brief Add an existing BCardLayout as a child to the layout that this builder
369		represents and return a CardBuilder representing the added layout.
370
371	\param cardLayout The existing layout to add to the current group layout.
372	\param weight The weight of this new layout within the current group
373		layout.
374
375	\returns A CardBuilder representing the \a cardLayout.
376
377	\since Haiku R1
378*/
379
380
381/*!
382	\fn CardBuilder BLayoutBuilder::Group<ParentBuilder>::AddCards(
383		BCardView* cardView, float weight)
384	\brief Add an existing BCardView as a child to the layout that this builder
385		represents and return a CardBuilder representing the layout of the
386		added BCardView.
387
388	\param cardView The existing BCardView to add to the current group layout.
389	\param weight The weight of this new layout within the current group layout.
390
391	\returns A CardBuilder representing the layout of the \a cardView.
392
393	\since Haiku R1
394*/
395
396
397//! @}
398
399
400/*!
401	\name Adding BSpaceLayoutItems
402
403	Some convenience methods for adding special BSpaceLayoutItems.
404*/
405
406
407//! @{
408
409
410/*!
411	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::AddGlue(
412		float weight)
413	\brief Add a BSpaceLayoutItem created by BSpaceLayoutItem::CreateGlue()
414		to the builder's layout.
415
416	\param weight The weight of the BSpaceLayoutItem in the BGroupLayout this
417		builder represents
418
419	\since Haiku R1
420*/
421
422
423/*!
424	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::AddStrut(float size)
425	\brief Add a BSpaceLayoutItem created by
426	      BSpaceLayoutItem::CreateHorizontalStrut() or
427	      BSpaceLayoutItem::CreateVerticalStrut() to the BGroupLayout
428	      this builder represents.
429
430	\param size The width or height of the strut to be created (depending on
431		the orientation of the BGroupLayout this builder represents).
432
433	\since Haiku R1
434*/
435
436
437//!@}
438
439
440/*!
441	\name Insets
442*/
443
444
445//! @{
446
447
448/*!
449	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::SetInsets(
450		float left, float top, float right, float bottom)
451	\copydoc BTwoDimensionalLayout::SetInsets(float, float, float, float)
452*/
453
454
455/*!
456	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::SetInsets(
457		float horizontal, float vertical)
458	\copydoc BTwoDimensionalLayout::SetInsets(float, float)
459*/
460
461
462/*!
463	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::SetInsets(
464		float insets)
465	\copydoc BTwoDimensionalLayout::SetInsets(float)
466*/
467
468
469//! @}
470
471
472/*!
473	\name Explicit Sizes and Alignment
474*/
475
476
477//! @{
478
479
480/*!
481	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::SetExplicitMinSize(
482		BSize size)
483	\brief Set the explicit minimum size of the underlying layout.
484
485	\since Haiku R1
486*/
487
488
489/*!
490	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::SetExplicitMaxSize(
491		BSize size)
492	\brief Set the explicit maximum size of the underlying layout.
493
494	\since Haiku R1
495*/
496
497
498/*!
499	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::SetExplicitPreferredSize(
500		BSize size)
501	\brief Set the explicit preferred size of the underlying layout.
502
503	\since Haiku R1
504*/
505
506
507/*!
508	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::SetExplicitAlignment(
509		BAlignment alignment)
510	\brief Set the explicit alignment of the underlying layout.
511
512	\since Haiku R1
513*/
514
515
516//! @}
517
518
519/*!
520	\name Accessors
521*/
522
523
524//! @{
525
526
527/*!
528	\fn BGroupLayout* BLayoutBuilder::Group<ParentBuilder>::Layout() const
529	\brief Get a pointer to the layout this builder represents.
530
531	\since Haiku R1
532*/
533
534
535/*!
536	\fn BView* BLayoutBuilder::Group<ParentBuilder>::View() const
537	\brief Get a pointer to the BView this builder's layout is attached to.
538
539	\since Haiku R1
540*/
541
542
543/*!
544	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::GetLayout(
545		BGroupLayout** _layout)
546	\brief Get the layout this builder represents.
547
548	\param[out] _layout The layout this builder represents.
549
550	\since Haiku R1
551*/
552
553
554/*!
555	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::GetView(
556		BView** _view)
557	\brief Get a pointer to the BView this builder's layout is attached to.
558
559	\param[out] _view The BView this builder's layout is attached to.
560
561	\since Haiku R1
562*/
563
564
565/*!
566	\fn BLayoutBuilder::Group<ParentBuilder>::operator BGroupLayout*()
567	\brief Cast this builder into the layout object it represents.
568
569	\since Haiku R1
570*/
571
572
573//!@}
574