docs/user/interface/LayoutItem.dox

   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&apos;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&apos;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&apos;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&apos;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 //! @}