1/* 2 * Copyright 2013 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/OutlineListView.h hrev46526 10 * src/kits/interface/OutlineListView.cpp hrev46526 11 */ 12 13 14/*! 15 \file OutlineListView.h 16 \ingroup interface 17 \ingroup libbe 18 \brief Provides the BOutlineListView class. 19*/ 20 21 22/*! 23 \class BOutlineListView 24 \ingroup interface 25 \ingroup libbe 26 \brief Expands upon BListView to display a hierarchical list of items. 27 28 Items with subitems underneath them are called super items and are drawn 29 with a small arrow to the left of their label. The label faces right if 30 the item is collapsed and faces down if the item is expanded. 31 32 An example of an outline list view looks like this: 33 34 \image html BOutlineListView_example.png 35 36 \see BListView for more info on how to use a list view, most of which also 37 applies to an outline list view. 38 39 \since BeOS R3 40*/ 41 42 43/*! 44 \fn BOutlineListView::BOutlineListView(BRect frame, const char* name, 45 list_view_type type, uint32 resizingMode, uint32 flags) 46 \brief Creates a new BOutlineListView object. 47 48 \param frame The \a frame rectangle to create the view in. 49 \param name The name of the view. 50 \param type Whether the list view supports a single selection or multiple 51 selections. 52 \param resizingMode The resizing mode flags. See BView for details. 53 \param flags The view flags. See BView for details. 54 55 \since BeOS R3 56*/ 57 58 59/*! 60 \fn BOutlineListView::BOutlineListView(const char* name, 61 list_view_type type, uint32 flags) 62 \brief Creates a new BOutlineListView object suitable for use in a BLayout. 63 64 \param name The name of the view. 65 \param type Whether the list view supports a single selection or multiple 66 selections. 67 \param flags The view flags. See BView for details. 68 69 \since Haiku R1 70*/ 71 72 73/*! 74 \fn BOutlineListView::BOutlineListView(BMessage* archive) 75 \brief Creates a BOutlineListView object from the \a archive message. 76 77 \param archive The message to create the object from. 78 79 \since BeOS R3 80*/ 81 82 83/*! 84 \fn BOutlineListView::~BOutlineListView() 85 \brief Delete the outline BOutlineListView object and free the memory used 86 by it. 87 88 This method does not free the attached list items. 89 90 \since BeOS R3 91*/ 92 93 94/*! 95 \name Archiving 96*/ 97 98 99//! @{ 100 101 102/*! 103 \fn BArchivable* BOutlineListView::Instantiate(BMessage* archive) 104 \brief Create a new BOutlineListView object from the message \a archive. 105 106 \param archive The message to create the object from. 107 108 \since BeOS R3 109*/ 110 111 112/*! 113 \fn status_t BOutlineListView::Archive(BMessage* archive, bool deep) const 114 \brief Archive the BOutlineListView object to a message. 115 116 \param archive The message to archive the object to. 117 \param deep \c true to archive child views. 118 119 \since BeOS R3 120*/ 121 122 123//! @} 124 125 126/*! 127 \name Hook Methods 128*/ 129 130 131//! @{ 132 133 134/*! 135 \fn void BOutlineListView::AllAttached() 136 \copydoc BView::AllAttached() 137*/ 138 139 140/*! 141 \fn void BOutlineListView::AllDetached() 142 \copydoc BView::AllDetached() 143*/ 144 145 146/*! 147 \fn void BOutlineListView::DetachedFromWindow() 148 \brief Hook method that is called when the outline list view is removed from 149 the view hierarchy. 150 151 \copydetails BView::DetachedFromWindow() 152*/ 153 154 155/*! 156 \fn void BOutlineListView::FrameMoved(BPoint newPosition) 157 \brief Hook method called when the outline list view is moved. 158 159 \copydetails BView::FrameMoved() 160*/ 161 162 163/*! 164 \fn void BOutlineListView::FrameResized(float newWidth, float newHeight) 165 \brief Hook method called when the outline list view is resized. 166 167 \copydetails BView::FrameResized() 168*/ 169 170 171/*! 172 \fn void BOutlineListView::KeyDown(const char* bytes, int32 numBytes) 173 \brief Hook method that is called when a key is pressed while the view is 174 the focus view of the active window. 175 176 Responds to arrow keys to provide the ability to navigate the outline list 177 or to expand or collapse sections of the outline. Inherits the keys 178 recognized by BListView. 179 180 The following keys are used by the outline list view by default: 181 - Right Arrow Expands the selected item. 182 - Left Arrow Collapses the selected item. 183 184 \param bytes The bytes of the key combination pressed. 185 \param numBytes The number of bytes in \a bytes. 186 187 \see BListView::KeyDown() 188 189 \since BeOS R3 190*/ 191 192 193/*! 194 \fn void BOutlineListView::MessageReceived(BMessage* message) 195 \brief Hook method called when a message is received by the outline list 196 view. 197 198 \copydetails BView::MessageReceived() 199*/ 200 201 202/*! 203 \fn void BOutlineListView::MouseDown(BPoint where) 204 \brief Hook method called when a mouse button is pressed while the cursor 205 is contained in the frame of the outline list view. 206 207 Responds to mouse clicks expanding or collapsing sections of the outline 208 when the user clicks on a latch. 209 210 \param where The point on the screen where the mouse pointer is when 211 the mouse button is pressed. 212 213 \see BListView::MouseDown() 214 215 \since BeOS R3 216*/ 217 218 219/*! 220 \fn void BOutlineListView::MouseUp(BPoint where) 221 \brief Hook method that is called when a mouse button is released while 222 the cursor is contained in the frame of the outline list view. 223 224 \copydetails BView::MouseUp() 225*/ 226 227 228//! @} 229 230 231/*! 232 \name Adding/Removing Items 233*/ 234 235 236//! @{ 237 238 239/*! 240 \fn bool BOutlineListView::AddUnder(BListItem* item, BListItem* superItem) 241 \brief Adds the \a item one level deeper and immediately after \a superItem. 242 243 \param item The \a item to add. 244 \param superItem The item to add under, if \c NULL adds to end. 245 246 \return \c true if the \a item was added, \c false otherwise. 247 248 \since BeOS R3 249*/ 250 251 252/*! 253 \fn bool BOutlineListView::AddItem(BListItem* item) 254 \brief Adds the \a item to the end of the list. 255 256 \param item The \a item to add. 257 258 \return \c true if the \a item was added, \c false otherwise. 259 260 \since BeOS R3 261*/ 262 263 264/*! 265 \fn bool BOutlineListView::AddItem(BListItem* item, int32 fullListIndex) 266 \brief Adds the \a item at \a fullListIndex. 267 268 \param item The \a item to add. 269 \param fullListIndex The index to add \a item at. 270 271 \return \c true if the \a item was added, \c false otherwise. 272 273 \since BeOS R3 274*/ 275 276 277/*! 278 \fn bool BOutlineListView::AddList(BList* newItems) 279 \brief Adds a list of items to the end of the list. 280 281 \param newItems The list of items to add. 282 283 \return \c true if the items were added, \c false otherwise. 284 285 \since BeOS R3 286*/ 287 288 289/*! 290 \fn bool BOutlineListView::AddList(BList* newItems, int32 fullListIndex) 291 \brief Adds a list of items at \a fullListIndex 292 293 \param newItems The list of items to add. 294 \param fullListIndex The index at which to start adding the items. 295 296 \return \c true if the items were added, \c false otherwise. 297 298 \since BeOS R3 299*/ 300 301 302/*! 303 \fn bool BOutlineListView::RemoveItem(BListItem* item) 304 \brief Removes the \a item from the list. 305 306 \param item The \a item to remove. 307 308 \return \c true if the \a item was removed, \c false otherwise. 309 310 \since BeOS R3 311*/ 312 313 314/*! 315 \fn BListItem* BOutlineListView::RemoveItem(int32 fullListIndex) 316 \brief Removes the \a item located at \a fullListIndex from the list. 317 318 \return A pointer to the BListItem removed. 319 320 \since BeOS R3 321*/ 322 323 324/*! 325 \fn bool BOutlineListView::RemoveItems(int32 fullListIndex, int32 count) 326 \brief Removes \a count items starting at \a fullListIndex from the list. 327 328 \return \c true if the items were removed, \c false otherwise. 329 330 \since BeOS R3 331*/ 332 333 334//! @} 335 336 337/*! 338 \name Full List 339 340 These methods replicate similar methods in BListView, but they work on the 341 full list, without discarding collapsed items. 342*/ 343 344 345//! @{ 346 347 348/*! 349 \fn BListItem* BOutlineListView::FullListItemAt(int32 fullListIndex) const 350 \brief Returns a pointer to the BListItem at \a fullListIndex. 351 352 \return A pointer to the the BListItem at \a fullListIndex or \c NULL if not 353 found. 354 355 \see BListView::ItemAt(int32 index) 356 357 \since BeOS R3 358*/ 359 360 361/*! 362 \fn int32 BOutlineListView::FullListIndexOf(BPoint where) const 363 \brief Returns the full list index of the item at \a where. 364 365 \return The index of the item at \a where or -1 if not found. 366 367 \see BListView::IndexOf(BListItem* item) 368 369 \since BeOS R3 370*/ 371 372 373/*! 374 \fn int32 BOutlineListView::FullListIndexOf(BListItem* item) const 375 \brief Returns the full list index of \a item. 376 377 \return The index of \a item or -1 if not found. 378 379 \see BListView::IndexOf(BPoint point) 380 381 \since BeOS R3 382*/ 383 384 385/*! 386 \fn BListItem* BOutlineListView::FullListFirstItem() const 387 \brief Returns a pointer to the first BListItem in the list. 388 389 \return A pointer to the first item in the list or \c NULL if there are no 390 items. 391 392 \see BListView::FirstItem() 393 394 \since BeOS R3 395*/ 396 397 398/*! 399 \fn BListItem* BOutlineListView::FullListLastItem() const 400 \brief Returns a pointer to the list BListItem in the list 401 402 \return A pointer to the last item in the list or \c NULL if there are no 403 items. 404 405 \see BListView::LastItem() 406 407 \since BeOS R3 408*/ 409 410 411/*! 412 \fn bool BOutlineListView::FullListHasItem(BListItem* item) const 413 \brief Returns whether or not the list contains the specified \a item. 414 415 \param item The list item to check. 416 417 \return \c true if \a item is in the list, \c false otherwise. 418 419 \see BListView::HasItem(BListItem* item) 420 421 \since BeOS R3 422*/ 423 424 425/*! 426 \fn int32 BOutlineListView::FullListCountItems() const 427 \brief Returns the number of items contained in the outline list view. 428 429 \return The number of items. 430 431 \see BListView::CountItems() 432 433 \since BeOS R3 434*/ 435 436 437/*! 438 \fn int32 BOutlineListView::FullListCurrentSelection(int32 index) const 439 \brief Returns the index of a currently selected item relative to the passed 440 in \a index. 441 442 \param index The \a index of the item to get relative to the selected item's 443 index. 444 445 \see BListView::CurrentSelection(int32 index) 446 447 \since BeOS R3 448*/ 449 450 451/*! 452 \fn void BOutlineListView::MakeEmpty() 453 \brief Empties the outline list view of all items. 454 455 \since BeOS R3 456*/ 457 458 459/*! 460 \fn bool BOutlineListView::FullListIsEmpty() const 461 \brief Returns whether or not the outline list view is empty. 462 463 \return \c true if the outline list view is empty, \c false otherwise. 464 465 \see BListView::IsEmpty() 466 467 \since BeOS R3 468*/ 469 470 471/*! 472 \fn void BOutlineListView::FullListDoForEach(bool(*func)(BListItem* item)) 473 \brief Calls the specified function on each item in the outline list. 474 475 \param func The function to call on each item. 476 477 \see BListView::DoForEach(bool (*func)(BListItem* item)) 478 479 \since BeOS R3 480*/ 481 482 483/*! 484 \fn void BOutlineListView::FullListDoForEach(bool(*func)(BListItem* item, 485 void* arg), void* arg) 486 \brief Calls the specified function on each item in the outline list. 487 488 \param func The function to call on each item. 489 \param arg The second argument of the function. 490 491 \sa BListView::DoForEach(bool (*func)(BListItem* item, void* arg), 492 void* arg) 493 494 \since BeOS R3 495*/ 496 497 498//! @} 499 500 501/*! 502 \fn BListItem* BOutlineListView::Superitem(const BListItem* item) 503 \brief Returns a pointer to the item at one level above \a item. 504 505 \return A pointer to the superitem of \a item or \c NULL if the \a item 506 is at the outermost level or not found. 507 508 \since BeOS R3 509*/ 510 511 512/*! 513 \fn void BOutlineListView::Expand(BListItem* item) 514 \brief Expands the section referenced by \a item. 515 516 \since BeOS R3 517*/ 518 519 520/*! 521 \fn void BOutlineListView::Collapse(BListItem* item) 522 \brief Collapses the section referenced by \a item. 523 524 \since BeOS R3 525*/ 526 527 528/*! 529 \fn bool BOutlineListView::IsExpanded(int32 fullListIndex) 530 \brief Returns whether or not the section that the item at \a fullListIndex 531 is expanded or not. 532 533 \return \c true if the section is expanded, \c false if it is collapsed. 534 535 \since BeOS R3 536*/ 537 538 539/*! 540 \name Sorting 541*/ 542 543 544//! @{ 545 546 547/*! 548 \fn void BOutlineListView::FullListSortItems( 549 int (*compareFunc)(const BListItem* a, const BListItem* b)) 550 \brief Sorts the items according to the passed in compare function. 551 552 \param compareFunc The compare function to use to sort the items. 553 554 \see BListView::SortItems(int (*cmp)(const void *, const void *)) 555 556 \since BeOS R3 557*/ 558 559 560/*! 561 \fn void BOutlineListView::SortItemsUnder(BListItem* superItem, 562 bool oneLevelOnly, int (*compareFunc)(const BListItem* a, 563 const BListItem* b)) 564 \brief Sorts the items under \a superItem. 565 566 \param superItem The base item. 567 \param oneLevelOnly if \c true, only items located one level under 568 superItem are considered. 569 \param compareFunc The compare function to use to sort the items. 570 571 \since BeOS R3 572*/ 573 574 575//! @} 576 577 578/*! 579 \fn int32 BOutlineListView::CountItemsUnder(BListItem* superItem, 580 bool oneLevelOnly) const 581 \brief Returns the number of items under \a superItem. 582 583 \param superItem The base item. 584 \param oneLevelOnly if \c true, only items located one level under 585 superItem are considered. 586 587 \return The number of items under \a superItem. 588 589 \since BeOS R3 590*/ 591 592 593/*! 594 \fn BListItem* BOutlineListView::EachItemUnder(BListItem* superItem, 595 bool oneLevelOnly, BListItem* (*eachFunc)(BListItem* item, void* arg), 596 void* arg) 597 \brief Calls \a eachFunc for each item under \a superItem. 598 599 \param superItem The base item. 600 \param oneLevelOnly if \c true, only items located one level under 601 superItem are considered. 602 \param eachFunc The function to call on each item. 603 \param arg The second argument of \a eachFunc. 604 605 \since BeOS R3 606*/ 607 608 609/*! 610 \fn BListItem* BOutlineListView::ItemUnderAt(BListItem* superItem, 611 bool oneLevelOnly, int32 index) const 612 \brief Returns a pointer to the item at \a index under \a superItem. 613 614 \param superItem The base item. 615 \param oneLevelOnly if \c true, only items located one level under 616 superItem are considered. 617 \param index The index of the item to get. 618 619 \return A pointer to the item at \a index under \a superItem or \c NULL 620 if not found. 621 622 \since BeOS R3 623*/ 624 625 626/*! 627 \fn bool BOutlineListView::DoMiscellaneous(MiscCode code, MiscData* data) 628 \brief If \a code is \a B_SWAP_OP, swap the items in \a data, otherwise 629 pass the arguments to BListView::DoMiscellaneous(). 630 631 \param code The action \a code to use. 632 \param data The \a data to act on. 633 634 \see BListView::DoMiscellaneous() 635 636 \since Haiku R1 637*/ 638 639 640/*! 641 \fn void BOutlineListView::ExpandOrCollapse(BListItem* item, bool expand) 642 \brief Toggle the expanded state of \a item. 643 644 \param item The \a item to toggle. 645 \param expand If \c true, expand the \a item, if \c false, collapse the 646 \a item. 647 648 \since Haiku R1 649*/ 650 651 652/*! 653 \fn BRect BOutlineListView::LatchRect(BRect itemRect, int32 level) const 654 \brief Used by derived classes to return the latch area. 655 656 \param itemRect The area of the item to get the latch area of. 657 \param level The \a level of the item to get the latch area of. 658 659 \since Haiku R1 660*/ 661 662 663/*! 664 \fn void BOutlineListView::DrawLatch(BRect itemRect, int32 level, 665 bool collapsed, bool highlighted, bool misTracked) 666 \brief Used by derived classes to draw the latch. 667 668 \param itemRect The area of the item to get the latch area of, 669 this is passed to LatchRect() to get the latch area. 670 \param level The \a level of the item to get the latch area of, 671 also passed to LatchRect(). 672 \param collapsed \c true to draw the latch in a collapsed state, 673 \c false to draw the latch in an expanded state. 674 \param highlighted \c true to draw the latch in a selected state, 675 \c false to draw the latch in an unselected state. Unused 676 by the base class. 677 \param misTracked Unused by the base class. 678 679 \since Haiku R1 680*/ 681 682 683/*! 684 \fn void BOutlineListView::DrawItem(BListItem* item, BRect itemRect, 685 bool complete) 686 \brief Used by derived classes to override how an \a item is drawn. 687 688 \param item The \a item to draw. 689 \param itemRect The area of the \a item to draw. 690 \param complete Whether or not to draw the background in addition to the 691 contents. 692 693 \since Haiku R1 694*/ 695
