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