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, or NULL to use the virtual super item
584	       of level 0 items.
585	\param oneLevelOnly if \c true, only items located one level under
586	       superItem are considered.
587
588	\return The number of items under \a superItem.
589
590	\since BeOS R3
591*/
592
593
594/*!
595	\fn BListItem* BOutlineListView::EachItemUnder(BListItem* superItem,
596		bool oneLevelOnly, BListItem* (*eachFunc)(BListItem* item, void* arg),
597		void* arg)
598	\brief Calls \a eachFunc for each item under \a superItem.
599
600	\param superItem The base item, or NULL to use the virtual super item
601	       of level 0 items.
602	\param oneLevelOnly if \c true, only items located one level under
603	       superItem are considered.
604	\param eachFunc The function to call on each item.
605	\param arg The second argument of \a eachFunc.
606
607	\since BeOS R3
608*/
609
610
611/*!
612	\fn BListItem* BOutlineListView::ItemUnderAt(BListItem* superItem,
613		bool oneLevelOnly, int32 index) const
614	\brief Returns a pointer to the item at \a index under \a superItem.
615
616	\param superItem The base item, or NULL to use the virtual super item
617	       of level 0 items.
618	\param oneLevelOnly if \c true, only items located one level under
619	       superItem are considered.
620	\param index The index of the item to get.
621
622	\return A pointer to the item at \a index under \a superItem or \c NULL
623	        if not found.
624
625	\since BeOS R3
626*/
627
628
629/*!
630	\fn bool BOutlineListView::DoMiscellaneous(MiscCode code, MiscData* data)
631	\brief If \a code is \a B_SWAP_OP, swap the items in \a data, otherwise
632	       pass the arguments to BListView::DoMiscellaneous().
633
634	\param code The action \a code to use.
635	\param data The \a data to act on.
636
637	\see BListView::DoMiscellaneous()
638
639	\since Haiku R1
640*/
641
642
643/*!
644	\fn void BOutlineListView::ExpandOrCollapse(BListItem* item, bool expand)
645	\brief Toggle the expanded state of \a item.
646
647	\param item The \a item to toggle.
648	\param expand If \c true, expand the \a item, if \c false, collapse the
649	        \a item.
650
651	\since Haiku R1
652*/
653
654
655/*!
656	\fn BRect BOutlineListView::LatchRect(BRect itemRect, int32 level) const
657	\brief Used by derived classes to return the latch area.
658
659	\param itemRect The area of the item to get the latch area of.
660	\param level The \a level of the item to get the latch area of.
661
662	\since Haiku R1
663*/
664
665
666/*!
667	\fn void BOutlineListView::DrawLatch(BRect itemRect, int32 level,
668		bool collapsed, bool highlighted, bool misTracked)
669	\brief Used by derived classes to draw the latch.
670
671	\param itemRect The area of the item to get the latch area of,
672	       this is passed to LatchRect() to get the latch area.
673	\param level The \a level of the item to get the latch area of,
674	       also passed to LatchRect().
675	\param collapsed \c true to draw the latch in a collapsed state,
676	       \c false to draw the latch in an expanded state.
677	\param highlighted \c true to draw the latch in a selected state,
678	       \c false to draw the latch in an unselected state. Unused
679	       by the base class.
680	\param misTracked Unused by the base class.
681
682	\since Haiku R1
683*/
684
685
686/*!
687	\fn void BOutlineListView::DrawItem(BListItem* item, BRect itemRect,
688		bool complete)
689	\brief Used by derived classes to override how an \a item is drawn.
690
691	\param item The \a item to draw.
692	\param itemRect The area of the \a item to draw.
693	\param complete Whether or not to draw the background in addition to the
694	       contents.
695
696	\since Haiku R1
697*/
698