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/Layout.h rev 38207 10 * src/kits/interface/Layout.cpp rev 38207 11 */ 12 13 14/*! 15 \file Layout.h 16 \ingroup interface 17 \ingroup layout 18 \ingroup libbe 19 \brief Defines the BLayout class. 20*/ 21 22 23/*! 24 \class BLayout 25 \ingroup interface 26 \ingroup layout 27 \ingroup libbe 28 \brief The BLayout class provides an interface, and some basic 29 implementation to manage the positioning and sizing of BLayoutItem s. 30 31 BLayouts can be attached to a BView, managing the BLayoutItem's and 32 BView's that reside in that view, or can be nested within another 33 BLayout as a BLayoutItem. 34 35 Before adding a BLayoutItem to a BLayout, that layout must have a target 36 view. When a BLayout is attached directly to a BView via BView::SetLayout() 37 then that BView becomes the target of the layout. When a BLayout is nested 38 in another BLayout (via BLayout::AddItem()) the nested BLayout inherits the 39 target of the layout it's nested in, if it does not have a target already. 40 You can retrieve the target view for a layout with the TargetView() method. 41 When adding a BLayoutItem to a BLayout, the item's view (as returned by 42 BLayoutItem::View()) is added to the BLayout's target view. 43 44\code 45BView* topView = new BGroupView(); 46BLayout* topLayout = topView->GetLayout(); 47 48BLayout* nestedLayout = new BGroupLayout(B_HORIZONTAL); 49topLayout->AddItem(nestedLayout); 50 51BLayout* veryNestedLayout = new BGroupLayout(B_VERTICAL); 52nestedLayout->AddItem(veryNestedLayout); 53\endcode 54 55 After executing this code, \c veryNestedLayout, \c nestedLayout, and 56 \c topLayout all have the same target view: \c topView. 57 58 Continuing with the same objects... 59 60\code 61BLayout* nestedLayoutWithView = (new BGroupView())->GetLayout(); 62topLayout->AddItem(nestedLayoutWithView); 63\endcode 64 65 \c nestedLayoutWithView does have a target view of \c topView. This is 66 because \c nestedLayoutWithView is attached directly to a BView. 67 68 \warning This class is not yet finalized, if you use it in your software 69 assume that it will break some time in the future. 70 71 \since Haiku R1 72*/ 73 74 75/*! 76 \fn BLayout::BLayout() 77 \brief Default constructor. 78 79 After this constructor has finished, this BLayout holds no 80 BLayoutItem's and does not have a target BView. 81 82 \warning Because a new BLayout does not have a target BView, calls to the 83 AddItem() and AddView() will fail methods will fail. 84 85 \since Haiku R1 86*/ 87 88 89/*! 90 \fn BLayout::BLayout(BMessage* archive) 91 \brief Archive constructor. 92 93 \param archive The archive message. 94 95 \since Haiku R1 96*/ 97 98 99/*! 100 \fn BLayout::~BLayout() 101 \brief Destructor, deletes all BLayoutItem's that this layout manages, 102 and detaches from this BLayout's owner view if there is one. 103 104 Each BLayoutItem's BView (as returned by BLayoutItem::View()) is also 105 removed from their parent. 106 107 \note Because nested BLayout's are treated as BLayoutItem's, 108 any layouts nested in this BLayout will be deleted. 109 110 \since Haiku R1 111*/ 112 113 114/*! 115 \name BView Targeting and Attachment Information 116*/ 117 118 119//! @{ 120 121 122/*! 123 \fn BView* BLayout::Owner() const 124 \brief Returns the Owner of this layout, i.e. the view this layout manages. 125 126 \since Haiku R1 127*/ 128 129 130/*! 131 \fn BView* BLayout::TargetView() const 132 \brief Returns the target view of this layout. 133 134 The target view of a layout becomes the parent of any BView's in this 135 layout, as well as the BView's returned by BLayoutItem::View() for 136 each BLayoutItem in this layout. 137 138 \since Haiku R1 139*/ 140 141 142/*! 143 \fn BView* BLayout::View() 144 \brief Returns the same BView* as BLayout::Owner(), this method is 145 inherited from BLayoutItem. 146 147 \since Haiku R1 148*/ 149 150 151//! @} 152 153 154/*! 155 \name Adding, Removing, Counting and Accessing Children 156*/ 157 158 159//! @{ 160 161 162/*! 163 \fn BLayoutItem* BLayout::AddView(BView* child) 164 \brief Creates a BLayoutItem to represent a BView, and adds that item to 165 this layout. 166 167 \a child is added to this BLayout's target view. 168 169 \returns The BLayoutItem created to represent \a child is, or \c NULL if 170 there was an error. 171 172 \param child The BView to be added to this BLayout. 173 174 \since Haiku R1 175*/ 176 177 178/*! 179 \fn BLayoutItem* BLayout::AddView(int32 index, BView* child) 180 \brief Creates a BLayoutItem to represent \a child, and adds that item at 181 \a index to this layout. \a child is added to this BLayout's target view. 182 183 \since Haiku R1 184*/ 185 186 187/*! 188 \fn bool BLayout::AddItem(BLayoutItem* item) 189 \brief Adds a BLayoutItem to this layout, and adds the BView it represents 190 to this BLayout's target view. 191 192 \param item The BLayoutItem to be added. 193 194 \return \c true if the item was added, \c false otherwise. 195 196 \since Haiku R1 197*/ 198 199 200/*! 201 \fn bool BLayout::AddItem(int32 index, BLayoutItem* item) 202 \brief Adds \a item to this layout, and adds the BView \a item represents 203 to this BLayout's target view. 204 205 \param item The BLayoutItem to be added. 206 \param index The index at which to add \c item. 207 208 If \a index is out of bounds, \a item will be added at the end. If \a index 209 is somewhere between the first and last indices, then items from \a index 210 to the end will be shuffled over by one. 211 212 \return \c true if the item was added, \c false otherwise. 213 214 \since Haiku R1 215*/ 216 217 218/*! 219 \fn bool BLayout::RemoveView(BView* child) 220 \brief Removes and deletes all BLayoutItem representing a BView from 221 this layout. 222 223 \param child The BView to be removed. 224 225 \return \c true if the item was removed, \c false otherwise. 226 227 \since Haiku R1 228*/ 229 230 231/*! 232 \fn bool BLayout::RemoveItem(BLayoutItem* item) 233 \brief Removes a BLayoutItem from this layout, and also removes the view 234 it represents from this BLayout's target view. 235 236 \param item The BLayoutItem to be removed 237 238 \warning \a item is not deleted, you must delete it manually, or add it to 239 another BLayout. 240 \warning \a item->View(), even when it is removed from the target view, 241 is not deleted. If you want it deleted, you must delete it yourself! 242 243 \return \c true if the item was removed, \c false otherwise. 244 245 \since Haiku R1 246*/ 247 248 249/*! 250 \fn BLayoutItem* BLayout::RemoveItem(int32 index) 251 \brief Remove the BLayoutItem at \a index. 252 253 \see RemoveItem(BLayoutItem*) 254 255 \returns The BLayoutItem that was removed. 256 257 \since Haiku R1 258*/ 259 260 261/*! 262 \fn BLayoutItem* BLayout::ItemAt(int32 index) const 263 \brief Get the BLayoutItem at \a index. Returns \c NULL if \a index is 264 out of bounds. 265 266 \since Haiku R1 267*/ 268 269 270/*! 271 \fn int32 BLayout::CountItems() const 272 \brief Get the number of BLayoutItem s in this layout. 273 274 \since Haiku R1 275*/ 276 277 278/*! 279 \fn int32 BLayout::IndexOfItem(const BLayoutItem* item) const 280 \brief Get the index of a BLayoutItem in this layout. 281 282 \param item The BLayoutItem whose index you want. 283 284 \retval -1 \a item was not found in this BLayout. 285 286 \since Haiku R1 287*/ 288 289 290/*! 291 \fn int32 BLayout::IndexOfView(BView* child) const 292 \brief Get the index of \a child in this layout. 293 294 \note This finds the index of views added through BLayout::AddView(), not 295 the index of an item which represents \a child that was added through 296 BLayout::AddItem(). 297 298 \since Haiku R1 299*/ 300 301 302//! @} 303 304 305/*! 306 \name Subclass Helpers 307 308 These methods are meant to ease the development of BLayout 309 subclasses. 310*/ 311 312 313//! @{ 314 315 316/*! 317 \fn bool BLayout::AncestorsVisible() const 318 \brief Get the visibility of the ancestors of this layout. 319 320 If a BLayout is connected to a BView, this will always return \c true. 321 If a BLayout is nested in another layout (it was passed to AddItem()), then 322 this will reflect the visibility of this BLayout's parent layout. If 323 any layout is hidden (by BLayout::SetVisible()) between this layout and its 324 target BView's layout, then this method will return \c false. 325 326 \since Haiku R1 327*/ 328 329 330/*! 331 \fn BRect BLayout::LayoutArea() 332 \brief Returns the on-screen area this layout has received to lay out its 333 items in. 334 335 The return value is in the coordinate space of this BLayout's target 336 view. If this BLayout is attached directly to a BView, then 337 <tt> LayoutArea().LeftTop() == B_ORIGIN </tt>. 338 339 \since Haiku R1 340*/ 341 342 343/*! 344 \fn void BLayout::VisibilityChanged(bool show) 345 \brief Method to be called by derived classes in their SetVisible() 346 implementation. Calls AncestorVisibilityChanged() on the items in this 347 BLayout. 348 349 \param show \c true to show, \c false to hide. 350 351 \since Haiku R1 352*/ 353 354 355//! @} 356 357 358/*! 359 \name Methods Triggering or Related to Laying Out the BLayout 360*/ 361 362 363//! @{ 364 365 366/*! 367 \fn void BLayout::Relayout(bool immediate = false) 368 \brief Request this BLayout to reposition and resize its items as required. 369 370 If \a immediate is \c false, and there is already a request to have the 371 window this layout resides in re-laid-out, then the layout will happen at 372 that time. If \a immediate is \c true, and there is no such pending 373 request, nor is this BLayout's parent layout in the process of laying 374 out its items, then this BLayout will now layout its items. 375 376 \param immediate Whether or not to Relayout immediately or wait for pending 377 requests first. 378 379 \since Haiku R1 380*/ 381 382 383/*! 384 \fn void BLayout::LayoutItems(bool force = false) 385 \brief If there is no layout currently ongoing, and \a force is \c false, 386 creates a new BLayoutContext and calls the DoLayout() method 387 of this BLayout and any BLayout's nested in this BLayout. 388 389 This method also guarantees that the owner view of this layout (as returned 390 by BLayout::Owner()) performs a layout as well (if it is suitable to do so). 391 392 \param force Force the LayoutItems. 393 394 \since Haiku R1 395*/ 396 397 398/*! 399 \fn BLayoutContext* BLayout::LayoutContext() const 400 \brief Returns the BLayoutContext this BLayout is currently operating in, 401 or \c NULL. 402 403 \since Haiku R1 404*/ 405 406 407//! @} 408 409 410/*! 411 \name Invalidation and State Mutators and Accessors 412*/ 413 414 415//! @{ 416 417 418/*! 419 \fn void BLayout::RequireLayout() 420 \brief Flag this layout as stale, i.e. any cached data may still be valid, 421 but the items need to be repositioned or resized. 422 423 \since Haiku R1 424*/ 425 426 427/*! 428 \fn void BLayout::InvalidateLayout(bool children = false) 429 \brief Invalidate this layout and any cached data this layout has relating 430 to positioning and sizing of its items. 431 432 Invalidating a BLayout also invalidates the view it is connected to 433 (if there is one) and the BLayout this layout (or this BLayout's view) 434 resides in. 435 436 Although this method is virtual, you should not override it, override the 437 BLayout::LayoutInvalidated() hook instead. 438 439 This method should be called whenever the layout becomes invalid. This might 440 happen if the size constraints of an item in this layout change, this layout 441 is given more or less space than it previously had, or an object in this 442 layout has had its InvalidateLayout() method called. 443 444 \sa BView::InvalidateLayout(), BLayoutItem::InvalidateLayout(), 445 BLayout::LayoutInvalidated() 446 447 \since Haiku R1 448*/ 449 450 451/*! 452 \fn bool BLayout::IsValid() 453 \brief Returns whether this layout has been invalidated (via 454 BLayout::InvalidateLayout()) and has not yet been validated 455 (by doing a layout, or by its ResetLayoutInvalidation() method. 456 457 \since Haiku R1 458*/ 459 460 461/*! 462 \fn void BLayout::EnableLayoutInvalidation() 463 \brief Re-enable layout invalidation after a call to 464 DisableLayoutInvalidation(). 465 466 \since Haiku R1 467*/ 468 469 470/*! 471 \fn void BLayout::DisableLayoutInvalidation() 472 \brief Disable layout invalidation notifications, i.e. calls to 473 this object's InvalidateLayout() method. 474 475 \since Haiku R1 476*/ 477 478 479/*! 480 \fn void BLayout::ResetLayoutInvalidation() 481 \brief Reset layout invalidation, causing InvalidateLayout calls to proceed 482 again. This method should be called once any cached data has been 483 validated, or updated to valid values. 484 485 \since Haiku R1 486*/ 487 488 489//! @} 490 491 492/*! 493 \name Archiving 494 495 These methods relate to the archiving or unarchiving of this object 496 and the BLayoutItem's it contains 497 498 \since Haiku R1 499*/ 500 501 502//! @{ 503 504 505/*! 506 \fn status_t BLayout::Archive(BMessage* archive, bool deep = true) const 507 \brief Archives this layout into \a archive. If deep is true, also archives 508 the items in this layout, calling ItemArchived() for each one. 509 510 \since Haiku R1 511*/ 512 513 514/*! 515 \fn status_t BLayout::AllUnarchived(const BMessage* from) 516 \brief Unarchives the BLayoutItem's for this layout, calling 517 ItemUnarchived() for each one. 518 519 \since Haiku R1 520*/ 521 522 523/*! 524 \fn status_t BLayout::ItemArchived(BMessage* into, BLayoutItem* item, 525 int32 index) const 526 \brief Hook for derived classes to add data specific to \a item to the 527 \a into BMessage. \a item resides at \a index. 528 529 \note The same archive is passed to BLayout::ItemArchived() for all items, 530 so any data added for each item will be stored in an array. 531 532 \since Haiku R1 533*/ 534 535 536/*! 537 \fn status_t BLayout::ItemUnarchived(const BMessage* from, 538 BLayoutItem* item, int32 index) 539 \brief Hook for derived classes to retrieve data specific to \a item from 540 the \a from BMessage. \a item resides at \a index. 541 542 \note The same archive is passed to BLayout::ItemArchived() for all items, 543 so any data added for each item will be stored in an array. You 544 should pass \a index to the BMessage methods you will be using in 545 this method. 546 547 \since Haiku R1 548*/ 549 550 551//! @} 552 553 554/*! 555 \name Hook Methods 556*/ 557 558 559//! @{ 560 561 562/*! 563 \fn bool BLayout::ItemAdded(BLayoutItem* item, int32 atIndex) 564 \brief Hook method called when \a item is added to this layout. 565 566 \param item The BLayoutItem that is being added. 567 \param atIndex The index of the BLayoutItem. 568 569 \return \c true on succcess, false if \a item will not be added. 570 571 \note This is a good time to allocate data for a BLayoutItem and attach it 572 to \a item via BLayoutItem::SetLayoutData(). 573 574 \since Haiku R1 575*/ 576 577 578/*! 579 \fn void BLayout::ItemRemoved(BLayoutItem* item, int32 fromIndex) 580 \brief Hook method called when \a item is removed from this layout. 581 582 \param item The BLayoutItem being removed. 583 \param fromIndex The index where \a item used to reside. 584 585 When this hook is called, \a item is not yet completely removed. It can 586 no longer be accessed with LayoutItemAt(), nor does it contribute to the 587 value of CountItems(), but the item has not yet had its ItemDetached() 588 hook called. 589 590 \note This is a good time to delete the data you've attached to \a item 591 via BLayoutItem::SetLayoutData(). 592 593 \since Haiku R1 594*/ 595 596 597/*! 598 \fn void BLayout::DoLayout() = 0 599 \brief Implemented by derived classes to position and resize the items in 600 this layout. 601 602 \since Haiku R1 603*/ 604 605 606/*! 607 \fn void BLayout::LayoutInvalidated(bool children) 608 609 Hook method called when this layout becomes invalid. This is a good place 610 to clear any caches your object might hold. 611 612 \param children Whether or not child layouts have also been invalidated. 613 614 \since Haiku R1 615*/ 616 617 618/*! 619 \fn void BLayout::OwnerChanged(BView* was) 620 \brief Hook method called when this layout is attached to a BView. 621 622 \param was The previous owner of this BLayout, for new BLayout s, this 623 will be \c NULL. 624 625 \since Haiku R1 626*/ 627 628 629/*! 630 \fn void BLayout::AttachedToLayout() 631 \brief Hook method inherited from BLayoutItem, classes derived from 632 BLayout must include the BLayout version of this method in their 633 implementation. 634 635 \since Haiku R1 636*/ 637 638 639/*! 640 \fn void BLayout::DetachedFromLayout(BLayout* layout) 641 \brief Hook method inherited from BLayoutItem, classes derived from 642 BLayout must include the BLayout version of this method in their 643 implementation. 644 645 \param layout The BLayout that this BLayout was detached from. 646 647 \since Haiku R1 648*/ 649 650 651/*! 652 \fn void BLayout::AncestorVisibilityChanged(bool shown) 653 \brief Hook method inherited from BLayoutItem, classes derived from 654 BLayout must include the BLayout version of this method in their 655 implementation. 656 657 \since Haiku R1 658*/ 659 660 661//! @} 662