xref: /haiku/docs/user/interface/ScrollView.dox (revision 5a2ed95c230bb8bb0f4c7bdc3f29eb54ffa312f7) 
1/*
2 * Copyright 2014 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
4 *
5 * Authors:
6 *		John Scipione, jscipione@gmail.com
7 *
8 * Corresponds to:
9 *		headers/os/interface/ScrollView.h	 hrev47312
10 *		src/kits/interface/ScrollView.cpp	 hrev47312
11 */
12
13
14/*!
15	\file ScrollView.h
16	\ingroup interface
17	\ingroup libbe
18	\brief BScrollView class definition.
19	\since BeOS R3
20*/
21
22
23/*!
24	\class BScrollView
25	\ingroup interface
26	\ingroup libbe
27	\brief A convenience class used to add scrolling to a target view.
28
29	The BScrollView class conveniently provides a container view
30	adding the scroll bars and target view as siblings so that when one
31	is moved or resized the rest can follow.
32
33	\see BScrollBar to learn more about how scroll bars work.
34
35	\sa BView::ScrollTo()
36	\sa BView::ScrollBy()
37	\sa BView::TargetedByScrollView()
38
39	\since BeOS R3
40*/
41
42
43/*!
44	\fn BScrollView::BScrollView(const char* name, BView* target,
45		uint32 resizingMode, uint32 flags, bool horizontal, bool vertical,
46		border_style border)
47	\brief Instantiates a new scroll view and connects it to the \a target
48	       view.
49
50	\param name The name of the scroll bar, can be \c NULL.
51	\param target The \a target view to scroll, can be \c NULL.
52	\param resizingMode Defines the scroll view's behavior when its parent
53	       is resized. See BView for details.
54	\param flags The view flags. See BView for details.
55	\param horizontal Whether or not to include a horizontal scroll bar.
56	\param vertical Whether or not to include a vertical scroll bar.
57	\param border The border style to use, options include:
58		- \c B_PLAIN_BORDER
59		- \c B_FANCY_BORDER
60		- \c B_NO_BORDER
61
62	\sa SetTarget()
63	\sa SetBorder()
64
65	\since BeOS R3
66*/
67
68
69/*!
70	\fn BScrollView::BScrollView(const char* name, BView* target, uint32 flags,
71		bool horizontal, bool vertical, border_style border)
72	\brief Instantiates a new scroll view and connects it to the \a target
73	       view suitable for use in a BLayout.
74
75	\param name The name of the scroll bar, can be \c NULL.
76	\param target The \a target view to scroll, can be \c NULL.
77	\param flags The view flags. See BView for details.
78	\param horizontal Whether or not to include a horizontal scroll bar.
79	\param vertical Whether or not to include a vertical scroll bar.
80	\param border The border style to use, options include:
81		- \c B_PLAIN_BORDER
82		- \c B_FANCY_BORDER
83		- \c B_NO_BORDER
84
85	\sa SetTarget()
86	\sa SetBorder()
87
88	\since Haiku R1
89*/
90
91
92/*!
93	\fn BScrollView::BScrollView(BMessage* archive)
94	\brief Archive constructor.
95
96	\param archive The message \a data to construct the scroll view from.
97
98	\since BeOS R3
99*/
100
101
102/*!
103	\fn BScrollView::~BScrollView()
104	\brief Destructor method.
105
106	Deletes the scroll view, sets the target to \c NULL and frees any
107	memory used.
108
109	\since BeOS R3
110*/
111
112
113/*!
114	\name Archiving
115*/
116
117
118//! @{
119
120
121/*!
122	\fn BArchivable* BScrollView::Instantiate(BMessage* archive)
123	\brief Creates a new BScrollView object from the \a archive message.
124
125	\return A newly created scroll view or \c NULL if the message doesn't
126	        contain an archived BScrollView object.
127
128	\since BeOS R3
129*/
130
131
132/*!
133	\fn status_t BScrollView::Archive(BMessage* archive, bool deep) const
134	\brief Archives the object into the \a archive message.
135
136	\param archive A pointer to the BMessage object to archive the object into.
137	\param deep Whether or not to archive child views as well.
138
139	\return A status code, \c B_OK if everything went well or an error code
140	        otherwise.
141
142	\since BeOS R3
143*/
144
145
146//! @}
147
148
149/*!
150	\name Hook Methods
151*/
152
153
154//! @{
155
156
157/*!
158	\fn void BScrollView::AllAttached()
159	\copydoc BView::AllAttached()
160*/
161
162
163/*!
164	\fn void BScrollView::AllDetached()
165	\copydoc BView::AllDetached()
166*/
167
168
169/*!
170	\fn void BScrollView::AttachedToWindow()
171	\brief Hook method called when the scroll bar is attached to a window.
172
173	Checks if the window uses \c B_DOCUMENT_LOOK and adjust the size of the bars
174	to make room for the window resize knob.
175
176	\copydetails BView::AttachedToWindow()
177*/
178
179
180/*!
181	\fn void BScrollView::DetachedFromWindow()
182	\brief Hook method called when the object is detached from a window.
183
184	\copydetails BView::DetachedFromWindow()
185*/
186
187
188/*!
189	\fn void BScrollView::Draw(BRect updateRect)
190	\brief Draws the area of the scroll view that intersects \a updateRect.
191
192	\param updateRect The rectangular area to be drawn.
193
194	\since BeOS R3
195*/
196
197
198/*!
199	\fn void BScrollView::MakeFocus(bool focus)
200	\brief Makes the scroll view the current focus view of the window or gives
201	       up being the window's focus view.
202
203	\copydetails BView::MakeFocus()
204*/
205
206
207/*!
208	\fn void BScrollView::FrameMoved(BPoint newPosition)
209	\brief Hook method called when the scroll view is moved.
210
211	\copydetails BView::FrameMoved()
212*/
213
214
215/*!
216	\fn void BScrollView::FrameResized(float newWidth, float newHeight)
217	\brief Hook method called when the scroll view is resized.
218
219	\copydetails BView::FrameResized()
220*/
221
222
223/*!
224	\fn void BScrollView::MessageReceived(BMessage* message)
225	\copydoc BView::MessageReceived()
226*/
227
228
229/*!
230	\fn void BScrollView::MouseDown(BPoint where)
231	\copydoc BView::MouseDown()
232*/
233
234
235/*!
236	\fn void BScrollView::MouseMoved(BPoint where, uint32 code,
237		const BMessage* dragMessage)
238	\copydoc BView::MouseMoved()
239*/
240
241
242/*!
243	\fn void BScrollView::MouseUp(BPoint where)
244	\copydoc BView::MouseUp()
245*/
246
247
248/*!
249	\fn void BScrollView::WindowActivated(bool active)
250	\copydoc BView::WindowActivated()
251*/
252
253
254//! @}
255
256
257/*!
258	\fn void BScrollView::GetPreferredSize(float* _width, float* _height)
259	\brief Fill out the preferred width and height of the scroll view
260	       into the \a _width and \a _height parameters.
261
262	\copydetails BView::GetPreferredSize()
263*/
264
265
266/*!
267	\fn BSize BScrollView::MinSize()
268	\brief Return the scroll view's minimum size.
269
270	\return The minimum size of the scroll view as a BSize.
271
272	\sa BAbstractLayout::MinSize()
273
274	\since Haiku R1
275*/
276
277
278/*!
279	\fn BSize BScrollView::MaxSize()
280	\brief Return the scroll view's maximum size.
281
282	\return The maximum size of the scroll view as a BSize.
283
284	\sa BAbstractLayout::MaxSize()
285
286	\since Haiku R1
287*/
288
289
290/*!
291	\fn BSize BScrollView::PreferredSize()
292	\brief Return the scroll view's preferred size.
293
294	\return The preferred size of the scroll view as a BSize.
295
296	\sa BAbstractLayout::PreferredSize()
297
298	\since Haiku R1
299*/
300
301
302/*!
303	\fn void BScrollView::ResizeToPreferred()
304	\brief Resizes the scroll view to its preferred size keeping the position of
305	       the left top corner constant.
306
307	\copydetails BView::ResizeToPreferred()
308*/
309
310
311/*!
312	\name BScrollBar
313*/
314
315
316//! @{
317
318
319/*!
320	\fn BScrollBar* BScrollView::ScrollBar(orientation direction) const
321	\brief Returns the BScrollBar object at the given \a direction.
322
323	\param direction The \a direction of the desired scroll bar, one of the
324	       following:
325	       - \c B_HORIZONTAL to get the horizontal scroll bar
326	       - \c B_VERTICAL to get the vertical scroll bar
327
328	\returns A pointer to the desired BScrollBar object or \c NULL
329	         if there is no scroll bar at that location.
330
331	\since BeOS R3
332*/
333
334
335/*!
336	\fn void BScrollView::SetBorder(border_style border)
337	\brief Set the border style of the scroll view.
338
339	\param border The border style constant to use, on of the following:
340		- \c B_PLAIN_BORDER
341		- \c B_FANCY_BORDER
342		- \c B_NO_BORDER
343
344	\since BeOS R3
345*/
346
347
348/*!
349	\fn border_style BScrollView::Border() const
350	\brief Return the border style used.
351
352	\return The border style constant used.
353
354	\since BeOS R3
355*/
356
357
358/*!
359	\fn status_t BScrollView::SetBorderHighlighted(bool highlight)
360	\brief Highlights or unhighlights the border of the scroll view's
361	       scroll bars.
362
363	\param highlight \c true to turn highlighting on, \c false to remove it.
364
365	\return If successful returns \c B_OK, otherwise, returns \c B_ERROR.
366
367	\since BeOS R3
368*/
369
370
371/*!
372	\fn bool BScrollView::IsBorderHighlighted() const
373	\brief Returns whether or not the border is highlighted.
374
375	\return \c true if the border is highlighted, \c false otherwise.
376
377	\since BeOS R3
378*/
379
380
381/*!
382	\fn void BScrollView::SetTarget(BView* target)
383	\brief Sets the \a target view that the scroll bars operates on unsetting
384	       the previous target.
385
386	\param target The \a target view to set.
387
388	\since Haiku R1
389*/
390
391
392/*!
393	\fn BView* BScrollView::Target() const
394	\brief Returns a pointer to the target view.
395
396	\return A pointer to a BView object that represents the target view or
397	        \c NULL if the target is not set.
398
399	\since Haiku R1
400*/
401
402
403//! @}
404
405
406/*!
407	\name Scripting
408*/
409
410
411//! @{
412
413
414/*!
415	\fn BHandler* BScrollView::ResolveSpecifier(BMessage* message, int32 index,
416		BMessage* specifier, int32 what, const char* property)
417	\brief Determine the proper handler for a scripting message.
418
419	\copydetails BView::ResolveSpecifier()
420*/
421
422
423/*!
424	\fn status_t BScrollView::GetSupportedSuites(BMessage* message)
425	\brief Reports the suites of messages and specifiers understood by the
426	       scroll view.
427
428	\copydetails BView::GetSupportedSuites()
429*/
430
431
432//! @}
433
434
435/*!
436	\fn status_t BScrollView::Perform(perform_code code, void* _data)
437	\brief Perform some action. (Internal Method)
438
439	\since Haiku R1
440*/
441
442
443/*!
444	\fn void BScrollView::LayoutInvalidated(bool descendants)
445	\brief Hook method called when the layout is invalidated.
446
447	The default implementation does nothing.
448
449	\param descendants Whether or not child views have also been invalidated.
450
451	\since Haiku R1
452*/
453
454
455/*!
456	\fn void BScrollView::DoLayout()
457	\brief Layout view within the layout context.
458
459	\since Haiku R1
460*/
461