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 * Niels Sascha Reedijk, niels.reedijk@gmail.com 8 * 9 * Corresponds to: 10 * headers/os/interface/TwoDimensionalLayout.h rev 45833 11 * src/kits/interface/TwoDimensionalLayout.cpp rev 49507 12 */ 13 14 15/*! 16 \file TwoDimensionalLayout.h 17 \ingroup layout 18 \ingroup libbe 19 \brief Defines the BTwoDimensionalLayout class. 20*/ 21 22 23/*! 24 \class BTwoDimensionalLayout 25 \ingroup layout 26 \ingroup libbe 27 \brief Abstract BLayout subclass arranging items within rows and columns. 28 29 This class manages all the tricky work of actually positioning/resizing 30 items, as well as calculating size constraints and providing extra features, 31 such as spacing/insets and alignment of multiple 32 BTwoDimensionalLayout's. Derived classes need only implement a few hook 33 methods to get a working layout. 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 \struct BTwoDimensionalLayout::ColumnRowConstraints 44 \brief Used by BTwoDimensionalLayout derived classes to communicate the 45 size constraints for a given column or row to the 46 BTwoDimensionalLayout class. 47 48 \since Haiku R1 49*/ 50 51 52/*! 53 \var BTwoDimensionalLayout::ColumnRowConstraints::weight 54 \brief The weight of the given column or row. 55*/ 56 57 58/*! 59 \var BTwoDimensionalLayout::ColumnRowConstraints::min 60 \brief The minimum size of the given column or row. 61*/ 62 63 64/*! 65 \var BTwoDimensionalLayout::ColumnRowConstraints::max 66 \brief The maximum size of the given column or row. 67*/ 68 69 70/*! 71 \struct BTwoDimensionalLayout::Dimensions 72 \brief Used by BTwoDimensionalLayout derived classes to communicate the 73 positioning and size of a BLayoutItem, in terms of columns and rows 74 to the BTwoDimensionalLayout class. 75 76 \since Haiku R1 77*/ 78 79 80/*! 81 \var BTwoDimensionalLayout::Dimensions::x 82 \brief The column of the layout item. 83*/ 84 85 86/*! 87 \var BTwoDimensionalLayout::Dimensions::y 88 \brief The row of the layout item. 89*/ 90 91 92/*! 93 \var BTwoDimensionalLayout::Dimensions::width 94 \brief The number of columns the layout item spans. 95*/ 96 97 98/*! 99 \var BTwoDimensionalLayout::Dimensions::height 100 \brief The number of rows the layout item spans. 101*/ 102 103 104/*! 105 \fn BTwoDimensionalLayout::BTwoDimensionalLayout() 106 \brief Create an empty layout. 107*/ 108 109 110/*! 111 \fn BTwoDimensionalLayout::BTwoDimensionalLayout(BMessage* from) 112 \brief Unarchive constructor. 113*/ 114 115 116/*! 117 \fn virtual BTwoDimensionalLayout::~BTwoDimensionalLayout() 118 \brief Destructor. 119*/ 120 121 122/*! 123 \fn void BTwoDimensionalLayout::AlignLayoutWith( 124 BTwoDimensionalLayout* other, orientation orientation) 125 \brief Align the BLayoutItem's in the specified \a orientation within 126 two or more BTwoDimensionalLayout's. 127 128 When two (or more) BTwoDimensionalLayout's are aligned within a 129 certain \a orientation, then the BLayoutItem's within those 130 BTwoDimensionalLayout's will have identical widths or heights 131 (depending on how the BTwoDimensionalLayout's are aligned.) 132 133 If you align two BGroupLayout's horizontally for example, then the 134 BLayoutItem at index 0 in both BGroupLayout's will be given the same 135 horizontal area. The same is true for the BLayoutItem at index 1, 136 2, etc. Not all BTwoDimensionalLayout's have to have an item at each 137 index for the alignment to proceed. 138 139 \param other The BTwoDimensionalLayout to be aligned with. 140 \param orientation The \a orientation on which to be aligned. 141 142 \since Haiku R1 143*/ 144 145 146/*! 147 \fn void BTwoDimensionalLayout::SetInsets(float left, float top, 148 float right, float bottom) 149 \brief Set the insets for this layout. 150 151 Set the spacing around the edges of this layout. If you pass 152 \c B_USE_DEFAULT_SPACING for a certain parameter, that parameter will 153 be replaced with the value returned by BControlLook::DefaultItemSpacing(). 154 155 \since Haiku R1 156*/ 157 158 159/*! 160 \fn void BTwoDimensionalLayout::SetInsets(float horizontal, float vertical) 161 \brief Set the insets for this layout. 162 163 This is a convenience method to easily set similar insets. 164 165 \param horizontal The insets to the \em left and \em right of the layout. 166 \param vertical The insets at the \em top and \em bottom of the layout. 167 168 \since Haiku R1 169*/ 170 171 172/*! 173 \fn void BTwoDimensionalLayout::SetInsets(float insets) 174 \brief Set the insets for this layout. 175 176 This is a convenience method that to easily set all the insets of the 177 layout to the same value. 178 179 \param insets The inset to be applied to \em left, \em top, \em right and 180 \em bottom of this layout. 181 182 \since Haiku R1 183*/ 184 185 186/*! 187 \fn void BTwoDimensionalLayout::GetInsets(float* left, float* top, 188 float* right, float* bottom) const 189 \brief Get the insets for the BTwoDimensionalLayout (in pixels). 190 191 Passing \c NULL for any parameter is not an error, those parameters will 192 be ignored. 193 194 \see BTwoDimensionalLayout::SetInsets(); 195 196 \since Haiku R1 197*/ 198 199 200/*! 201 \name Hook Methods 202 203 These methods are called automatically as needed during layout, and 204 provide the BTwoDimensionalLayout class with the necessary information 205 to properly layout the BLayoutItem in this BTwoDimensionalLayout. 206*/ 207 208 209//! @{ 210 211 212/*! 213 \fn void BTwoDimensionalLayout::PrepareItems(orientation orientation) 214 \brief Prepare the BLayoutItem in this BTwoDimensionalLayout subclass 215 for layout within a certain \a orientation. 216 217 This is a good place to update cache information that will be used in 218 other hook methods, for example. 219 220 \since Haiku R1 221*/ 222 223 224/*! 225 \fn bool BTwoDimensionalLayout::HasMultiColumnItems() 226 \brief Tests whether or not this BTwoDimensionalLayout contains any 227 BLayoutItem's spanning more than one column. 228 229 The BTwoDimensionalLayout implementation returns false. 230 231 \since Haiku R1 232*/ 233 234 235/*! 236 \fn bool BTwoDimensionalLayout::HasMultiRowItems() 237 \brief Tests whether or not this BTwoDimensionalLayout contains any 238 BLayoutItem's spanning more than one row. 239 240 The BTwoDimensionalLayout implementation returns false. 241 242 \since Haiku R1 243*/ 244 245 246/*! 247 \fn int32 BTwoDimensionalLayout::InternalCountColumns() 248 \brief Get the number of columns in the BTwoDimensionalLayout. 249 250 \returns The number of columns in the BTwoDimensionalLayout. 251 252 \since Haiku R1 253*/ 254 255 256/*! 257 \fn int32 BTwoDimensionalLayout::InternalCountRows() 258 \brief Get the number of rows in the BTwoDimensionalLayout. 259 260 \returns The number of rows in the BTwoDimensionalLayout. 261 262 \since Haiku R1 263*/ 264 265 266/*! 267 \fn void BTwoDimensionalLayout::GetColumnRowConstraints( 268 orientation orientation, int32 index, ColumnRowConstraints* constraints) 269 \brief Fill in the ColumnRowConstraints for a certain column or row in 270 the BTwoDimensionalLayout. 271 272 This method is used to communicate the size constraints and weight for 273 a given row/column in the BTwoDimensionalLayout. 274 275 \since Haiku R1 276*/ 277 278 279/*! 280 \fn void BTwoDimensionalLayout::GetItemDimensions(BLayoutItem* item, 281 Dimensions* dimensions) 282 \brief Tell the base class what column and row a BLayoutItem is in as 283 well as how many columns and rows it covers. 284 285 \since Haiku R1 286*/ 287 288 289//! @} 290 291 292/*! 293 \name Protected helper methods for inset calculation. 294*/ 295 296 297//! @{ 298 299/*! 300 \fn BSize BTwoDimensionalLayout::AddInsets(BSize size) 301 \brief Add the \a size to all the insets for this layout. 302 303 \since Haiku R1 304*/ 305 306 307/*! 308 \fn void BTwoDimensionalLayout::AddInsets(float* minHeight, 309 float* maxHeight, float* preferredHeight) 310 \brief Add to the insets, and store the modified values. 311 312 \param[out] minHeight The value to add to the minimum height for this 313 layout. The new minimum height is stored at the variable of this 314 pointer. 315 \param[out] maxHeight The value to add to the maximum height for this 316 layout. The new maximum height is stored at the variable of this 317 pointer. 318 \param[out] preferredHeight the value to add to the preferred height for 319 this layout. The new preferred heifght is stored at the variable of 320 this pointer. 321 322 \since Haiku R1 323*/ 324 325/*! 326 \fn BSize BTwoDimensionalLayout::SubtractInsets(BSize size) 327 \brief Substract the \a size from all the insets for this layout. 328 329 \since Haiku R1 330*/ 331 332 333//! @} 334 335/*! 336 \name Current settings for spacing 337*/ 338 339 340//! @{ 341 342 343/*! 344 \var float BTwoDimensionalLayout::fLeftInset 345 \brief The current left inset for this layout. 346*/ 347 348 349/*! 350 \var float BTwoDimensionalLayout::fRightInset 351 \brief The current right inset for this layout. 352*/ 353 354 355/*! 356 \var float BTwoDimensionalLayout::fTopInset 357 \brief The current top inset for this layout. 358*/ 359 360 361/*! 362 \var float BTwoDimensionalLayout::fBottomInset 363 \brief The current bottom inset for this layout. 364*/ 365 366 367/*! 368 \var float BTwoDimensionalLayout::fHSpacing 369 \brief the current horizontal spacing between columns for this layout. 370*/ 371 372 373/*! 374 \var float BTwoDimensionalLayout::fVSpacing 375 \brief The current vertical spacing between rows for this layout. 376*/ 377 378//! @} 379