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