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 \since Haiku R1 168*/ 169 170 171/*! 172 \fn void BLayoutItem::SetExplicitMaxSize(BSize size) = 0 173 \brief Set this item's explicit max size, to be used in MaxSize(). 174 175 \since Haiku R1 176*/ 177 178 179/*! 180 \fn void BLayoutItem::SetExplicitPreferredSize(BSize size) = 0 181 \brief Set this item's explicit preferred size, to be used in 182 PreferredSize(). 183 184 \since Haiku R1 185*/ 186 187 188/*! 189 \fn void BLayoutItem::SetExplicitAlignment(BAlignment alignment) = 0 190 \brief Set this item's explicit alignment, to be used in Alignment(). 191 192 \since Haiku R1 193*/ 194 195 196//! @} 197 198 199/*! 200 \name Getting/Setting the Visibility of a BLayoutItem 201 202 These methods take into account only the local visibility of this 203 item, not the visibility of its ancestors. \n 204*/ 205 206 207//! @{ 208 209 210/*! 211 \fn bool BLayoutItem::IsVisible() = 0 212 \brief Return the current local visibility of this item. If an item is not 213 visible, it will not be given space by the BLayout it resides in. 214 215 A simple implementation would return the last thing passed to SetVisible(). 216 A more complex implementation may deal with a BView that could 217 be hidden in any number of ways. 218 219 \since Haiku R1 220*/ 221 222 223/*! 224 \fn void BLayoutItem::SetVisible(bool visible) = 0 225 \brief Set the local visibility of this item. 226 227 \since Haiku R1 228*/ 229 230 231//! @} 232 233 234/*! 235 \name Getting/Setting Current On-Screen Positioning of a BLayoutItem 236*/ 237 238 239//! @{ 240 241 242/*! 243 \fn void BLayoutItem::AlignInFrame(BRect frame) 244 \brief Position this BLayoutItem within \a frame, given the value returned 245 by Alignment(), and the size constraints for this item. 246 247 \since Haiku R1 248*/ 249 250 251/*! 252 \fn BRect BLayoutItem::Frame() = 0 253 \brief Return the bounding frame of this item. 254 255 The returned BRect is in the coordinate system of the target view of the 256 BLayout this item belongs to. 257 258 \since Haiku R1 259*/ 260 261 262/*! 263 \fn void BLayoutItem::SetFrame(BRect frame) = 0 264 \brief Set the bounding frame of this item. 265 266 \a frame is in the coordinate system of the target view of the BLayout 267 that this item belongs to. 268 269 \since Haiku R1 270*/ 271 272 273//! @} 274 275 276/*! 277 \fn BView* BLayoutItem::View() 278 \brief Return the BView this item is representing, or \c NULL if it does not 279 represent any view. 280 281 When a BLayoutItem is added to a BLayout, this method is called, and the 282 returned BView will be added to the BLayout's target view. 283 284 \since Haiku R1 285*/ 286 287 288/*! 289 \name Layout Events and Requests 290 291 These methods represent events or requests originating from a 292 BLayout. In some implementations they may be handled directly by this 293 BLayoutItem, but many implementations will forward these events to 294 another object. 295*/ 296 297 298//! @{ 299 300 301/*! 302 \fn void BLayoutItem::InvalidateLayout(bool children = false) 303 \brief Invalidate the layout of this item, or the object it represents. 304 305 Although this method is virtual, you should not override it in your classes, 306 override LayoutInvalidated() instead. This method will take care of calling 307 the InvalidateLayout() methods of affected views/layouts/items. However, if 308 there is an object that is somehow connected to this one by means other than 309 the standard mechanisms provided by the Haiku API, you should use 310 the LayoutInvalidated() hook to do this. 311 312 \param children Whether or not to invalidate children of this object. 313 314 \since Haiku R1 315*/ 316 317 318/*! 319 \fn void BLayoutItem::Relayout(bool immediate = false) 320 \brief Relayout any children or onscreen data this item contains. Often 321 this request is forwarded to another object. 322 323 The default implementation of this method will likely be sufficient in 324 most cases. Assuming \c this->View() doesn't return \c NULL, the default 325 implementation calls Relayout() or Layout() on the value returned 326 by View(). 327 328 \since Haiku R1 329*/ 330 331 332//! @} 333 334 335/*! 336 \name Utility Methods for BLayout Subclasses 337 338 Utility methods for the BLayout class to attach and retrieve 339 arbitrary data for a BLayoutItem. 340*/ 341 342 343//! @{ 344 345 346/*! 347 \fn void* BLayoutItem::LayoutData() const 348 \brief Retrieve arbitrary data attached to this BLayoutItem. 349 350 \note This method should only be called by a BLayout subclass. 351 352 \since Haiku R1 353*/ 354 355 356/*! 357 \fn void BLayoutItem::SetLayoutData(void* data) 358 \brief Attach arbitrary data to this BLayoutItem. 359 360 \note This method should only be called by a BLayout subclass. 361 362 \since Haiku R1 363*/ 364 365 366//! @} 367 368 369/*! 370 \name Hook methods 371*/ 372 373 374//! @{ 375 376 377/*! 378 \fn void BLayoutItem::LayoutInvalidated(bool children) 379 \brief Hook called from InvalidateLayout(). 380 381 Override this method to clean out an cached layout info. It is good 382 practice to recreate such info only on demand, eg when MinSize() or friends 383 are called. 384 385 If \a children is \c true, then you should invalidate any information on 386 child objects as well, and propagate the invalidation to them. 387 388 \since Haiku R1 389*/ 390 391 392/*! 393 \fn void BLayoutItem::AttachedToLayout() 394 \brief Hook called when this object is attached to a BLayout (via 395 BLayout::AddItem()) 396 397 \note You can find the BLayout you've been attached to with the Layout() 398 method. 399 400 \since Haiku R1 401*/ 402 403 404/*! 405 \fn void BLayoutItem::DetachedFromLayout(BLayout* layout) 406 \brief Hook called when this object is attached to a BLayout (via 407 BLayout::RemoveItem()) 408 409 \warning You should not use this hook to reattach \c this to \a BLayout, 410 doing so will cause undefined behaviour (probably a crash). 411 412 \param layout The BLayout you were previously attached to. 413 414 \since Haiku R1 415*/ 416 417 418/*! 419 \fn void BLayoutItem::AncestorVisibilityChanged(bool shown) 420 \brief Hook called when this BLayoutItem's ancestors change visibility, 421 effectively hiding or showing this item. 422 423 Implementations of this method should alter the onscreen visibility of this 424 item. I.E. if \a shown is \c false, nothing should be drawn to represent 425 this item. 426 427 \note This method should not effect the value returned by this object's 428 IsVisible() method. 429 430 \param shown \c true to show, \c false to hide. 431 432 \since Haiku R1 433*/ 434 435 436//! @} 437