1/* 2 * Copyright 2020 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Niels Sascha Reedijk, niels.reedijk@gmail.com 7 * 8 * Reviewers: 9 * Adrien Destugues, pulkomandy@pulkomandy.tk 10 * 11 * Corresponds to: 12 * headers/os/interface/LayoutBuilder.h rev 49977 13 */ 14 15 16/*! 17 \class BLayoutBuilder::Cards<> 18 \ingroup layout 19 \ingroup libbe 20 \brief BLayoutBuilder::Base subclass for building BCardLayouts. 21 22 \since Haiku R1 23 24 The BCardLayout class is a simple BLayout subclass that arranges the 25 items as a stack of cards with only one card being on top and visible to 26 the user. 27 28 For a detailed view on the properties, see the \link BCardLayout class 29 description\endlink. 30*/ 31 32 33/*! 34 \typedef BLayoutBuilder::Cards<ParentBuilder>::ThisBuilder 35 \brief Shorthand representing the type of \c this. 36 37 \since Haiku R1 38*/ 39 40 41/*! 42 \typedef BLayoutBuilder::Cards<ThisBuilder>::GroupBuilder 43 \brief Shorthand for builders returned by this builder's AddGroup() methods. 44 45 \since Haiku R1 46*/ 47 48 49/*! 50 \typedef BLayoutBuilder::Cards<ThisBuilder>::GridBuilder 51 \brief Shorthand for builders returned by this builder's AddGrid() methods. 52 53 \since Haiku R1 54*/ 55 56 57/*! 58 \typedef BLayoutBuilder::Cards<ThisBuilder>::SplitBuilder 59 \brief Shorthand for builders returned by this builder's AddSplit() methods. 60 61 \since Haiku R1 62*/ 63 64 65/*! 66 \typedef BLayoutBuilder::Cards<ThisBuilder>::CardBuilder 67 \brief Shorthand for builders returned by this builder's AddCards() 68 methods. 69 70 \since Haiku R1 71*/ 72 73 74/*! 75 \name Constructors 76*/ 77 78 79//! @{ 80 81 82/*! 83 \fn BLayoutBuilder::Cards<ParentBuilder>::Cards() 84 \brief Creates a builder for BCardLayout. 85 86 \since Haiku R1 87*/ 88 89 90/*! 91 \fn BLayoutBuilder::Cards<ParentBuilder>::Cards(BWindow* window) 92 \brief Creates a new builder for BCardLayout, and attaches it to a 93 \a window. 94 95 \since Haiku R1 96*/ 97 98 99/*! 100 \fn BLayoutBuilder::Cards<ParentBuilder>::Cards(BView* view) 101 \brief Creates a new builder for BCardLayout, and attaches it to a 102 \a view. 103 104 \since Haiku R1 105*/ 106 107 108/*! 109 \fn BLayoutBuilder::Cards<ParentBuilder>::Cards(BCardLayout* layout) 110 \brief Creates a builder targeting an existing BCardLayout. 111 112 \since Haiku R1 113*/ 114 115 116/*! 117 \fn BLayoutBuilder::Cards<ParentBuilder>::Cards(BCardLayout* layout) 118 \brief Creates a builder targeting an existing BCardView. 119 120 \since Haiku R1 121*/ 122 123 124//! @} 125 126 127/*! 128 \name Accessors 129*/ 130 131 132//! @{ 133 134 135/*! 136 \fn BCardLayout* BLayoutBuilder::Cards<ParentBuilder>::Layout() const 137 \brief Get a pointer to the underlying BCardLayout 138 139 \returns A pointer to the underlying BCardLayout 140 141 \since Haiku R1 142*/ 143 144 145/*! 146 \fn BView* BLayoutBuilder::Cards<ParentBuilder>::View() const 147 \brief Get a pointer to the underlying BView. 148 149 \returns A pointer to the underlying BView 150 151 \since Haiku R1 152*/ 153 154/*! 155 \fn ThisBuilder& BLayoutBuilder::Cards<ParentBuilder>::GetLayout( 156 BCardLayout** _layout) 157 \brief Get a pointer to the underlying view. 158 159 \param[out] _layout Location to store the underlying BCardView reference. 160 161 \return The method returns a self reference, so that calls to the builder 162 may be chained. 163 164 \since Haiku R1 165*/ 166 167 168/*! 169 \fn ThisBuilder& BLayoutBuilder::Cards<ParentBuilder>::GetView( 170 BView** _view) 171 \brief Get a pointer to the underlying view. 172 173 \param[out] _view Location to store the underlying BView reference. 174 175 \return The method returns a self reference, so that calls to the builder 176 may be chained. 177 178 \since Haiku R1 179*/ 180 181 182/*! 183 \fn BLayoutBuilder::Cards<ParentBuilder>::operator BCardLayout*() 184 \brief Cast this builder into the BCardLayout it represents. 185 186 \since Haiku R1 187*/ 188 189//! @} 190 191 192/*! 193 \name Adding BViews and BLayoutItems 194*/ 195 196 197//! @{ 198 199 200/*! 201 \fn ThisBuilder& BLayoutBuilder::Cards<ParentBuilder>::Add(BView* view) 202 \brief Add a \a view to the underlying BCardLayout. 203 204 The layout item will be added as a card at the end of the stack. 205 206 \param view The BView to be added. The underlying BCardLayout will take 207 ownership of the object. 208 209 \since Haiku R1 210*/ 211 212 213/*! 214 \fn ThisBuilder& BLayoutBuilder::Cards<ParentBuilder>::Add( 215 BLayoutItem* item) 216 \brief Add a \a item to the underlying BCardLayout. 217 218 The layout item will be added as a card at the end of the stack. 219 220 \param item The BLayoutItem to be added. The underlying BCardLayout will 221 take ownership of the object. 222 223 \since Haiku R1 224*/ 225 226 227//! @} 228 229 230/*! 231 \name Adding BLayouts and their BView Pairs 232 233 A set of methods that add a BLayout or BView subclass and return a 234 BLayoutBuilder::Base subclass representing the newly added object. These 235 methods push a new builder on top of the stack, you will not be using 236 \c this builder again until you call End(). 237*/ 238 239 240//! @{ 241 242 243/*! 244 \fn GroupBuilder BLayoutBuilder::Cards<ParentBuilder>::AddGroup( 245 orientation orientation, float spacing) 246 \brief Construct and add a viewless BGroupLayout, then return a GroupBuilder 247 representing the newly added layout. 248 249 \param orientation The orientation to use for the new BGroupLayout. 250 \param spacing The spacing to use for the new BGroupLayout. 251 252 \returns A GroupBuilder representing the newly created BGroupLayout. 253 254 \since Haiku R1 255*/ 256 257 258/*! 259 \fn GroupBuilder BLayoutBuilder::Cards<ParentBuilder>::AddGroup( 260 BGroupView* groupView) 261 \brief Add BGroupView and return a builder representing the newly added 262 BGroupView. 263 264 \param groupView The BGroupView to be added. 265 266 \returns A GroupBuilder representing \a groupView. 267 268 \since Haiku R1 269*/ 270 271 272/*! 273 \fn GroupBuilder BLayoutBuilder::Cards<ParentBuilder>::AddGroup( 274 BGroupLayout* groupLayout) 275 \brief Add a BGroupLayout and return a builder representing the newly added 276 BGroupLayout. 277 278 \param groupLayout The BGroupLayout to be added. 279 280 \returns A GroupBuilder representing \a groupLayout. 281 282 \since Haiku R1 283*/ 284 285 286/*! 287 \fn GridBuilder BLayoutBuilder::Cards<ParentBuilder>::AddGrid( 288 float horizontalSpacing, float verticalSpacing) 289 \brief Create and add a viewless BGridLayout, then return a builder 290 representing the newly created BGridLayout. 291 292 \param horizontalSpacing The horizontal spacing for the new BGridLayout. 293 \param verticalSpacing The vertical spacing for the new BGridLayout. 294 295 \returns A GridBuilder representing the newly created BGridLayout. 296 297 \since Haiku R1 298*/ 299 300 301/*! 302 \fn GridBuilder BLayoutBuilder::Cards<ParentBuilder>::AddGrid( 303 BGridLayout* gridLayout) 304 \brief Add a BGridLayout, then return a builder the newly added BGridLayout. 305 306 \param gridLayout The BGridLayout to be added and used to construct the 307 returned GridBuilder. 308 309 \returns A GridBuilder representing \a gridLayout. 310 311 \since Haiku R1 312*/ 313 314 315/*! 316 \fn GridBuilder BLayoutBuilder::Cards<ParentBuilder>::AddGrid( 317 BGridView* gridView) 318 \brief Add a BGridView, then return a builder the newly added BGridView. 319 320 \param gridView The BGridView to be added and used to construct the 321 returned GridBuilder. 322 323 \returns A GridBuilder representing \a gridView. 324 325 \since Haiku R1 326*/ 327 328 329/*! 330 \fn SplitBuilder BLayoutBuilder::Cards<ParentBuilder>::AddSplit( 331 orientation orientation, float spacing) 332 \brief Create and add a new BSplitView with a weight of \c weight, then 333 return a SplitBuilder representing the new BSplitView. 334 335 \param orientation The orientation of the new BSplitView. 336 \param spacing The spacing of the new BSplitView. 337 338 \returns A SplitBuilder representing the new BSplitView. 339 340 \since Haiku R1 341*/ 342 343 344/*! 345 \fn SplitBuilder BLayoutBuilder::Cards<ParentBuilder>::AddSplit( 346 BSplitView* splitView) 347 \brief Add a BSplitView to the BSplitView this builder represents and 348 return a SplitBuilder representing the BSplitView. 349 350 \param splitView The BSplitView to be added. 351 352 \returns A SplitBuilder representing the new BSplitView. 353 354 \since Haiku R1 355*/ 356 357 358/*! 359 \fn CardBuilder BLayoutBuilder::Cards<ParentBuilder>::AddCards() 360 \brief Add a new BCardLayout as a child of the BCardLayout this builder 361 represents and return a CardBuilder representing the new layout. 362 363 \returns A CardBuilder representing the new BCardLayout. 364 365 \since Haiku R1 366*/ 367 368 369/*! 370 \fn CardBuilder BLayoutBuilder::Cards<ParentBuilder>::AddCards( 371 BCardLayout* cardLayout) 372 \brief Add a new BCardLayout as a child of the BCardLayout this builder 373 represents and return a CardBuilder representing the new layout. 374 375 \param cardLayout The existing layout that will be added to the underlying 376 BSplitView. 377 378 \returns A CardBuilder representing the new BCardLayout. 379 380 \since Haiku R1 381*/ 382 383 384/*! 385 \fn CardBuilder BLayoutBuilder::Cards<ParentBuilder>::AddCards( 386 BCardView* cardView) 387 \brief Add a new BCardLayout as a child of the BCardLayout this builder 388 represents and return a CardBuilder representing the new layout. 389 390 \param cardView The existing view that will be added to the underlying 391 BSplitView. 392 393 \returns A CardBuilder representing the new BCardLayout. 394 395 \since Haiku R1 396*/ 397 398 399 400//! @} 401 402 403/*! 404 \name Setting Explicit Sizes 405*/ 406 407 408//! @{ 409 410 411/*! 412 \fn ThisBuilder& BLayoutBuilder::Cards<ParentBuilder>::SetExplicitMinSize( 413 BSize size) 414 \brief Set the explicit minimum size of the underlying layout item. 415 416 \since Haiku R1 417*/ 418 419 420/*! 421 \fn ThisBuilder& BLayoutBuilder::Cards<ParentBuilder>::SetExplicitMaxSize( 422 BSize size) 423 \brief Set the explicit maximum size of the underlying layout item. 424 425 \since Haiku R1 426*/ 427 428 429/*! 430 \fn ThisBuilder& BLayoutBuilder::Cards<ParentBuilder>::SetExplicitPreferredSize( 431 BSize size) 432 \brief Set the explicit preferred size of the underlying layout item. 433 434 \since Haiku R1 435*/ 436 437 438/*! 439 \fn ThisBuilder& BLayoutBuilder::Cards<ParentBuilder>::SetExplicitAlignment( 440 BAlignment alignment) 441 \brief Set the explicit alignment of the underlying layout item. 442 443 \since Haiku R1 444*/ 445 446 447//! @} 448 449 450/*! 451 \name Visible Item 452*/ 453 454 455//! @{ 456 457 458/*! 459 \fn ThisBuilder& BLayoutBuilder::Cards<ParentBuilder>::SetVisibleItem( 460 int32 index) 461 \brief Set the current visible item to the item at \a index. 462 463 \see BCardLayout::SetVisibleItem(int32) 464*/ 465 466 467//! @} 468