docs/user/interface/TabView.dox

   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         \fn BHandler* BTabView::ResolveSpecifier(BMessage* message, int32 index,
 599                 BMessage* specifier, int32 what, const char* property)
 600         \copydoc BHandler::ResolveSpecifier()
 601 */
 602
 603
 604 /*!
 605         \fn status_t BTabView::GetSupportedSuites(BMessage* message)
 606         \copydoc BHandler::GetSupportedSuites()
 607 */
 608
 609
 610 /*!
 611         \fn void BTabView::AddTab(BView* target, BTab* tab)
 612         \brief Adds the specified \a tab to the BTabView.
 613
 614         The tab is added to the end of the tab list. The new tab's target view is
 615         set to \a target. If \a tab is \c NULL, a new BTab object is constructed
 616         and added to the BTabView. You can get a pointer to the new tab by calling
 617         the TabAt() method.
 618
 619         If you choose to reimplement AddTab(), you should call this parent method
 620         at the end of your method.
 621
 622         \sa BTabView::TabAt()
 623
 624         \since BeOS R3
 625 */
 626
 627
 628 /*!
 629         \fn BTab* BTabView::RemoveTab(int32 index)
 630         \brief Removes the tab at the specified \a index from the BTabView and
 631                returns a pointer to the BTab object.
 632
 633         The BTab object is not deleted, if you don't need it anymore you should delete it.
 634
 635         \since BeOS R3
 636 */
 637
 638
 639 /*!
 640         \fn BTab* BTabView::TabAt(int32 index) const
 641         \brief Returns a pointer to the BTab object at the specified \a index.
 642
 643         \since BeOS R3
 644 */
 645
 646
 647 /*!
 648         \fn void BTabView::SetTabWidth(button_width width)
 649         \brief Sets the width of the tabs in the BTabView
 650
 651         \a width is one of the following:
 652         - \c B_WIDTH_FROM_WIDEST Each tab's width is determined from the width of the widest tab.
 653         - \c B_WIDTH_AS_USUAL The default tab width is used for all tabs.
 654         - \c B_WIDTH_FROM_LABEL The label of each tab determines the tab width.
 655
 656         \since BeOS R3
 657 */
 658
 659
 660 /*!
 661         \fn button_width BTabView::TabWidth() const
 662         \brief Returns the current tab width flag.
 663
 664         \since BeOS R3
 665 */
 666
 667
 668 /*!
 669         \fn void BTabView::SetTabHeight(float height)
 670         \brief Sets the height of the tabs to \a height.
 671
 672         \a height should be an integral value.
 673
 674         \since BeOS R3
 675 */
 676
 677
 678 /*!
 679         \fn float BTabView::TabHeight() const
 680         \brief Returns the current tab height.
 681
 682         \since BeOS R3
 683 */
 684
 685
 686 /*!
 687         \fn void BTabView::SetBorder(border_style borderStyle)
 688         \brief Sets the border style of the tab view to \a borderStyle.
 689
 690         \param borderStyle One of the following:
 691                - \c B_FANCY_BORDER (the default)
 692                - \c B_PLAIN_BORDER a plain line border,
 693                - \c B_NO_BORDER do not draw a border.
 694
 695         \since Haiku R1
 696 */
 697
 698
 699 /*!
 700         \fn border_style BTabView::Border() const
 701         \brief Returns the current border_style flag.
 702
 703         \since Haiku R1
 704 */
 705
 706
 707 /*!
 708         \fn BView* BTabView::ContainerView() const
 709         \brief Returns a pointer to the tab view's container view.
 710
 711         \since Haiku R1
 712 */
 713
 714
 715 /*!
 716         \fn int32 BTabView::CountTabs() const
 717         \brief Returns the number of tabs in the tab view.
 718
 719         \since Haiku R1
 720 */
 721
 722
 723 /*!
 724         \fn BView* BTabView::ViewForTab(int32 tabIndex) const
 725         \brief Returns the BView of the tab at the specified \a tabIndex.
 726
 727         \since Haiku R1
 728 */