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