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 Displays and manipulates styled text. 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 \class BTabView 263 \ingroup interface 264 \ingroup libbe 265 \brief A container for BTab objects to display all tabs. 266 267 \since BeOS R3 268*/ 269 270 271/*! 272 \fn BTabView::BTabView(const char* name, button_width width, uint32 flags) 273 \brief Initializes a new BTabView object for use as part of a BLayout. 274 275 \param name The name of the tab view. 276 \param width The tab width flag to use. Options include: 277 - \c B_WIDTH_AS_USUAL 278 - \c B_WIDTH_FROM_WIDEST 279 - \c B_WIDTH_FROM_LABEL 280 \param flags \a flags passed to BView. 281 282 \since Haiku R1 283*/ 284 285 286/*! 287 \fn BTabView::BTabView(BRect frame, const char* name, button_width width, 288 uint32 resizeMask, uint32 flags) 289 \brief Initializes a new BTabView object. 290 291 \param frame The frame rectangle. 292 \param name The name of the tab view. 293 \param width The tab width flag to use. Options include: 294 - \c B_WIDTH_AS_USUAL 295 - \c B_WIDTH_FROM_WIDEST 296 - \c B_WIDTH_FROM_LABEL 297 \param resizeMask Resizing mask, passed to BView. 298 \param flags \a flags passed to BView. 299 300 \since BeOS R3 301*/ 302 303 304/*! 305 \fn BTabView::BTabView(BMessage* archive) 306 \brief Creates a BTabView object from the passed in \a archive. 307 308 \since BeOS R3 309*/ 310 311 312/*! 313 \fn BTabView::~BTabView() 314 \brief Frees the memory allocated by each tab then destroys the object. 315 316 \since BeOS R3 317*/ 318 319 320/*! 321 \name Archiving 322*/ 323 324 325//! @{ 326 327 328/*! 329 \fn BArchivable* BTabView::Instantiate(BMessage* archive) 330 \brief Instantiates a BTabView object from the passed in \a archive. 331 332 \since BeOS R3 333*/ 334 335 336/*! 337 \fn status_t BTabView::Archive(BMessage* data, bool deep) const 338 \brief Archives the object into the \a data message. 339 340 \param data A pointer to the BMessage object to archive the object into. 341 \param deep Whether or not to archive child views as well. 342 343 \return A status code, \c B_OK if everything went well or an error code 344 otherwise. 345 \retval B_OK The object was archived. 346 \retval B_NO_MEMORY Ran out of memory while archiving the object. 347 348 \since BeOS R3 349*/ 350 351 352/*! 353 \fn status_t BTabView::AllUnarchived(const BMessage* from) 354 \brief Hook method called when all views have been unarchived. 355 356 \copydetails BView::AllUnarchived() 357*/ 358 359 360//! @} 361 362 363/*! 364 \fn status_t BTabView::Perform(perform_code code, void* _data) 365 \brief Perform some action. (Internal Method) 366*/ 367 368 369/*! 370 \name Hook Methods 371*/ 372 373 374//! @{ 375 376 377/*! 378 \fn void BTabView::AllAttached() 379 \copydoc BView::AllAttached() 380*/ 381 382 383/*! 384 \fn void BTabView::AllDetached() 385 \copydoc BView::AllDetached() 386*/ 387 388 389/*! 390 \fn void BTabView::AttachedToWindow() 391 \copydoc BView::AttachedToWindow() 392*/ 393 394 395/*! 396 \fn void BTabView::DetachedFromWindow() 397 \copydoc BView::DetachedFromWindow() 398*/ 399 400 401/*! 402 \fn void BTabView::Draw(BRect updateRect) 403 \brief Draws the focus tab and the tab view frame. 404 405 \since BeOS R3 406*/ 407 408 409/*! 410 \fn BRect BTabView::DrawTabs() 411 \brief Draws all the tabs in the BTabView and returns the frame rectangle 412 of the currently selected tab. 413 414 \since BeOS R3 415*/ 416 417 418/*! 419 \fn void BTabView::DrawBox(BRect selTabRect) 420 \brief Draws the box that encloses the container view. 421 422 \param selTabRect The frame rectangle of the currently selected tab. 423 424 \since BeOS R3 425*/ 426 427 428/*! 429 \fn void BTabView::FrameResized(float newWidth, float newHeight) 430 \copydoc BView::FrameResized() 431*/ 432 433 434/*! 435 \fn void BTabView::KeyDown(const char* bytes, int32 numBytes) 436 \brief Handles keyboard navigation for the BTabView. 437 438 Down and left arrow keys move the focus tab left, up and right 439 arrow keys move the focus tab right. The space bar and enter keys 440 select the currently focused tab. 441 442 \sa BView::KeyDown() 443 444 \since BeOS R3 445*/ 446 447 448/*! 449 \fn void BTabView::MessageReceived(BMessage* message) 450 \brief Handles scripting messages for the tab view. 451 452 \copydetails BView::MessageReceived() 453*/ 454 455 456/*! 457 \fn void BTabView::MouseDown(BPoint where) 458 \brief Selects the tab that the user clicked on (if any). 459 460 \sa BView::MouseDown() 461 462 \since BeOS R3 463*/ 464 465 466/*! 467 \fn void BTabView::MouseUp(BPoint where) 468 \copydoc BView::MouseUp() 469*/ 470 471 472/*! 473 \fn void BTabView::MouseMoved(BPoint where, uint32 code, 474 const BMessage* dragMessage) 475 \copydoc BView::MouseMoved() 476*/ 477 478 479/*! 480 \fn void BTabView::Pulse() 481 \copydoc BView::Pulse() 482*/ 483 484 485/*! 486 \fn void BTabView::Select(int32 index) 487 \brief Selects the tab at the given \a index making it the selected tab. 488 489 \param index The zero-based tab index of the tab to select. 490 491 \since BeOS R3 492*/ 493 494 495/*! 496 \fn int32 BTabView::Selection() const 497 \brief Returns the currently selected tab's index. 498 499 \since BeOS R3 500*/ 501 502 503/*! 504 \fn void BTabView::WindowActivated(bool active) 505 \copydoc BView::WindowActivated() 506*/ 507 508 509//! @} 510 511 512/*! 513 \fn void BTabView::MakeFocus(bool focus) 514 \brief Highlight or unhighlight the selection when the tab view acquires 515 or loses its focus state. 516 517 \copydetails BView::MakeFocus() 518*/ 519 520 521/*! 522 \fn void BTabView::SetFocusTab(int32 tab, bool focus) 523 \brief Sets the focus state of the specified \a tab. 524 525 \param tab The index of the tab to set the focus state of. 526 \param focus \c true to set focus, \c false to remove it. 527 528 \since BeOS R3 529*/ 530 531 532/*! 533 \fn int32 BTabView::FocusTab() const 534 \brief Returns the index of the current focus tab. 535 536 \since BeOS R3 537*/ 538 539 540/*! 541 \fn BRect BTabView::TabFrame(int32 index) const 542 \brief Returns the frame rectangle of the tab at the specified \a index. 543 544 \since BeOS R3 545*/ 546 547 548/*! 549 \fn void BTabView::SetFlags(uint32 flags) 550 \copydoc BView::SetFlags() 551*/ 552 553 554/*! 555 \fn void BTabView::SetResizingMode(uint32 mode) 556 \copydoc BView::SetResizingMode() 557*/ 558 559 560/*! 561 \fn void BTabView::ResizeToPreferred() 562 \copydoc BView::ResizeToPreferred() 563*/ 564 565 566/*! 567 \fn void BTabView::GetPreferredSize(float* _width, float* _height) 568 \copydoc BView::GetPreferredSize() 569*/ 570 571 572/*! 573 \fn BSize BTabView::MinSize() 574 \brief Returns the tab view's minimum size in a BLayout. 575 576 \since Haiku R1 577*/ 578 579 580/*! 581 \fn BSize BTabView::MaxSize() 582 \brief Returns the tab view's maximum size in a BLayout. 583 584 \since Haiku R1 585*/ 586 587 588/*! 589 \fn BSize BTabView::PreferredSize() 590 \brief Returns the tab view's preferred size in a BLayout. 591 592 \since Haiku R1 593*/ 594 595 596/*! 597 \fn void BTabView::FrameMoved(BPoint newPosition) 598 \copydoc BView::FrameMoved() 599*/ 600 601 602/*! 603 \fn void BTabView::FrameResized(float newWidth, float newHeight) 604 \copydoc BView::FrameResized() 605 606 607/*! 608 \fn BHandler* BTabView::ResolveSpecifier(BMessage* message, int32 index, 609 BMessage* specifier, int32 what, const char* property) 610 \copydoc BHandler::ResolveSpecifier() 611*/ 612 613 614/*! 615 \fn status_t BTabView::GetSupportedSuites(BMessage* message) 616 \copydoc BHandler::GetSupportedSuites() 617*/ 618 619 620/*! 621 \fn void BTabView::AddTab(BView* target, BTab* tab) 622 \brief Adds the specified \a tab to the BTabView. 623 624 The tab is added to the end of the tab list. The new tab's target view is 625 set to \a target. If \a tab is \c NULL, a new BTab object is constructed 626 and added to the BTabView. You can get a pointer to the new tab by calling 627 the TabAt() method. 628 629 If you choose to reimplement AddTab(), you should call this parent method 630 at the end of your method. 631 632 \sa BTabView::TabAt() 633 634 \since BeOS R3 635*/ 636 637 638/*! 639 \fn BTab* BTabView::RemoveTab(int32 index) 640 \brief Removes the tab at the specified \a index from the BTabView and 641 returns a pointer to the BTab object. 642 643 The BTab object is not deleted, if you don't need it anymore you should delete it. 644 645 \since BeOS R3 646*/ 647 648 649/*! 650 \fn BTab* BTabView::TabAt(int32 index) const 651 \brief Returns a pointer to the BTab object at the specified \a index. 652 653 \since BeOS R3 654*/ 655 656 657/*! 658 \fn void BTabView::SetTabWidth(button_width width) 659 \brief Sets the width of the tabs in the BTabView 660 661 \a width is one of the following: 662 - \c B_WIDTH_FROM_WIDEST Each tab's width is determined from the width of the widest tab. 663 - \c B_WIDTH_AS_USUAL The default tab width is used for all tabs. 664 - \c B_WIDTH_FROM_LABEL The label of each tab determines the tab width. 665 666 \since BeOS R3 667*/ 668 669 670/*! 671 \fn button_width BTabView::TabWidth() const 672 \brief Returns the current tab width flag. 673 674 \since BeOS R3 675*/ 676 677 678/*! 679 \fn void BTabView::SetTabHeight(float height) 680 \brief Sets the height of the tabs to \a height. 681 682 \a height should be an integral value. 683 684 \since BeOS R3 685*/ 686 687 688/*! 689 \fn float BTabView::TabHeight() const 690 \brief Returns the current tab height. 691 692 \since BeOS R3 693*/ 694 695 696/*! 697 \fn void BTabView::SetBorder(border_style border) 698 \brief Sets the border of the tab view to \a border. 699 700 \since Haiku R1 701*/ 702 703 704/*! 705 \fn border_style BTabView::Border() const 706 \brief Returns the current border_style flag. 707 708 \since Haiku R1 709*/ 710 711 712/*! 713 \fn BView* BTabView::ContainerView() const 714 \brief Returns a pointer to the tab view's container view. 715 716 \since Haiku R1 717*/ 718 719 720/*! 721 \fn int32 BTabView::CountTabs() const 722 \brief Returns the number of tabs in the tab view. 723 724 \since Haiku R1 725*/ 726 727 728/*! 729 \fn BView* BTabView::ViewForTab(int32 tabIndex) const 730 \brief Returns the BView of the tab at the specified \a tabIndex. 731 732 \since Haiku R1 733*/ 734 735