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