1/*! 2 \class BLayoutItem 3 \ingroup interface 4 \ingroup layout 5 \ingroup libbe 6 7 \brief Abstract class representing things that are positionable and 8 resizable by objects of the BLayout class. 9 10 The BLayoutItem class provides an interface that is meant to be used almost 11 exclusively by objects of the BLayout class. Despite this, there are some 12 methods that are provided for other users of the class. 13 14 \warning This class is not yet finalized, if you use it in your software 15 assume that it will break some time in the future. 16*/ 17 18 19/*! 20 \fn BLayoutItem::BLayoutItem(BMessage* archive) 21 \brief Archive constructor. 22 23 Creates a Bunarchiver for \a archive and calls its Finish() method. 24*/ 25 26 27/*! 28 \fn BLayout* BLayoutItem::Layout() const 29 \brief Returns the BLayout this BLayoutItem resides in. 30*/ 31 32 33/*! 34 \name Reporting size and alignment constraints to a BLayout 35 @{ 36*/ 37 38/*! 39 \fn BSize BLayoutItem::MinSize() = 0 40 \brief Returns the minimum desirable size for this item. 41*/ 42 43 44/*! 45 \fn BSize BLayoutItem::MaxSize() = 0 46 \brief Returns the maximum desirable size for this item. 47*/ 48 49 50/*! 51 \fn BSize BLayoutItem::PreferredSize() = 0 52 \brief Returns the preferred size for this item. 53*/ 54 55 56/*! 57 \fn BAlignment BLayoutItem::Alignment() = 0 58 \brief Returns the requested alignment for this item. 59 60 The value returned from this method is used in BLayoutItem::AlignInFrame(), 61 which BLayouts use to position and resize items. In a vertical BGroupLayout, 62 for example, although each item recieves the same horizontal area, each item 63 can use that area differently, aligning to the left, right or center for 64 example. 65*/ 66 67 68/*! 69 \fn bool BLayoutItem::HasHeightForWidth() 70 \brief Returns whether or not this BLayoutItem's height constraints are 71 dependent on its width. 72 73 \note By default, this method returns \c false. 74*/ 75 76 77/*! 78 \fn void BLayoutItem::GetHeightForWidth(float width, float* min, 79 float* max, float* preferred) 80 \brief Get this BLayoutItem's height constraints for a given \a width. 81 82 If a BLayoutItem does not have height for width constraints 83 (HasHeightForWidth() returns \c false) it does not need to implement this 84 method. 85 86 \note It is prudent to compare \a min, \a max, \a preferred to NULL before 87 dereferencing them. 88*/ 89 90 91//@} 92 93 94/*! 95 \name Overriding size constraints and alignment. 96 97 Although the explicit constraints placed on an item are not enforced by the 98 BLayoutItem class, all Haiku BLayoutItem subclasses will use the 99 BLayoutUtils::ComposeSize() or BLayoutUtils::ComposeAlignment() functions 100 in when reporting these constraints. It is recommended that all subclasses 101 do this as well, the BAbstractLayoutItem class provides any easy way to 102 include this behaviour in your class. 103 104 @{ 105*/ 106 107 108/*! 109 \fn void BLayoutItem::SetExplicitMinSize(BSize size) = 0 110 \brief Set this item's explicit min size, to be used in MinSize(). 111*/ 112 113 114/*! 115 \fn void BLayoutItem::SetExplicitMaxSize(BSize size) = 0 116 \brief Set this item's explicit max size, to be used in MaxSize(). 117*/ 118 119 120/*! 121 \fn void BLayoutItem::SetExplicitPreferredSize(BSize size) = 0 122 \brief Set this item's explicit preferred size, to be used in 123 PreferredSize(). 124*/ 125 126 127/*! 128 \fn void BLayoutItem::SetExplicitAlignment(BAlignment alignment) = 0 129 \brief Set this item's explicit alignment, to be used in Alignment(). 130*/ 131 132 133//@} 134 135 136/*! 137 \name Getting and setting the visiblity of a BLayoutItem. 138 139 These methods take into account only the local visibility of this 140 item, not the visibility of its ancestors. \n 141 142 @{ 143*/ 144 145 146/*! 147 \fn bool BLayoutItem::IsVisible() = 0 148 \brief Return the current local visibility of this item. If an item is not 149 visible, it will not be given space by the BLayout it resides in. 150 151 A simple implementation would return the last thing passed to SetVisible(). 152 A more complex implementation may deal with a BView that could 153 be hidden in any number of ways. 154*/ 155 156 157/*! 158 \fn void BLayoutItem::SetVisible(bool visible) = 0 159 \brief Set the local visibility of this item. 160*/ 161 162 163//@} 164 165 166/*! 167 \name Getting and setting the current on-screen positioning of \ 168 a BLayoutItem. 169 170 @{ 171*/ 172 173 174/*! 175 \fn void BLayoutItem::AlignInFrame(BRect frame) 176 \brief Position this BLayoutItem within \a frame, given the value returned 177 by Alignment(), and the size constraints for this item. 178*/ 179 180 181/*! 182 \fn BRect BLayoutItem::Frame() = 0 183 \brief Return the bounding frame of this item. 184 185 The returned BRect is in the coordinate system of the target view of the 186 BLayout this item belongs to. 187*/ 188 189 190/*! 191 \fn void BLayoutItem::SetFrame(BRect frame) = 0 192 \brief Set the bounding frame of this item. 193 194 \a frame is in the coordinate system of the target view of the 195 BLayout this item belongs to. 196*/ 197 198 199//@} 200 201 202/*! 203 \fn BView* BLayoutItem::View() 204 \brief Return the BView this item is representing, or NULL if it does not 205 represent any view. 206 207 When a BLayoutItem is added to a BLayout, this method is called, and the 208 returned BView will be added to the BLayout's target view. 209*/ 210 211 212/*! 213 \name Layout events and requests. 214 215 \brief These methods represent events or requests originating from a 216 BLayout. In some implementations they may be handled directly by this 217 BLayoutItem, but many implementations will forward these events to 218 another object. 219 220 @{ 221*/ 222 223 224/*! 225 \fn void BLayoutItem::InvalidateLayout(bool children = false) 226 \brief Invalidate the layout of this item, or the object it represents. 227 228 If \a children is \c true, then you should also invalidate any child 229 objects. 230*/ 231 232 233/*! 234 \fn void BLayoutItem::Relayout(bool immediate = false) 235 \brief Relayout any children or onscreen data this item contains. Often 236 this request is forwarded to another object. 237*/ 238 239 240//@} 241 242 243/*! 244 \name Utility methods for BLayout subclasses 245 \brief Utility methods for the BLayout class to attach and retrieve 246 arbitrary data for a BLayoutItem. 247 248 @{ 249*/ 250 251 252/*! 253 \fn void* BLayoutItem::LayoutData() const 254 \brief Retrieve arbitrary data attached to this BLayoutItem. 255 256 \note This method should only be called by a BLayout subclass. 257*/ 258 259 260/*! 261 \fn void BLayoutItem::SetLayoutData(void* data) 262 \brief Attach arbitrary data to this BLayoutItem. 263 264 \note This method should only be called by a BLayout subclass. 265*/ 266 267 268//@} 269 270 271/*! \name Hook methods 272 273 @{ 274*/ 275 276 277/*! 278 \fn void BLayoutItem::AttachedToLayout() 279 \brief Hook called when this object is attached to a BLayout (via 280 BLayout::AddItem()) 281 282 \note You can find the BLayout you've been attached to with the Layout() 283 method. 284*/ 285 286 287/*! 288 \fn void BLayoutItem::DetachedFromLayout(BLayout* layout) 289 \brief Hook called when this object is attached to a BLayout (via 290 BLayout::RemoveItem()) 291 \param layout The BLayout you were previously attached to. 292 293 \warning You should not use this hook to reattach \c this to \a BLayout, 294 doing so will cause undefined behaviour (probably a crash). 295*/ 296 297 298/*! 299 \fn void BLayoutItem::AncestorVisibilityChanged(bool shown) 300 \brief Hook called when this BLayoutItem's ancestors change visibility, 301 effectively hiding or showing this item. 302 303 Implementations of this method should alter the onscreen visibility of this 304 item. I.E. if \a shown is \c false, nothing should be drawn to represent 305 this item. 306 307 \note This method should not effect the value returned by this object's 308 IsVisible() method. 309*/ 310 311 312//@} 313