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