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 215 \retval true success 216 \retval false failure 217*/ 218 219 220/*! 221 \fn BLayoutItem* BLayout::RemoveItem(int32 index) 222 \brief Remove the BLayoutItem at \a index. 223 224 \see RemoveItem(BLayoutItem*) 225 226 \returns The BLayoutItem that was removed. 227*/ 228 229 230/*! 231 \fn BLayoutItem* BLayout::ItemAt(int32 index) const 232 \brief Get the BLayoutItem at \a index. Returns \c NULL if \a index is 233 out of bounds. 234*/ 235 236 237/*! 238 \fn int32 BLayout::CountItems() const 239 \brief Get the number of BLayoutItem s in this layout. 240*/ 241 242 243/*! 244 \fn int32 BLayout::IndexOfItem(const BLayoutItem* item) const 245 \brief Get the index of a BLayoutItem in this layout. 246 247 \param item The BLayoutItem whose index you want. 248 249 \retval -1 \a item was not found in this BLayout. 250*/ 251 252 253/*! 254 \fn int32 BLayout::IndexOfView(BView* child) const 255 \brief Get the index of \a child in this layout. 256 257 \note This finds the index of views added through BLayout::AddView(), not 258 the index of an item which represents \a child that was added through 259 BLayout::AddItem(). 260*/ 261 262 263//! @} 264 265 266/*! 267 \name Subclass helpers. 268 \brief These methods are meant to ease the development of BLayout 269 subclasses. 270*/ 271 272 273//! @{ 274 275 276/*! 277 \fn bool BLayout::AncestorsVisible() 278 \brief Get the visibility of the ancestors of this layout. 279 280 If a BLayout is connected to a BView, this will always return \c true. 281 If a BLayout is nested in another layout (it was passed to AddItem()), then 282 this will reflect the visibility of this BLayout's parent layout. If 283 any layout is hidden (by BLayout::SetVisible()) between this layout and its 284 target BView's layout, then this method will return \c false. 285*/ 286 287 288/*! 289 \fn BRect BLayout::LayoutArea() 290 \brief Returns the on-screen area this layout has received to lay out its 291 items in. 292 293 The return value is in the coordinate space of this BLayout's target 294 view. If this BLayout is attached directly to a BView, then 295 <tt> LayoutArea().LeftTop() == B_ORIGIN </tt>. 296*/ 297 298 299/*! 300 \fn void BLayout::VisibilityChanged(bool show) 301 \brief Method to be called by derived classes in their SetVisible() 302 implementation. Calls AncestorVisibilityChanged() on the items in this 303 BLayout. 304 305 \param show \c true to show, \c false to hide. 306*/ 307 308 309//! @} 310 311 312/*! 313 \name Methods triggering or related to laying out this BLayout. 314*/ 315 316 317//! @{ 318 319 320/*! 321 \fn void BLayout::Relayout(bool immediate = false) 322 \brief Request this BLayout to reposition and resize its items as required. 323 324 If \a immediate is \c false, and there is already a request to have the 325 window this layout resides in re-laid-out, then the layout will happen at 326 that time. If \a immediate is \c true, and there is no such pending 327 request, nor is this BLayout's parent layout in the process of laying 328 out its items, then this BLayout will now layout its items. 329 330 \param immediate Whether or not to Relayout immediately or wait for pending 331 requests first. 332*/ 333 334 335/*! 336 \fn void BLayout::LayoutItems(bool force = false) 337 \brief If there is no layout currently ongoing, and \a force is \c false, 338 creates a new BLayoutContext and calls the DerivedLayoutItems() method 339 of this BLayout and any BLayout s nested in this BLayout. 340 341 If method also guarantees that the owner view of this layout (as returned 342 by BLayout::Owner()) performs a layout as well (if it is suitable to do so). 343 344 \param force Force the LayoutItems. 345*/ 346 347 348/*! 349 \fn BLayoutContext* BLayout::LayoutContext() 350 \brief Returns the BLayoutContext this BLayout is currently operating in, 351 or \c NULL. 352*/ 353 354 355//! @} 356 357 358/*! 359 \name Invalidation and state mutators and accessors. 360*/ 361 362 363//! @{ 364 365 366/*! 367 \fn void BLayout::RequireLayout() 368 \brief Flag this layout as stale, i.e. any cached data may still be valid, 369 but the items need to be repositioned or resized. 370*/ 371 372 373/*! 374 \fn void BLayout::InvalidateLayout(bool children = false) 375 \brief Invalidate this layout and any cached data this layout has relating 376 to positioning and sizing of its items. 377 378 Invalidating a BLayout also invalidates the view it is connected to 379 (if there is one) and the BLayout this layout (or this BLayout's view) 380 resides in. 381 382 This method should be called whenever the layout becomes invalid. This might 383 happen if the size constraints of an item in this layout change, this layout 384 is given more or less space than it previously had, or an object in this 385 layout has had its InvalidateLayout() method called. 386 387 \see BView::InvalidateLayout() BLayoutItem::InvalidateLayout() 388*/ 389 390 391/*! 392 \fn bool BLayout::IsValid() 393 \brief Returns whether this layout has been invalidated (via 394 BLayout::InvalidateLayout()) and has not yet been validated (by doing a 395 layout, or by its ResetLayoutInvalidation() method. 396*/ 397 398 399/*! 400 \fn void BLayout::EnableLayoutInvalidation() 401 \brief Re-enable layout invalidation after a call to 402 DisableLayoutInvalidation(). 403*/ 404 405 406/*! 407 \fn void BLayout::DisableLayoutInvalidation() 408 \brief Disable layout invalidation notifications, i.e. calls to 409 this object's InvalidateLayout() method. 410*/ 411 412 413/*! 414 \fn void BLayout::ResetLayoutInvalidation() 415 \brief Reset layout invalidation, causing InvalidateLayout calls to proceed 416 again. This method should be called once any cached data has been 417 validated, or updated to valid values. 418*/ 419 420 421//! @} 422 423 424/*! 425 \name Archiving methods 426 \brief These methods relate to the archiving or unarchiving of this object 427 and the BLayoutItem's it contains 428*/ 429 430 431//! @{ 432 433 434/*! 435 \fn status_t BLayout::Archive(BMessage* archive, bool deep = true) const 436 \brief Archives this layout into \a archive. If deep is true, also archives 437 the items in this layout, calling ItemArchived() for each one. 438*/ 439 440 441/*! 442 \fn status_t BLayout::AllUnarchived(const BMessage* from) 443 \brief Unarchives the BLayoutItem's for this layout, calling 444 ItemUnarchived() for each one. 445*/ 446 447 448/*! 449 \fn status_t BLayout::ItemArchived(BMessage* into, BLayoutItem* item, 450 int32 index) const 451 \brief Hook for derived classes to add data specific to \a item to the 452 \a into BMessage. \a item resides at \a index. 453 454 \note The same archive is passed to BLayout::ItemArchived() for all items, 455 so any data added for each item will be stored in an array. 456*/ 457 458 459/*! 460 \fn status_t BLayout::ItemUnarchived(const BMessage* from, 461 BLayoutItem* item, int32 index) 462 \brief Hook for derived classes to retrieve data specific to \a item from 463 the \a from BMessage. \a item resides at \a index. 464 465 \note The same archive is passed to BLayout::ItemArchived() for all items, 466 so any data added for each item will be stored in an array. You should pass 467 \a index to the BMessage methods you will be using in this method. 468*/ 469 470 471//! @} 472 473 474/*! 475 \name BLayout Hook methods 476*/ 477 478 479//! @{ 480 481 482/*! 483 \fn bool BLayout::ItemAdded(BLayoutItem* item, int32 atIndex) 484 \brief Hook method called when \a item is added to this layout. 485 486 \param item The BLayoutItem that is being added. 487 \param atIndex The index of the BLayoutItem. 488 489 \retval true success 490 \retval false failure, \a item will not be added. 491 492 \note This is a good time to allocate data for a BLayoutItem and attach it 493 to \a item via BLayoutItem::SetLayoutData(). 494*/ 495 496 497/*! 498 \fn void BLayout::ItemRemoved(BLayoutItem* item, int32 fromIndex) 499 \brief Hook method called when \a item is removed from this layout. 500 501 \param item The BLayoutItem being removed. 502 \param fromIndex The index where \a item used to reside. 503 504 \note This is a good time to delete the data you've attached to \a item 505 via BLayoutItem::SetLayoutData(). 506*/ 507 508 509/*! 510 \fn void BLayout::DerivedLayoutItems() = 0 511 \brief Implemented by derived classes to position and resize the items in 512 this layout. 513*/ 514 515 516/*! 517 \fn void BLayout::OwnerChanged(BView* was) 518 \brief Hook method called when this layout is attached to a BView. 519 520 \param was The previous owner of this BLayout, for new BLayout s, this 521 will be \c NULL. 522*/ 523 524 525/*! 526 \fn void BLayout::AttachedToLayout() 527 \brief Hook method inherited from BLayoutItem, classes derived from 528 BLayout must include the BLayout version of this method in their 529 implementation. 530*/ 531 532 533/*! 534 \fn void BLayout::DetachedFromLayout(BLayout* layout) 535 \brief Hook method inherited from BLayoutItem, classes derived from 536 BLayout must include the BLayout version of this method in their 537 implementation. 538 539 \param layout The BLayout that this BLayout was detached from. 540*/ 541 542 543/*! 544 \fn void BLayout::AncestorVisibilityChanged(bool shown) 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