1/*
2 * Copyright 2010, 2020 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
4 *
5 * Authors:
6 *		Alex Wilson, yourpalal2@gmail.com
7 *
8 * Corresponds to:
9 *		headers/os/interface/LayoutBuilder.h	 rev 49977
10 */
11
12
13/*!
14	\file LayoutBuilder.h
15	\ingroup layout
16	\ingroup libbe
17	\brief Defines the BLayoutBuilder templates.
18*/
19
20
21/*!
22	\class BLayoutBuilder::Base<>
23	\ingroup layout
24	\brief Base for all other layout builders in the BLayoutBuilder namespace.
25
26	This class provides the stack-like semantics for its subclasses. The
27	BLayoutBuilder::Group, BLayoutBuilder::Grid and BLayoutBuilder::Split all
28	provide methods such as AddGrid() AddGroup() and AddSplit(), which
29	make a new builder, place it on top of your builder stack and return it.
30	Now you are operating on the new builder. When you call	the End() method on
31	the new builder, you are returned the one you had previously been using. At
32	any point, you are calling methods on whatever builder currently resides on
33	the top of the stack. Here's an example of how these classes work.
34
35\code
36BLayoutBuilder::Group<>(B_HORIZONTAL)
37\endcode
38
39	At this point our stack just contains a single builder, it looks like this:
40		\li Group<>
41
42\code
43	.AddGrid()
44\endcode
45
46	Now there is a Grid builder on top of the stack, so it looks like this \li Group<>::GridBuilder
47		\li Group<>
48
49	Notice that the Grid on top of the stack is not a plain Grid<>, but a nested
50	type from the Group<> class. This is an essential part of the builder
51	classes, as this is what allows you to pop builders off the stack and get
52	the correct type in return.
53
54\code
55		.AddSplit()
56\endcode
57
58	Now our stack looks like this:
59		\li Group<>::GridBuilder::SplitBuilder
60		\li Group<>::GridBuilder
61		\li Group<>
62
63	This could continue ad. nauseam, but at some point, you may finish with a
64	builder, and you might want to continue manipulating the builder below it
65	on the stack. To do this, you simply call the End() method like so:
66
67\code
68			.End()
69\endcode
70
71	And now the stack is back to this:
72		\li Group<>::GridBuilder
73		\li Group<>
74
75	So you are again working with the grid builder. You can add more
76	BLayoutItems or BViews, or even more builders. Here's how it will all look
77	together.
78
79\code
80BLayoutBuilder::Group<>(B_HORIZONTAL)
81	// working with the Group builder
82	.AddGrid()
83		// working with the Group<>::GridBuilder
84		.AddSplit()
85			// working with the Group<>::GridBuilder::SplitBuilder
86		.End()
87		// back to the Group<>::GridBuilder
88\endcode
89
90	Note that the C++ language does not impose any sequence points in such
91	method chains. This means the arguments to all calls may be evaluated in an
92	unexpected order. For exemple, the following code may not result in adding
93	the 3 views in rows 0, 1 and 2 in the target grid:
94
95\code
96	// Don't do this!
97	int row = 0;
98	BLayoutBuilder::Grid<>(target)
99		.Add(viewA, row++)
100		.Add(viewB, row++)
101		.Add(viewC, row++);
102\endcode
103
104	\since Haiku R1
105*/
106
107
108/*!
109	\fn void BLayoutBuilder::Base<ParentBuilder>::SetParent(ParentBuilder*
110		parent)
111	\brief Internal method for use by BLayoutBuilder::Base subclasses,
112	       this is essential to the builder stack semantics.
113
114	\since Haiku R1
115*/
116
117
118/*!
119	\fn ParentBuilder& BLayoutBuilder::Base<ParentBuilder>::End()
120	\brief Returns this builder's parent.
121
122	\since Haiku R1
123*/
124
125
126//! \cond INTERNAL
127
128
129/*!
130	\var ParentBuilder* BLayoutBuilder::Base< ParentBuilder >::fParent
131	\brief Internal pointer to the parent of the builder.
132*/
133
134
135//! \endcond
136