1/* 2 * Copyright 2017, 2020 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Adrien Destugues, pulkomandy@pulkomandy.tk 7 * 8 * Corresponds to: 9 * headers/os/interface/LayoutBuilder.h rev 49977 10 */ 11 12 13/*! 14 \class BLayoutBuilder::Grid<> 15 \ingroup layout 16 \ingroup libbe 17 \brief BLayoutBuilder::Base subclass for building BGridLayouts. 18 19 \since Haiku R1 20 21 Each item is added to the grid layout at (column, row) and may span multiple 22 columns and rows. 23*/ 24 25 26/*! 27 \typedef BLayoutBuilder::Grid<ParentBuilder>::ThisBuilder 28 \copydoc BLayoutBuilder::Group<ParentBuilder>::ThisBuilder 29*/ 30 31 32/*! 33 \typedef BLayoutBuilder::Grid<ParentBuilder>::GroupBuilder 34 \copydoc BLayoutBuilder::Group<ParentBuilder>::GroupBuilder 35*/ 36 37 38/*! 39 \typedef BLayoutBuilder::Grid<ParentBuilder>::GridBuilder 40 \copydoc BLayoutBuilder::Group<ParentBuilder>::GridBuilder 41*/ 42 43 44/*! 45 \typedef BLayoutBuilder::Grid<ParentBuilder>::SplitBuilder 46 \copydoc BLayoutBuilder::Group<ParentBuilder>::SplitBuilder 47*/ 48 49 50/*! 51 \typedef BLayoutBuilder::Grid<ThisBuilder>::CardBuilder 52 \copydoc BLayoutBuilder::Group<ThisBuilder>::CardBuilder 53*/ 54 55 56/*! 57 \name Constructors 58*/ 59 60 61//! @{ 62 63 64/*! 65 \fn BLayoutBuilder::Grid<ParentBuilder>::Grid(BWindow *window, 66 float horizontal, float vertical) 67 \brief Creates a new BGridLayout, and attaches it to a BWindow. 68 69 \note The top BView* in \a window has its ViewColor set to 70 \c B_PANEL_BACKGROUND_COLOR. 71 \param window Thew BWindow* to attach the newly created BGroupLayout to. 72 \param horizontal The horizontal spacing for the new BGridLayout. 73 \param vertical The vertical spacing for the new BGridLayout. 74 75 \since Haiku R1 76*/ 77 78 79/*! 80 \fn BLayoutBuilder::Grid<ParentBuilder>::Grid(BView* view, 81 float horizontal, float vertical) 82 \brief Creates a builder targeting an existing \a view. 83 84 \param view The BView* to attach the newly created BGridLayout to. 85 \param horizontal The horizontal spacing for the new BGridLayout. 86 \param vertical The vertical spacing for the new BGroupLayout. 87 88 \since Haiku R1 89*/ 90 91 92/*! 93 \fn BLayoutBuilder::Grid<ParentBuilder>::Grid(BGridLayout* layout) 94 \brief Creates a builder targeting an existing BGridLayout. 95 96 Methods called on this builder will be directed to \a layout. 97 98 \param layout The BGridLayout to target with this builder. 99 100 \since Haiku R1 101*/ 102 103 104/*! 105 \fn BLayoutBuilder::Grid<ParentBuilder>::Grid(BGridView* view) 106 \brief Creates a builder targeting a BGridView. 107 108 Methods called on this builder will be directed to 109 \c view->GridLayout(). 110 111 \param view The BGridView this builder will target. 112 113 \since Haiku R1 114*/ 115 116 117/*! 118 \fn BLayoutBuilder::Grid<ParentBuilder>::Grid( 119 float horizontal, float vertical) 120 \brief Creates a new BGridView and targets it. 121 122 Methods called on this builder will be directed to the new BGridView's 123 BGridLayout. 124 125 \param horizontal The horizontal spacing for the new BGridLayout. 126 \param vertical The vertical spacing for the new BGridLayout. 127 128 \since Haiku R1 129*/ 130 131 132//! @} 133 134 135/*! 136 \name Accessors 137*/ 138 139 140//! @{ 141 142 143/*! 144 \fn BGridLayout* BLayoutBuilder::Grid<ParentBuilder>::Layout() const 145 \copydoc BLayoutBuilder::Group<ParentBuilder>::Layout() 146*/ 147 148 149/*! 150 \fn BView* BLayoutBuilder::Grid<ParentBuilder>::View() const 151 \copydoc BLayoutBuilder::Group<ParentBuilder>::View() 152*/ 153 154 155/*! 156 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::GetLayout( 157 BGridLayout** _layout) 158 \copydoc BLayoutBuilder::Group<ParentBuilder>::GetLayout() 159*/ 160 161 162/*! 163 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::GetView( 164 BView** _view) 165 \copydoc BLayoutBuilder::Group<ParentBuilder>::GetView() 166*/ 167 168 169/*! 170 \fn BLayoutBuilder::Grid<ParentBuilder>::operator BGridLayout*() 171 \brief Cast this builder into the layout object it represents. 172 173 \since Haiku R1 174*/ 175 176 177//! @} 178 179 180/*! 181 \name Adding BViews and BLayoutItems 182*/ 183 184 185//! @{ 186 187 188/*! 189 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::Add(BView* view, 190 int32 column, int32 row, int32 columnCount, int32 rowCount) 191 \brief Add a BView to the BGridLayout this builder represents. 192 193 \param view The BView to be added. 194 \param column The column number (zero-index) to use. 195 \param row The row number (zero-index) to use. 196 \param columnCount The number of columns to span over. 197 \param rowCount The number of rows to span over. 198 199 \see BGridLayout::AddView(BView*) 200 201 \since Haiku R1 202*/ 203 204 205/*! 206 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::Add( 207 BLayoutItem* item, int32 column, int32 row, 208 int32 columnCount, int32 rowCount) 209 \brief Add a BLayoutItem to the BGridLayout this builder represents. 210 211 \param item The BLayoutItem to be added. 212 \param column The column number (zero-index) to use. 213 \param row The row number (zero-index) to use. 214 \param columnCount The number of columns to span over. 215 \param rowCount The number of rows to span over. 216 217 \see BGridLayout::AddItem(BLayoutItem*) 218 219 \since Haiku R1 220*/ 221 222 223/*! 224 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::AddMenuField( 225 BMenuField* item, int32 column, int32 row, alignment labelAlignment, 226 int32 labelColumnCount, int32 fieldColumnCount, int32 rowCount) 227 \brief Add a BMenuField to the layout. 228 229 \param item The BMenuField to be added. 230 \param column The column number (zero-index) to use. 231 \param row The row number (zero-index) to use. 232 \param labelAlignment The alignment of the label to use. Choices include: 233 - \c B_ALIGN_LEFT 234 - \c B_ALIGN_RIGHT 235 - \c B_ALIGN_CENTER 236 - \c B_ALIGN_HORIZONTAL_CENTER 237 - \c B_ALIGN_HORIZONTAL_UNSET 238 - \c B_ALIGN_USE_FULL_WIDTH 239 \param labelColumnCount The number of columns the label will span over. 240 \param fieldColumnCount The number of columns the menu field will span over. 241 \param rowCount The number of rows to span over. 242 243 A BMenuField is composed of a label and a menu. This method allows to 244 lay the sub-components in separate grid cells, allowing easy alignment 245 of the menu with other items in the layout. 246 247 \since Haiku R1 248*/ 249 250 251/*! 252 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::AddTextControl( 253 BTextControl* item, int32 column, int32 row, alignment labelAlignment, 254 int32 labelColumnCount, int32 textColumnCount, int32 rowCount) 255 \brief Add a BMenuField to the layout 256 257 \param item The BMenuField to be added. 258 \param column The column number (zero-index) to use. 259 \param row The row number (zero-index) to use. 260 \param labelAlignment The alignment of the label to use. Choices include: 261 - \c B_ALIGN_LEFT 262 - \c B_ALIGN_RIGHT 263 - \c B_ALIGN_CENTER 264 - \c B_ALIGN_HORIZONTAL_CENTER 265 - \c B_ALIGN_HORIZONTAL_UNSET 266 - \c B_ALIGN_USE_FULL_WIDTH 267 \param labelColumnCount The number of columns the label will span over. 268 \param textColumnCount The number of columns the text field will span over. 269 \param rowCount The number of rows to span over. 270 271 A BTextControl is composed of a label and a text area. This method allows to 272 lay the sub-components in separate grid cells, allowing easy alignment 273 of the text area with other items in the layout. 274 275 \since Haiku R1 276*/ 277 278 279//! @} 280 281 282/*! 283 \name Adding BLayouts and their BView Pairs 284 285 A set of methods that add a BLayout or BView subclass and return a 286 BLayoutBuilder::Base subclass representing the newly added object. These 287 methods push a new builder on top of the stack, you will not be using 288 \c this builder again until you call End(). 289*/ 290 291 292//! @{ 293 294 295/*! 296 \fn GroupBuilder BLayoutBuilder::Grid<ParentBuilder>::AddGroup( 297 orientation orientation, float spacing, int32 column, int32 row, 298 int32 columnCount, int32 rowCount) 299 \copybrief GroupBuilder BLayoutBuilder::Group<ParentBuilder>::AddGroup( 300 orientation orientation, float spacing, float weight) 301 302 \param orientation The orientation to use for the new BGroupLayout. 303 \param spacing The spacing to use for the new BGroupLayout. 304 \param column The column number (zero-index) to use. 305 \param row The row number (zero-index) to use. 306 \param columnCount The number of columns to span the new BGroupLayout over. 307 \param rowCount The number of rows to span the new BGroupLayout over. 308 309 \returns A GroupBuilder representing the newly created BGroupLayout. 310 311 \since Haiku R1 312*/ 313 314 315/*! 316 \fn GroupBuilder BLayoutBuilder::Grid<ParentBuilder>::AddGroup( 317 BGroupView* groupView, int32 column, int32 row, int32 columnCount, 318 int32 rowCount = 1) 319 \copybrief GroupBuilder BLayoutBuilder::Group<ParentBuilder>::AddGroup(BGroupView* 320 groupView, float weight) 321 322 \param groupView The BGroupView to be added. 323 \param column The column number (zero-index) to use. 324 \param row The row number (zero-index) to use. 325 \param columnCount The number of columns to span the \a groupView over. 326 \param rowCount The number of rows to span the \a groupView over. 327 328 \returns A GroupBuilder representing the layout of the \a groupView. 329 330 \since Haiku R1 331*/ 332 333 334/*! 335 \fn GroupBuilder BLayoutBuilder::Grid<ParentBuilder>::AddGroup( 336 BGroupLayout* groupLayout, int32 column, int32 row, 337 int32 columnCount, int32 rowCount) 338 \copybrief GroupBuilder BLayoutBuilder::Group<ParentBuilder>::AddGroup( 339 BGroupLayout* groupLayout, float weight) 340 341 \param groupLayout The BGroupLayout to be added. 342 \param column The column number (zero-index) to use. 343 \param row The row number (zero-index) to use. 344 \param columnCount The number of columns to span the \a groupLayout over. 345 \param rowCount The number of rows to span the \a groupLayout over. 346 347 \returns A GroupBuilder representing the \a groupLayout. 348 349 \since Haiku R1 350*/ 351 352 353/*! 354 \fn GridBuilder BLayoutBuilder::Grid<ParentBuilder>::AddGrid( 355 float horizontalSpacing, float verticalSpacing, int32 column, 356 int32 row, int32 columnCount, int32 rowCount) 357 \copydoc GridBuilder BLayoutBuilder::Group<ParentBuilder>::AddGrid( 358 float horizontalSpacing, float verticalSpacing, float weight) 359 360 \param horizontalSpacing The horizontal spacing for the new BGridLayout. 361 \param verticalSpacing The vertical spacing for the new BGridLayout. 362 \param column The column number (zero-index) to use. 363 \param row The row number (zero-index) to use. 364 \param columnCount The number of columns to span the new BGridLayout over. 365 \param rowCount The number of rows to span the new BGridLayout over. 366 367 \returns A GridBuilder representing the newly created BGridLayout. 368 369 \since Haiku R1 370*/ 371 372 373/*! 374 \fn GridBuilder BLayoutBuilder::Grid<ParentBuilder>::AddGrid( 375 BGridLayout* gridLayout, int32 column, int32 row, int32 columnCount, 376 int32 rowCount) 377 \copybrief GridBuilder BLayoutBuilder::Group<ParentBuilder>::AddGrid( 378 BGridLayout* gridLayout, float weight) 379 380 \param gridLayout The BGridLayout to be added. 381 \param column The column number (zero-index) to use. 382 \param row The row number (zero-index) to use. 383 \param columnCount The number of columns to span the \a gridLayout over. 384 \param rowCount The number of rows to span the \a gridLayout over. 385 386 \returns A GridBuilder representing \a gridLayout. 387 388 \since Haiku R1 389*/ 390 391 392/*! 393 \fn GridBuilder BLayoutBuilder::Grid<ParentBuilder>::AddGrid( 394 BGridView* gridView, int32 column, int32 row, int32 columnCount, 395 int32 rowCount) 396 \copybrief GridBuilder BLayoutBuilder::Group<ParentBuilder>::AddGrid( 397 BGridView* gridView, float weight) 398 399 \param gridView The BGridView to be added. 400 \param column The column number (zero-index) to use. 401 \param row The row number (zero-index) to use. 402 \param columnCount The number of columns to span the \a gridView over. 403 \param rowCount The number of rows to span the \a gridView over. 404 405 \returns A GridBuilder representing the layout of the \a gridView. 406 407 \since Haiku R1 408*/ 409 410 411/*! 412 \fn SplitBuilder BLayoutBuilder::Grid<ParentBuilder>::AddSplit( 413 orientation orientation, float spacing, int32 column, int32 row, 414 int32 columnCount, int32 rowCount) 415 \copybrief SplitBuilder BLayoutBuilder::Group<ParentBuilder>::AddSplit( 416 orientation orientation, float spacing, float weight) 417 418 \param orientation The orientation of the new BSplitView. 419 \param spacing The spacing of the new BSplitView. 420 \param column The column number (zero-index) to use. 421 \param row The row number (zero-index) to use. 422 \param columnCount The number of columns to span the new BSplitView over. 423 \param rowCount The number of rows to span the new BSplitView over. 424 425 \returns A SplitBuilder representing the new BSplitView. 426 427 \since Haiku R1 428*/ 429 430 431/*! 432 \fn SplitBuilder BLayoutBuilder::Grid<ParentBuilder>::AddSplit( 433 BSplitView* splitView, int32 column, int32 row, int32 columnCount, 434 int32 rowCount) 435 \copybrief SplitBuilder BLayoutBuilder::Group<ParentBuilder>::AddSplit( 436 BSplitView* splitView, float weight) 437 438 \param splitView The BSplitView to be added. 439 \param column The column number (zero-index) to use. 440 \param row The row number (zero-index) to use. 441 \param columnCount The number of columns to span the \a splitView over. 442 \param rowCount The number of rows to span the \a splitView over. 443 444 \returns A SplitBuilder representing the \a splitView. 445 446 \since Haiku R1 447*/ 448 449 450/*! 451 \fn CardBuilder BLayoutBuilder::Grid<ParentBuilder>::AddCards( 452 int32 column, int32 row, int32 columnCount, int32 rowCount) 453 \copybrief CardBuilder BLayoutBuilder::Group<ParentBuilder>::AddCards( 454 float weight) 455 456 \param column The column number (zero-index) to use. 457 \param row The row number (zero-index) to use. 458 \param columnCount The number of columns to span the new layout over. 459 \param rowCount The number of rows to span the new layout over. 460 461 \returns A CardBuilder representing the new BCardLayout. 462 463 \since Haiku R1 464*/ 465 466 467/*! 468 \fn CardBuilder BLayoutBuilder::Grid<ParentBuilder>::AddCards( 469 BCardLayout* cardLayout, int32 column, int32 row, int32 columnCount, 470 int32 rowCount) 471 \copybrief CardBuilder BLayoutBuilder::Group<ParentBuilder>::AddCards( 472 BCardLayout* cardLayout, float weight) 473 474 \param cardLayout The existing layout to add to the current grid layout. 475 \param column The column number (zero-index) to use. 476 \param row The row number (zero-index) to use. 477 \param columnCount The number of columns to span the \a cardLayout over. 478 \param rowCount The number of rows to span the \a cardLayout over. 479 480 \returns A CardBuilder representing the \a cardLayout. 481 482 \since Haiku R1 483*/ 484 485 486/*! 487 \fn CardBuilder BLayoutBuilder::Grid<ParentBuilder>::AddCards( 488 BCardView* cardView, int32 column, int32 row, int32 columnCount, 489 int32 rowCount) 490 \copybrief CardBuilder BLayoutBuilder::Group<ParentBuilder>::AddCards( 491 BCardView* cardView, float weight) 492 493 \param cardView The existing BCardView to add to the current grid layout. 494 \param column The column number (zero-index) to use. 495 \param row The row number (zero-index) to use. 496 \param columnCount The number of columns to span the \a cardView over. 497 \param rowCount The number of rows to span the \a cardView over. 498 499 \returns A CardBuilder representing the layout of t he \a cardView. 500 501 \since Haiku R1 502*/ 503 504 505//! @} 506 507 508/*! 509 \name Adding BSpaceLayoutItems 510 511 A convenience method to add glue to a cell. 512*/ 513 514 515//! @{ 516 517 518/*! 519 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::AddGlue( 520 int32 column, int32 row, int32 columnCount, int32 rowCount) 521 \copybrief BLayoutBuilder::Group<ParentBuilder>::AddGlue(float weight) 522 523 \param column The column number (zero-index) for the glue. 524 \param row The row number (zero-index) for the glue. 525 \param columnCount The number of columns to span the glue item over. 526 \param rowCount The number of rows to span the glue item over. 527 528 \since Haiku R1 529*/ 530 531 532//! @} 533 534 535/*! 536 \name BGridLayout Properties 537 538 These methods expose some settings of the underlying grid layout. 539*/ 540 541 542//! @{ 543 544 545/*! 546 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::SetHorizontalSpacing( 547 float spacing) 548 \copydoc BGridLayout::SetHorizontalSpacing(float spacing) 549*/ 550 551 552/*! 553 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::SetVerticalSpacing( 554 float spacing) 555 \copydoc BGridLayout::SetVerticalSpacing(float spacing) 556*/ 557 558 559/*! 560 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::SetSpacing( 561 float horizontal, float vertical) 562 \copydoc BGridLayout::SetSpacing(float horizontal, float vertical) 563*/ 564 565 566/*! 567 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::SetColumnWeight( 568 int32 column, float weight) 569 \copydoc BGridLayout::SetColumnWeight(int32 column, float weight) 570*/ 571 572 573/*! 574 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::SetRowWeight( 575 int32 row, float weight) 576 \copydoc BGridLayout::SetRowWeight(int32 row, float weight) 577*/ 578 579 580//! @} 581 582 583/*! 584 \name Insets 585*/ 586 587 588//! @{ 589 590 591/*! 592 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::SetInsets( 593 float left, float top, float right, float bottom) 594 \copydoc BTwoDimensionalLayout::SetInsets(float, float, float, float) 595*/ 596 597 598/*! 599 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::SetInsets( 600 float horizontal, float vertical) 601 \copydoc BTwoDimensionalLayout::SetInsets(float, float) 602*/ 603 604 605/*! 606 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::SetInsets( 607 float insets) 608 \copydoc BTwoDimensionalLayout::SetInsets(float) 609*/ 610 611 612//! @} 613 614 615/*! 616 \name Explicit Sizes and Alignment 617*/ 618 619 620//! @{ 621 622 623/*! 624 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::SetExplicitMinSize( 625 BSize size) 626 \copydoc BLayoutBuilder::Group<ParentBuilder>::SetExplicitMinSize() 627*/ 628 629 630/*! 631 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::SetExplicitMaxSize( 632 BSize size) 633 \copydoc BLayoutBuilder::Group<ParentBuilder>::SetExplicitMaxSize() 634*/ 635 636 637/*! 638 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::SetExplicitPreferredSize( 639 BSize size) 640 \copydoc BLayoutBuilder::Group<ParentBuilder>::SetExplicitPreferredSize() 641*/ 642 643 644/*! 645 \fn ThisBuilder& BLayoutBuilder::Grid<ParentBuilder>::SetExplicitAlignment( 646 BAlignment alignment) 647 \copydoc BLayoutBuilder::Group<ParentBuilder>::SetExplicitAlignment() 648*/ 649 650 651//! @} 652