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