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