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