xref: /haiku/docs/user/interface/LayoutItem.dox (revision 25a7b01d15612846f332751841da3579db313082)
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/LayoutItem.h  rev 38207
10 *		src/kits/interface/LayoutItem.cpp  rev 38207
11 */
12
13
14/*!
15	\file LayoutItem.h
16	\ingroup interface
17	\ingroup layout
18	\ingroup libbe
19	\brief Describes the BLayoutItem class.
20*/
21
22
23/*!
24	\class BLayoutItem
25	\ingroup interface
26	\ingroup layout
27	\ingroup libbe
28	\brief Abstract class representing things that are positionable and
29		resizable by objects of the BLayout class.
30
31	The BLayoutItem class provides an interface that is meant to be used almost
32	exclusively by objects of the BLayout class. Despite this, there are some
33	methods that are provided for other users of the class.
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
39
40/*!
41	\fn BLayoutItem::BLayoutItem(BMessage* archive)
42	\brief Archive constructor.
43
44	Creates a BLayoutItem from the \a archive message.
45*/
46
47
48/*!
49	\fn BLayout* BLayoutItem::Layout() const
50	\brief Returns the BLayout this BLayoutItem resides in.
51*/
52
53
54/*!
55	\fn BLayout::~BLayout()
56	\brief Destructor method.
57
58	Standard Destructor.
59*/
60
61
62/*!
63	\name Reporting size and alignment constraints to a BLayout
64*/
65
66
67//! @{
68
69
70/*!
71	\fn BSize BLayoutItem::MinSize() = 0
72	\brief Returns the minimum desirable size for this item.
73*/
74
75
76/*!
77	\fn BSize BLayoutItem::MaxSize() = 0
78	\brief Returns the maximum desirable size for this item.
79*/
80
81
82/*!
83	\fn BSize BLayoutItem::PreferredSize() = 0
84	\brief Returns the preferred size for this item.
85*/
86
87
88/*!
89	\fn BAlignment BLayoutItem::Alignment() = 0
90	\brief Returns the requested alignment for this item.
91
92	The value returned from this method is used in BLayoutItem::AlignInFrame(),
93	which BLayouts use to position and resize items. In a vertical BGroupLayout,
94	for example, although each item recieves the same horizontal area, each item
95	can use that area differently, aligning to the left, right or center for
96	example.
97*/
98
99
100/*!
101	\fn bool BLayoutItem::HasHeightForWidth()
102	\brief Returns whether or not this BLayoutItem's height constraints are
103		dependent on its width.
104
105	\note By default, this method returns \c false.
106*/
107
108
109/*!
110	\fn void BLayoutItem::GetHeightForWidth(float width, float* min,
111		float* max, float* preferred)
112	\brief Get this BLayoutItem's height constraints for a given \a width.
113
114	If a BLayoutItem does not have height for width constraints
115	(HasHeightForWidth() returns \c false) it does not need to implement this
116	method.
117
118	\note It is prudent to compare \a min, \a max, \a preferred to \c NULL
119	before dereferencing them.
120*/
121
122
123//! @}
124
125
126/*!
127	\name Overriding size constraints and alignment.
128
129	Although the explicit constraints placed on an item are not enforced by the
130	BLayoutItem class, all Haiku BLayoutItem subclasses will use the
131	BLayoutUtils::ComposeSize() or BLayoutUtils::ComposeAlignment() functions
132	in when reporting these constraints. It is recommended that all subclasses
133	do this as well, the BAbstractLayoutItem class provides any easy way to
134	include this behaviour in your class.
135*/
136
137
138//! @{
139
140
141/*!
142	\fn void BLayoutItem::SetExplicitMinSize(BSize size) = 0
143	\brief Set this item's explicit min size, to be used in MinSize().
144*/
145
146
147/*!
148	\fn void BLayoutItem::SetExplicitMaxSize(BSize size) = 0
149	\brief Set this item's explicit max size, to be used in MaxSize().
150*/
151
152
153/*!
154	\fn void BLayoutItem::SetExplicitPreferredSize(BSize size) = 0
155	\brief Set this item's explicit preferred size, to be used in
156		PreferredSize().
157*/
158
159
160/*!
161	\fn void BLayoutItem::SetExplicitAlignment(BAlignment alignment) = 0
162	\brief Set this item's explicit alignment, to be used in Alignment().
163*/
164
165
166//! @}
167
168
169/*!
170	\name Getting and setting the visiblity of a BLayoutItem.
171
172	These methods take into account only the local visibility of this
173	item, not the visibility of its ancestors. \n
174*/
175
176
177//! @{
178
179
180/*!
181	\fn bool BLayoutItem::IsVisible() = 0
182	\brief Return the current local visibility of this item. If an item is not
183		visible, it will not be given space by the BLayout it resides in.
184
185	A simple implementation would return the last thing passed to SetVisible().
186	A more complex implementation may deal with a BView that could
187	be hidden in any number of ways.
188*/
189
190
191/*!
192	\fn void BLayoutItem::SetVisible(bool visible) = 0
193	\brief Set the local visibility of this item.
194*/
195
196
197//! @}
198
199
200/*!
201	\name Getting and setting the current on-screen positioning of a BLayoutItem.
202*/
203
204
205//! @{
206
207
208/*!
209	\fn void BLayoutItem::AlignInFrame(BRect frame)
210	\brief Position this BLayoutItem within \a frame, given the value returned
211		by Alignment(), and the size constraints for this item.
212*/
213
214
215/*!
216	\fn BRect BLayoutItem::Frame() = 0
217	\brief Return the bounding frame of this item.
218
219	The returned BRect is in the coordinate system of the target view of the
220	BLayout this item belongs to.
221*/
222
223
224/*!
225	\fn void BLayoutItem::SetFrame(BRect frame) = 0
226	\brief Set the bounding frame of this item.
227
228	\a frame is in the coordinate system of the target view of the BLayout
229		that this item belongs to.
230*/
231
232
233//! @}
234
235
236/*!
237	\fn BView* BLayoutItem::View()
238	\brief Return the BView this item is representing, or \c NULL if it does not
239		represent any view.
240
241	When a BLayoutItem is added to a BLayout, this method is called, and the
242	returned BView will be added to the BLayout's target view.
243*/
244
245
246/*!
247	\name Layout events and requests.
248
249	\brief These methods represent events or requests originating from a
250	BLayout. In some implementations they may be handled directly by this
251	BLayoutItem, but many implementations will forward these events to
252	another object.
253*/
254
255
256//! @{
257
258
259/*!
260	\fn void BLayoutItem::InvalidateLayout(bool children = false)
261	\brief Invalidate the layout of this item, or the object it represents.
262	\param children Whether or not to invalidate children of this object.
263
264	Although this method is virtual, you should not override it in your classes,
265	override LayoutInvalidated() instead. This method will take care of calling
266	the InvalidateLayout() methods of affected views/layouts/items. However, if
267	there is an object that is somehow connected to this one by means other than
268	the standard mechanisms provided by the Haiku API, you should use
269	the LayoutInvalidated() hook to do this.
270*/
271
272
273/*!
274	\fn void BLayoutItem::Relayout(bool immediate = false)
275	\brief Relayout any children or onscreen data this item contains. Often
276		this request is forwarded to another object.
277
278	The default implementation of this method will likely be sufficient in
279	most cases. Assuming \c this->View() doesn't return \c NULL, the default
280	implementation calls Relayout() or Layout() on the value returned
281	by View().
282*/
283
284
285//! @}
286
287
288/*!
289	\name Utility methods for BLayout subclasses
290	\brief Utility methods for the BLayout class to attach and retrieve
291		arbitrary data for a BLayoutItem.
292*/
293
294
295//! @{
296
297
298/*!
299	\fn void* BLayoutItem::LayoutData() const
300	\brief Retrieve arbitrary data attached to this BLayoutItem.
301
302	\note This method should only be called by a BLayout subclass.
303*/
304
305
306/*!
307	\fn void BLayoutItem::SetLayoutData(void* data)
308	\brief Attach arbitrary data to this BLayoutItem.
309
310	\note This method should only be called by a BLayout subclass.
311*/
312
313
314//! @}
315
316
317/*!
318	\name Hook methods
319*/
320
321
322//! @{
323
324
325/*!
326	\fn void BLayoutItem::LayoutInvalidated(bool children)
327	\brief Hook called from InvalidateLayout().
328
329	Override this method to clean out an cached layout info. It is good
330	practice to recreate such info only on demand, eg when MinSize() or friends
331	are called.
332
333	If \a children is \c true, then you should invalidate any information on
334	child objects as well, and propagate the invalidation to them.
335*/
336
337
338/*!
339	\fn void BLayoutItem::AttachedToLayout()
340	\brief Hook called when this object is attached to a BLayout (via
341		BLayout::AddItem())
342
343	\note You can find the BLayout you've been attached to with the Layout()
344		method.
345*/
346
347
348/*!
349	\fn void BLayoutItem::DetachedFromLayout(BLayout* layout)
350	\brief Hook called when this object is attached to a BLayout (via
351		BLayout::RemoveItem())
352
353	\warning You should not use this hook to reattach \c this to \a BLayout,
354		doing so will cause undefined behaviour (probably a crash).
355
356	\param layout The BLayout you were previously attached to.
357*/
358
359
360/*!
361	\fn void BLayoutItem::AncestorVisibilityChanged(bool shown)
362	\brief Hook called when this BLayoutItem's ancestors change visibility,
363		effectively hiding or showing this item.
364
365	Implementations of this method should alter the onscreen visibility of this
366	item. I.E. if \a shown is \c false, nothing should be drawn to represent
367	this item.
368
369	\note This method should not effect the value returned by this object's
370		IsVisible() method.
371
372	\param shown \c true to show, \c false to hide.
373*/
374
375
376//! @}
377