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