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