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*/ 729