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