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/LayoutItem.h rev 49040 10 * src/kits/interface/LayoutItem.cpp rev 49040 11 */ 12 13 14/*! 15 \file LayoutItem.h 16 \ingroup layout 17 \ingroup libbe 18 \brief Describes the BLayoutItem class. 19*/ 20 21 22/*! 23 \class BLayoutItem 24 \ingroup layout 25 \ingroup libbe 26 \brief Abstract class representing things that are positionable and 27 resizable by objects of the BLayout class. 28 29 The BLayoutItem class provides an interface that is meant to be used almost 30 exclusively by objects of the BLayout class. Despite this, there are some 31 methods that are provided for other users of the class. 32 33 \warning This class is not yet finalized, if you use it in your software 34 assume that it will break some time in the future. 35 36 \since Haiku R1 37*/ 38 39 40/*! 41 \fn BLayoutItem::BLayoutItem(BMessage* archive) 42 \brief Archive constructor. 43 44 Creates a BLayoutItem from the \a archive message. 45 46 \since Haiku R1 47*/ 48 49 50/*! 51 \fn BLayout* BLayoutItem::Layout() const 52 \brief Returns the BLayout this BLayoutItem resides in. 53 54 \since Haiku R1 55*/ 56 57 58/*! 59 \fn bool BLayoutItem::RemoveSelf() 60 \brief Remove this layout item from the BLayout it is a part of. 61 62 This method works analoguous to BView::RemoveSelf(), that is it removes 63 itself from the parent layout and returns whether or not this was 64 succesful. 65 66 \return \c true if the item was removed from the layout, or \c false if 67 item was not part of a layout, or removal was succesful. 68 69 \since Haiku R1 70*/ 71 72 73/*! 74 \fn BLayout::~BLayout() 75 \brief Destructor method. 76 77 Standard Destructor. 78 79 \since Haiku R1 80*/ 81 82 83/*! 84 \name Reporting Size and Alignment Constraints to a BLayout 85*/ 86 87 88//! @{ 89 90 91/*! 92 \fn BSize BLayoutItem::MinSize() = 0 93 \brief Returns the minimum desirable size for this item. 94 95 \since Haiku R1 96*/ 97 98 99/*! 100 \fn BSize BLayoutItem::MaxSize() = 0 101 \brief Returns the maximum desirable size for this item. 102 103 \since Haiku R1 104*/ 105 106 107/*! 108 \fn BSize BLayoutItem::PreferredSize() = 0 109 \brief Returns the preferred size for this item. 110 111 \since Haiku R1 112*/ 113 114 115/*! 116 \fn BAlignment BLayoutItem::Alignment() = 0 117 \brief Returns the requested alignment for this item. 118 119 The value returned from this method is used in BLayoutItem::AlignInFrame(), 120 which BLayouts use to position and resize items. In a vertical BGroupLayout, 121 for example, although each item recieves the same horizontal area, each item 122 can use that area differently, aligning to the left, right or center for 123 example. 124 125 \since Haiku R1 126*/ 127 128 129/*! 130 \fn bool BLayoutItem::HasHeightForWidth() 131 \brief Returns whether or not this BLayoutItem's height constraints are 132 dependent on its width. 133 134 \note By default, this method returns \c false. 135 136 \since Haiku R1 137*/ 138 139 140/*! 141 \fn void BLayoutItem::GetHeightForWidth(float width, float* min, 142 float* max, float* preferred) 143 \brief Get this BLayoutItem's height constraints for a given \a width. 144 145 If a BLayoutItem does not have height for width constraints 146 (HasHeightForWidth() returns \c false) it does not need to implement this 147 method. 148 149 \note It is prudent to compare \a min, \a max, \a preferred to \c NULL 150 before dereferencing them. 151 152 \since Haiku R1 153*/ 154 155 156//! @} 157 158 159/*! 160 \name Overriding Size and Alignment Constraints 161 162 Although the explicit constraints placed on an item are not enforced by the 163 BLayoutItem class, all Haiku BLayoutItem subclasses will use the 164 BLayoutUtils::ComposeSize() or BLayoutUtils::ComposeAlignment() functions 165 in when reporting these constraints. It is recommended that all subclasses 166 do this as well, the BAbstractLayoutItem class provides any easy way to 167 include this behaviour in your class. 168 169 \since Haiku R1 170*/ 171 172 173//! @{ 174 175 176/*! 177 \fn void BLayoutItem::SetExplicitMinSize(BSize size) = 0 178 \brief Set this item's explicit min size, to be used in MinSize(). 179 180 This forces the minimal size for the item and overrides any constraints 181 that would normally be used to compute it. Most importantly, the minimal 182 size of children is ignored, so setting this can lead to the children not 183 fitting the view. 184 185 \since Haiku R1 186*/ 187 188 189/*! 190 \fn void BLayoutItem::SetExplicitMaxSize(BSize size) = 0 191 \brief Set this item's explicit max size, to be used in MaxSize(). 192 193 \since Haiku R1 194*/ 195 196 197/*! 198 \fn void BLayoutItem::SetExplicitPreferredSize(BSize size) = 0 199 \brief Set this item's explicit preferred size, to be used in 200 PreferredSize(). 201 202 \since Haiku R1 203*/ 204 205 206/*! 207 \fn void BLayoutItem::SetExplicitSize(BSize size) 208 \brief Set the explicity size to \a size. 209 210 This method is a convenience method that sets the minimum size, maximum 211 size and preferred size to \a size, as to force this layout item to have 212 a specific size. 213 214 \param size The specific (non-zero) size for this layout item. 215 216 \since Haiku R1 217*/ 218 219 220/*! 221 \fn void BLayoutItem::SetExplicitAlignment(BAlignment alignment) = 0 222 \brief Set this item's explicit alignment, to be used in Alignment(). 223 224 \since Haiku R1 225*/ 226 227 228//! @} 229 230 231/*! 232 \name Getting/Setting the Visibility of a BLayoutItem 233 234 These methods take into account only the local visibility of this 235 item, not the visibility of its ancestors. \n 236*/ 237 238 239//! @{ 240 241 242/*! 243 \fn bool BLayoutItem::IsVisible() = 0 244 \brief Return the current local visibility of this item. If an item is not 245 visible, it will not be given space by the BLayout it resides in. 246 247 A simple implementation would return the last thing passed to SetVisible(). 248 A more complex implementation may deal with a BView that could 249 be hidden in any number of ways. 250 251 \since Haiku R1 252*/ 253 254 255/*! 256 \fn void BLayoutItem::SetVisible(bool visible) = 0 257 \brief Set the local visibility of this item. 258 259 \since Haiku R1 260*/ 261 262 263//! @} 264 265 266/*! 267 \name Getting/Setting Current On-Screen Positioning of a BLayoutItem 268*/ 269 270 271//! @{ 272 273 274/*! 275 \fn void BLayoutItem::AlignInFrame(BRect frame) 276 \brief Position this BLayoutItem within \a frame, given the value returned 277 by Alignment(), and the size constraints for this item. 278 279 \since Haiku R1 280*/ 281 282 283/*! 284 \fn BRect BLayoutItem::Frame() = 0 285 \brief Return the bounding frame of this item. 286 287 The returned BRect is in the coordinate system of the target view of the 288 BLayout this item belongs to. 289 290 \since Haiku R1 291*/ 292 293 294/*! 295 \fn void BLayoutItem::SetFrame(BRect frame) = 0 296 \brief Set the bounding frame of this item. 297 298 \a frame is in the coordinate system of the target view of the BLayout 299 that this item belongs to. 300 301 \since Haiku R1 302*/ 303 304 305//! @} 306 307 308/*! 309 \fn BView* BLayoutItem::View() 310 \brief Return the BView this item is representing, or \c NULL if it does not 311 represent any view. 312 313 When a BLayoutItem is added to a BLayout, this method is called, and the 314 returned BView will be added to the BLayout's target view. 315 316 \since Haiku R1 317*/ 318 319 320/*! 321 \name Layout Events and Requests 322 323 These methods represent events or requests originating from a 324 BLayout. In some implementations they may be handled directly by this 325 BLayoutItem, but many implementations will forward these events to 326 another object. 327*/ 328 329 330//! @{ 331 332 333/*! 334 \fn void BLayoutItem::InvalidateLayout(bool children = false) 335 \brief Invalidate the layout of this item, or the object it represents. 336 337 Although this method is virtual, you should not override it in your classes, 338 override LayoutInvalidated() instead. This method will take care of calling 339 the InvalidateLayout() methods of affected views/layouts/items. However, if 340 there is an object that is somehow connected to this one by means other than 341 the standard mechanisms provided by the Haiku API, you should use 342 the LayoutInvalidated() hook to do this. 343 344 \param children Whether or not to invalidate children of this object. 345 346 \since Haiku R1 347*/ 348 349 350/*! 351 \fn void BLayoutItem::Relayout(bool immediate = false) 352 \brief Relayout any children or onscreen data this item contains. Often 353 this request is forwarded to another object. 354 355 The default implementation of this method will likely be sufficient in 356 most cases. Assuming \c this->View() doesn't return \c NULL, the default 357 implementation calls Relayout() or Layout() on the value returned 358 by View(). 359 360 \since Haiku R1 361*/ 362 363 364//! @} 365 366 367/*! 368 \name Utility Methods for BLayout Subclasses 369 370 Utility methods for the BLayout class to attach and retrieve 371 arbitrary data for a BLayoutItem. 372*/ 373 374 375//! @{ 376 377 378/*! 379 \fn void* BLayoutItem::LayoutData() const 380 \brief Retrieve arbitrary data attached to this BLayoutItem. 381 382 \note This method should only be called by a BLayout subclass. 383 384 \since Haiku R1 385*/ 386 387 388/*! 389 \fn void BLayoutItem::SetLayoutData(void* data) 390 \brief Attach arbitrary data to this BLayoutItem. 391 392 \note This method should only be called by a BLayout subclass. 393 394 \since Haiku R1 395*/ 396 397 398//! @} 399 400 401/*! 402 \name Hook methods 403*/ 404 405 406//! @{ 407 408 409/*! 410 \fn void BLayoutItem::LayoutInvalidated(bool children) 411 \brief Hook called from InvalidateLayout(). 412 413 Override this method to clean out an cached layout info. It is good 414 practice to recreate such info only on demand, eg when MinSize() or friends 415 are called. 416 417 If \a children is \c true, then you should invalidate any information on 418 child objects as well, and propagate the invalidation to them. 419 420 \since Haiku R1 421*/ 422 423 424/*! 425 \fn void BLayoutItem::AttachedToLayout() 426 \brief Hook called when this object is attached to a BLayout (via 427 BLayout::AddItem()) 428 429 \note You can find the BLayout you've been attached to with the Layout() 430 method. 431 432 \since Haiku R1 433*/ 434 435 436/*! 437 \fn void BLayoutItem::DetachedFromLayout(BLayout* layout) 438 \brief Hook called when this object is attached to a BLayout (via 439 BLayout::RemoveItem()) 440 441 \warning You should not use this hook to reattach \c this to \a BLayout, 442 doing so will cause undefined behaviour (probably a crash). 443 444 \param layout The BLayout you were previously attached to. 445 446 \since Haiku R1 447*/ 448 449 450/*! 451 \fn void BLayoutItem::AncestorVisibilityChanged(bool shown) 452 \brief Hook called when this BLayoutItem's ancestors change visibility, 453 effectively hiding or showing this item. 454 455 Implementations of this method should alter the onscreen visibility of this 456 item. I.E. if \a shown is \c false, nothing should be drawn to represent 457 this item. 458 459 \note This method should not effect the value returned by this object's 460 IsVisible() method. 461 462 \param shown \c true to show, \c false to hide. 463 464 \since Haiku R1 465*/ 466 467 468//! @} 469