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