xref: /haiku/docs/user/interface/TabView.dox (revision 4b918abdb02a26a770d898594eaaccc6f1726e9b)
1/*
2 * Copyright 2014 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
4 *
5 * Authors:
6 *		Augustin Cavalier <waddlesplash>
7 *		John Scipione, jscipione@gmail.com
8 *
9 * Corresponds to:
10 *		headers/os/interface/TabView.h	 hrev45377
11 *		src/kits/interface/TabView.cpp	 hrev45377
12 */
13
14
15/*!
16	\file TabView.h
17	\ingroup interface
18	\ingroup libbe
19	\brief Provides the BTab and BTabView classes.
20*/
21
22
23/*!
24	\enum tab_position
25	\ingroup interface
26
27	Tab position flags
28
29	\since BeOS R3
30*/
31
32
33/*!
34	\var tab_position B_TAB_FIRST
35
36	First tab in the tab view.
37
38	\since BeOS R3
39*/
40
41
42/*!
43	\var tab_position B_TAB_FRONT
44
45	Front most tab in the tab view.
46
47	\since BeOS R3
48*/
49
50
51/*!
52	\var tab_position B_TAB_ANY
53
54	Any tab in the tab view.
55
56	\since BeOS R3
57*/
58
59
60/*!
61	\class BTab
62	\ingroup interface
63	\ingroup libbe
64	\brief A tab that goes in a BTabView.
65
66	\since BeOS R3
67*/
68
69
70/*!
71	\fn BTab::BTab(BView* contentsView)
72	\brief Initializes a new BTab object as part of a \a tabView.
73
74	The BTab is enabled, but not selected nor the current focus. \a contentsView
75	is set as the tab's target view -- when the tab is selected, its target
76	view is activated.
77
78	\since BeOS R3
79*/
80
81
82/*!
83	\fn BTab::BTab(BMessage* archive)
84	\brief Archive Constructor.
85
86	\since BeOS R3
87*/
88
89
90/*!
91	\fn BTab::~BTab()
92	\brief Destructor.
93*/
94
95
96/*!
97	\fn BArchivable* BTab::Instantiate(BMessage* archive)
98	\brief Instantiates a BTab object from the passed in \a archive.
99
100	\since BeOS R3
101*/
102
103
104/*!
105	\fn status_t BTab::Archive(BMessage* data, bool deep) const
106	\brief Archives the object into the \a data message.
107
108	\param data A pointer to the BMessage object to archive the object into.
109	\param deep Whether or not to archive child views as well.
110
111	\return A status code, \c B_OK if everything went well or an error code
112	        otherwise.
113	\retval B_OK The object was archived.
114	\retval B_NO_MEMORY Ran out of memory while archiving the object.
115
116	\since BeOS R3
117*/
118
119
120/*!
121	\fn status_t BTab::Perform(uint32 d, void* arg)
122	\brief Perform some action. (Internal Method)
123
124	\since BeOS R3
125*/
126
127
128/*!
129	\fn const char* BTab::Label() const
130	\brief Returns the tab's label (the target view's name).
131
132	\since BeOS R3
133*/
134
135
136/*!
137	\fn void BTab::SetLabel(const char* label)
138	\brief Sets the target view's name, and updates the BTab accordingly.
139
140	\since BeOS R3
141*/
142
143
144/*!
145	\class BTabView
146	\ingroup interface
147	\ingroup libbe
148	\brief A container for BTab objects to display all tabs.
149
150	\since BeOS R3
151*/
152
153
154/*!
155	\fn bool BTab::IsSelected() const
156	\brief Returns whether or not the tab is selected.
157
158	\since BeOS R3
159*/
160
161
162/*!
163	\fn void BTab::Select(BView* owner)
164	\brief Called by the BTabView when the tab is selected.
165
166	\param owner The view that the tab's view should be owned by.
167
168	\since BeOS R3
169*/
170
171
172/*!
173	\fn void BTab::Deselect()
174	\brief Called by the BTabView when the tab is de-selected.
175
176	\since BeOS R3
177*/
178
179
180/*!
181	\fn void BTab::SetEnabled(bool enable)
182	\brief Enables or disables the tab.
183
184	\since BeOS R3
185*/
186
187
188/*!
189	\fn bool BTab::IsEnabled() const
190	\brief Returns whether or not the tab is enabled.
191*/
192
193
194/*!
195	\fn void BTab::MakeFocus(bool focus)
196	\brief Makes the tab the window's focus view or removes it.
197
198	\since BeOS R3
199*/
200
201
202/*!
203	\fn bool BTab::IsFocus() const
204	\brief Returns whether or not the tab is the window's focus view.
205*/
206
207
208/*!
209	\fn void BTab::SetView(BView* view)
210	\brief Sets the view to be displayed for this tab.
211*/
212
213
214/*!
215	\fn BView* BTab::View() const
216	\brief Returns a pointer to the view to be displayed for this tab.
217*/
218
219
220/*!
221	\fn void BTab::DrawFocusMark(BView* owner, BRect frame)
222	\brief Draws the mark indicating that the BTab object is in focus.
223
224	This consists of a blue line drawn across the bottom of the tab frame
225	by default.
226
227	\since BeOS R3
228*/
229
230
231/*!
232	\fn void BTab::DrawLabel(BView* owner, BRect frame)
233	\brief Draws the tab's title.
234
235	\since BeOS R3
236*/
237
238
239/*!
240	\fn void BTab::DrawTab(BView* owner, BRect frame, tab_position position,
241		bool full)
242	\brief Draws the tab.
243
244	This method draws the tab's title by calling DrawLabel(), then draws the
245	tab itself. The \a position of the tab may affect how the tab is rendered
246	-- for example the frontmost tab may have a different appearance than the
247	other tabs.
248
249	\param owner The view that owns the tab.
250	\param frame The frame rectangle to draw in.
251	\param position May affect how the tab is rendered. Choices include:
252	       - \c B_TAB_FIRST
253	       - \c B_TAB_FRONT
254	       - \c B_TAB_ANY
255	\param full Whether or not to completely draw the tab, no longer used.
256
257	\since BeOS R3
258*/
259
260
261/*!
262	\fn BTabView::BTabView(const char* name, button_width width, uint32 flags)
263	\brief Initializes a new BTabView object for use as part of a BLayout.
264
265	\param name The name of the tab view.
266	\param width The tab width flag to use. Options include:
267	       - \c B_WIDTH_AS_USUAL
268	       - \c B_WIDTH_FROM_WIDEST
269	       - \c B_WIDTH_FROM_LABEL
270	\param flags \a flags passed to BView.
271
272	\since Haiku R1
273*/
274
275
276/*!
277	\fn BTabView::BTabView(BRect frame, const char* name, button_width width,
278		uint32 resizeMask, uint32 flags)
279	\brief Initializes a new BTabView object.
280
281	\param frame The frame rectangle.
282	\param name The name of the tab view.
283	\param width The tab width flag to use. Options include:
284	       - \c B_WIDTH_AS_USUAL
285	       - \c B_WIDTH_FROM_WIDEST
286	       - \c B_WIDTH_FROM_LABEL
287	\param resizeMask Resizing mask, passed to BView.
288	\param flags \a flags passed to BView.
289
290	\since BeOS R3
291*/
292
293
294/*!
295	\fn BTabView::BTabView(BMessage* archive)
296	\brief Creates a BTabView object from the passed in \a archive.
297
298	\since BeOS R3
299*/
300
301
302/*!
303	\fn BTabView::~BTabView()
304	\brief Frees the memory allocated by each tab then destroys the object.
305
306	\since BeOS R3
307*/
308
309
310/*!
311	\name Archiving
312*/
313
314
315//! @{
316
317
318/*!
319	\fn BArchivable* BTabView::Instantiate(BMessage* archive)
320	\brief Instantiates a BTabView object from the passed in \a archive.
321
322	\since BeOS R3
323*/
324
325
326/*!
327	\fn status_t BTabView::Archive(BMessage* data, bool deep) const
328	\brief Archives the object into the \a data message.
329
330	\param data A pointer to the BMessage object to archive the object into.
331	\param deep Whether or not to archive child views as well.
332
333	\return A status code, \c B_OK if everything went well or an error code
334	        otherwise.
335	\retval B_OK The object was archived.
336	\retval B_NO_MEMORY Ran out of memory while archiving the object.
337
338	\since BeOS R3
339*/
340
341
342/*!
343	\fn status_t BTabView::AllUnarchived(const BMessage* from)
344	\brief Hook method called when all views have been unarchived.
345
346	\copydetails BView::AllUnarchived()
347*/
348
349
350//! @}
351
352
353/*!
354	\fn status_t BTabView::Perform(perform_code code, void* _data)
355	\brief Perform some action. (Internal Method)
356*/
357
358
359/*!
360	\name Hook Methods
361*/
362
363
364//! @{
365
366
367/*!
368	\fn void BTabView::AllAttached()
369	\copydoc BView::AllAttached()
370*/
371
372
373/*!
374	\fn void BTabView::AllDetached()
375	\copydoc BView::AllDetached()
376*/
377
378
379/*!
380	\fn void BTabView::AttachedToWindow()
381	\copydoc BView::AttachedToWindow()
382*/
383
384
385/*!
386	\fn void BTabView::DetachedFromWindow()
387	\copydoc BView::DetachedFromWindow()
388*/
389
390
391/*!
392	\fn void BTabView::Draw(BRect updateRect)
393	\brief Draws the focus tab and the tab view frame.
394
395	\since BeOS R3
396*/
397
398
399/*!
400	\fn BRect BTabView::DrawTabs()
401	\brief Draws all the tabs in the BTabView and returns the frame rectangle
402	       of the currently selected tab.
403
404	\since BeOS R3
405*/
406
407
408/*!
409	\fn void BTabView::DrawBox(BRect selectedTabRect)
410	\brief Draws the box that encloses the container view.
411
412	\param selectedTabRect The frame rectangle of the currently selected tab.
413
414	\since BeOS R3
415*/
416
417
418/*!
419	\fn void BTabView::FrameResized(float newWidth, float newHeight)
420	\copydoc BView::FrameResized()
421*/
422
423
424/*!
425	\fn void BTabView::KeyDown(const char* bytes, int32 numBytes)
426	\brief Handles keyboard navigation for the BTabView.
427
428	Down and left arrow keys move the focus tab left, up and right
429	arrow keys move the focus tab right. The space bar and enter keys
430	select the currently focused tab.
431
432	\sa BView::KeyDown()
433
434	\since BeOS R3
435*/
436
437
438/*!
439	\fn void BTabView::MessageReceived(BMessage* message)
440	\brief Handles scripting messages for the tab view.
441
442	\copydetails BView::MessageReceived()
443*/
444
445
446/*!
447	\fn void BTabView::MouseDown(BPoint where)
448	\brief Selects the tab that the user clicked on (if any).
449
450	\sa BView::MouseDown()
451
452	\since BeOS R3
453*/
454
455
456/*!
457	\fn void BTabView::MouseUp(BPoint where)
458	\copydoc BView::MouseUp()
459*/
460
461
462/*!
463	\fn void BTabView::MouseMoved(BPoint where, uint32 code,
464		const BMessage* dragMessage)
465	\copydoc BView::MouseMoved()
466*/
467
468
469/*!
470	\fn void BTabView::Pulse()
471	\copydoc BView::Pulse()
472*/
473
474
475/*!
476	\fn void BTabView::Select(int32 index)
477	\brief Selects the tab at the given \a index making it the selected tab.
478
479	\param index The zero-based tab index of the tab to select.
480
481	\since BeOS R3
482*/
483
484
485/*!
486	\fn int32 BTabView::Selection() const
487	\brief Returns the currently selected tab's index.
488
489	\since BeOS R3
490*/
491
492
493/*!
494	\fn void BTabView::WindowActivated(bool active)
495	\copydoc BView::WindowActivated()
496*/
497
498
499//! @}
500
501
502/*!
503	\fn void BTabView::MakeFocus(bool focus)
504	\brief Highlight or unhighlight the selection when the tab view acquires
505	       or loses its focus state.
506
507	\copydetails BView::MakeFocus()
508*/
509
510
511/*!
512	\fn void BTabView::SetFocusTab(int32 tab, bool focus)
513	\brief Sets the focus state of the specified \a tab.
514
515	\param tab The index of the tab to set the focus state of.
516	\param focus \c true to set focus, \c false to remove it.
517
518	\since BeOS R3
519*/
520
521
522/*!
523	\fn int32 BTabView::FocusTab() const
524	\brief Returns the index of the current focus tab.
525
526	\since BeOS R3
527*/
528
529
530/*!
531	\fn BRect BTabView::TabFrame(int32 index) const
532	\brief Returns the frame rectangle of the tab at the specified \a index.
533
534	\since BeOS R3
535*/
536
537
538/*!
539	\fn void BTabView::SetFlags(uint32 flags)
540	\copydoc BView::SetFlags()
541*/
542
543
544/*!
545	\fn void BTabView::SetResizingMode(uint32 mode)
546	\copydoc BView::SetResizingMode()
547*/
548
549
550/*!
551	\fn void BTabView::ResizeToPreferred()
552	\copydoc BView::ResizeToPreferred()
553*/
554
555
556/*!
557	\fn void BTabView::GetPreferredSize(float* _width, float* _height)
558	\copydoc BView::GetPreferredSize()
559*/
560
561
562/*!
563	\fn BSize BTabView::MinSize()
564	\brief Returns the tab view's minimum size in a BLayout.
565
566	\since Haiku R1
567*/
568
569
570/*!
571	\fn BSize BTabView::MaxSize()
572	\brief Returns the tab view's maximum size in a BLayout.
573
574	\since Haiku R1
575*/
576
577
578/*!
579	\fn BSize BTabView::PreferredSize()
580	\brief Returns the tab view's preferred size in a BLayout.
581
582	\since Haiku R1
583*/
584
585
586/*!
587	\fn void BTabView::FrameMoved(BPoint newPosition)
588	\copydoc BView::FrameMoved()
589*/
590
591
592/*!
593	\fn void BTabView::FrameResized(float newWidth, float newHeight)
594	\copydoc BView::FrameResized()
595*/
596
597
598/*!
599	\fn BHandler* BTabView::ResolveSpecifier(BMessage* message, int32 index,
600		BMessage* specifier, int32 what, const char* property)
601	\copydoc BHandler::ResolveSpecifier()
602*/
603
604
605/*!
606	\fn status_t BTabView::GetSupportedSuites(BMessage* message)
607	\copydoc BHandler::GetSupportedSuites()
608*/
609
610
611/*!
612	\fn void BTabView::AddTab(BView* target, BTab* tab)
613	\brief Adds the specified \a tab to the BTabView.
614
615	The tab is added to the end of the tab list. The new tab's target view is
616	set to \a target. If \a tab is \c NULL, a new BTab object is constructed
617	and added to the BTabView. You can get a pointer to the new tab by calling
618	the TabAt() method.
619
620	If you choose to reimplement AddTab(), you should call this parent method
621	at the end of your method.
622
623	\sa BTabView::TabAt()
624
625	\since BeOS R3
626*/
627
628
629/*!
630	\fn BTab* BTabView::RemoveTab(int32 index)
631	\brief Removes the tab at the specified \a index from the BTabView and
632	       returns a pointer to the BTab object.
633
634	The BTab object is not deleted, if you don't need it anymore you should delete it.
635
636	\since BeOS R3
637*/
638
639
640/*!
641	\fn BTab* BTabView::TabAt(int32 index) const
642	\brief Returns a pointer to the BTab object at the specified \a index.
643
644	\since BeOS R3
645*/
646
647
648/*!
649	\fn void BTabView::SetTabWidth(button_width width)
650	\brief Sets the width of the tabs in the BTabView
651
652	\a width is one of the following:
653	- \c B_WIDTH_FROM_WIDEST Each tab's width is determined from the width of the widest tab.
654	- \c B_WIDTH_AS_USUAL The default tab width is used for all tabs.
655	- \c B_WIDTH_FROM_LABEL The label of each tab determines the tab width.
656
657	\since BeOS R3
658*/
659
660
661/*!
662	\fn button_width BTabView::TabWidth() const
663	\brief Returns the current tab width flag.
664
665	\since BeOS R3
666*/
667
668
669/*!
670	\fn void BTabView::SetTabHeight(float height)
671	\brief Sets the height of the tabs to \a height.
672
673	\a height should be an integral value.
674
675	\since BeOS R3
676*/
677
678
679/*!
680	\fn float BTabView::TabHeight() const
681	\brief Returns the current tab height.
682
683	\since BeOS R3
684*/
685
686
687/*!
688	\fn void BTabView::SetBorder(border_style borderStyle)
689	\brief Sets the border style of the tab view to \a borderStyle.
690
691	\param borderStyle One of the following:
692	       - \c B_FANCY_BORDER (the default)
693	       - \c B_PLAIN_BORDER a plain line border,
694	       - \c B_NO_BORDER do not draw a border.
695
696	\since Haiku R1
697*/
698
699
700/*!
701	\fn border_style BTabView::Border() const
702	\brief Returns the current border_style flag.
703
704	\since Haiku R1
705*/
706
707
708/*!
709	\fn BView* BTabView::ContainerView() const
710	\brief Returns a pointer to the tab view's container view.
711
712	\since Haiku R1
713*/
714
715
716/*!
717	\fn int32 BTabView::CountTabs() const
718	\brief Returns the number of tabs in the tab view.
719
720	\since Haiku R1
721*/
722
723
724/*!
725	\fn BView* BTabView::ViewForTab(int32 tabIndex) const
726	\brief Returns the BView of the tab at the specified \a tabIndex.
727
728	\since Haiku R1
729*/
730