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/TwoDimensionalLayout.h rev 38207 10 * src/kits/interface/TwoDimensionalLayout.cpp rev 38207 11 */ 12 13 14/*! 15 \file TwoDimensionalLayout.h 16 \ingroup interface 17 \ingroup layout 18 \ingroup libbe 19 \brief Defines the BTwoDimensionalLayout class. 20*/ 21 22 23/*! 24 \class BTwoDimensionalLayout 25 \ingroup interface 26 \ingroup layout 27 \ingroup libbe 28 \brief Abstract BLayout subclass arranging items within rows and columns. 29 30 This class manages all the tricky work of actually positioning/resizing 31 items, as well as calculating size constraints and providing extra features, 32 such as spacing/insets and alignment of multiple 33 BTwoDimensionalLayout's. Derived classes need only implement a few hook 34 methods to get a working layout. 35 36 \warning This class is not yet finalized, if you use it in your software 37 assume that it will break some time in the future. 38 39 \since Haiku R1 40*/ 41 42 43/*! 44 \struct BTwoDimensionalLayout::ColumnRowConstraints 45 \brief Used by BTwoDimensionalLayout derived classes to communicate the 46 size constraints for a given column or row to the 47 BTwoDimensionalLayout class. 48 49 \since Haiku R1 50*/ 51 52 53/*! 54 \struct BTwoDimensionalLayout::Dimensions 55 \brief Used by BTwoDimensionalLayout derived classes to communicate the 56 positioning and size of a BLayoutItem, in terms of columns and rows 57 to the BTwoDimensionalLayout class. 58 59 \since Haiku R1 60*/ 61 62 63/*! 64 \fn void BTwoDimensionalLayout::AlignLayoutWith( 65 BTwoDimensionalLayout* other, orientation orientation) 66 \brief Align the BLayoutItem's in the specified \a orientation within 67 two or more BTwoDimensionalLayout's. 68 69 When two (or more) BTwoDimensionalLayout's are aligned within a 70 certain \a orientation, then the BLayoutItem's within those 71 BTwoDimensionalLayout's will have identical widths or heights 72 (depending on how the BTwoDimensionalLayout's are aligned.) 73 74 If you align two BGroupLayout's horizontally for example, then the 75 BLayoutItem at index 0 in both BGroupLayout's will be given the same 76 horizontal area. The same is true for the BLayoutItem at index 1, 77 2, etc. Not all BTwoDimensionalLayout's have to have an item at each 78 index for the alignment to proceed. 79 80 \param other The BTwoDimensionalLayout to be aligned with. 81 \param orientation The \a orientation on which to be aligned. 82 83 \since Haiku R1 84*/ 85 86 87/*! 88 \fn void BTwoDimensionalLayout::SetInsets(float left, float top, 89 float right, float bottom) 90 \brief Set the insets for this BTwoDimensionalLayout (in pixels). 91 92 Set the spacing around the edges of this BTwoDimensionalLayout. If you 93 pass \c B_USE_DEFAULT_SPACING for a certain parameter, that parameter will 94 be replaced with the value returned by BControlLook::DefaultItemSpacing(). 95 96 \see BTwoDimensionalLayout::GetInsets(); 97 98 \since Haiku R1 99*/ 100 101 102/*! 103 \fn void BTwoDimensionalLayout::GetInsets(float* left, float* top, 104 float* right, float* bottom) const 105 \brief Get the insets for the BTwoDimensionalLayout (in pixels). 106 107 Passing \c NULL for any parameter is not an error, those parameters will 108 be ignored. 109 110 \see BTwoDimensionalLayout::SetInsets(); 111 112 \since Haiku R1 113*/ 114 115 116/*! 117 \name Hook Methods 118 119 These methods are called automatically as needed during layout, and 120 provide the BTwoDimensionalLayout class with the necessary information 121 to properly layout the BLayoutItem in this BTwoDimensionalLayout. 122*/ 123 124 125//! @{ 126 127 128/*! 129 \fn void BTwoDimensionalLayout::PrepareItems(orientation orientation) 130 \brief Prepare the BLayoutItem in this BTwoDimensionalLayout subclass 131 for layout within a certain \a orientation. 132 133 This is a good place to update cache information that will be used in 134 other hook methods, for example. 135 136 \since Haiku R1 137*/ 138 139 140/*! 141 \fn bool BTwoDimensionalLayout::HasMultiColumnItems() 142 \brief Tests whether or not this BTwoDimensionalLayout contains any 143 BLayoutItem's spanning more than one column. 144 145 The BTwoDimensionalLayout implementation returns false. 146 147 \since Haiku R1 148*/ 149 150 151/*! 152 \fn bool BTwoDimensionalLayout::HasMultiRowItems() 153 \brief Tests whether or not this BTwoDimensionalLayout contains any 154 BLayoutItem's spanning more than one row. 155 156 The BTwoDimensionalLayout implementation returns false. 157 158 \since Haiku R1 159*/ 160 161 162/*! 163 \fn int32 BTwoDimensionalLayout::InternalCountColumns() 164 \brief Get the number of columns in the BTwoDimensionalLayout. 165 166 \returns The number of columns in the BTwoDimensionalLayout. 167 168 \since Haiku R1 169*/ 170 171 172/*! 173 \fn int32 BTwoDimensionalLayout::InternalCountRows() 174 \brief Get the number of rows in the BTwoDimensionalLayout. 175 176 \returns The number of rows in the BTwoDimensionalLayout. 177 178 \since Haiku R1 179*/ 180 181 182/*! 183 \fn void BTwoDimensionalLayout::GetColumnRowConstraints( 184 orientation orientation, int32 index, ColumnRowConstraints* constraints) 185 \brief Fill in the ColumnRowConstraints for a certain column or row in 186 the BTwoDimensionalLayout. 187 188 This method is used to communicate the size constraints and weight for 189 a given row/column in the BTwoDimensionalLayout. 190 191 \since Haiku R1 192*/ 193 194 195/*! 196 \fn void BTwoDimensionalLayout::GetItemDimensions(BLayoutItem* item, 197 Dimensions* dimensions) 198 \brief Tell the base class what column and row a BLayoutItem is in as 199 well as how many columns and rows it covers. 200 201 \since Haiku R1 202*/ 203 204 205//! @} 206