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