BOutlineListView¶
Constructor and Destructor¶
BOutlineListView()
BOutlineListView::BOutlineListView(BRect frame, const char *name, list_view_type type = B_SINGLE_SELECTION_LIST, uint32 resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP, uint32 flags = B_WILL_DRAW | B_FRAME_EVENTS | B_NAVIGABLE)
BOutlineListView::BOutlineListView(BMessage *archive)
Initializes the BOutlineListView. This constructor matches the
BListView
constructor in every detail, including default
arguments. All argument values are passed to the BListView
constructor
without change. The
BOutlineListView class doesn’t do any initialization of its own.
~BOutlineListView()
virtual BOutlineListView::~BOutlineListView()
Does nothing; this class relies on the BListView
constructor
destructor.
Hook Functions¶
KeyDown()
virtual void BOutlineListView::KeyDown(const char *bytes, int32 numBytes)
Augments the inherited version of KeyDown()
to allow users to navigate the outline hierarchy
using the arrow keys and to expand or collapse sections of the outline
using Control—arrow key combinations.
MouseDown()
virtual void BOutlineListView::MouseDown(BPoint point)
Augments the inherited version of MouseDown()
to permit users to expand and collapse sections of the
outline by clicking on an item’s latch.
Member Functions¶
AddItem(), AddUnder()
virtual bool BOutlineListView::AddItem(BListItem *item)
virtual bool BOutlineListView::AddItem(BListItem *item, int32 index)
virtual bool BOutlineListView::AddUnder(BListItem *item, BListItem *superitem)
These functions add an item to the list. AddItem()
adds the item at index—where the index counts all items assigned
to the BOutlineListView—or, if an index isn’t
specified, at the end of the list. The two versions of this function
override their BListView
counterparts to ensure that the item
is correctly entered into the outline. If the item is added to a portion of
the list that is collapsed, it won’t be visible.
AddUnder() adds an item immediately after another item in the list and at one outline level deeper. The level of the item is modified accordingly. Thus, the item already in the list becomes the superitem for the newly added item. If its new superitem is collapsed or is in a collapsed part of the list, the item will not be visible.
Unlike AddUnder(), AddItem() respects the outline level of the item. By setting the item’s level before calling AddItem(), you can add it as a subitem to an item at a higher outline level or insert it as a superitem to items at a lower level.
See also: the BListItem
class
AddList()
virtual bool BOutlineListView::AddList(BList *newItems)
virtual bool BOutlineListView::AddList(BList *newItems, int32 index)
Adds a group of items to the list just as AddItem()
adds a single item. The index counts
all items assigned to the BOutlineListView. The
newItems BList
must contain pointers to
BListItem
objects.
See also: BListView::AddList()
Archive()
virtual status_t BOutlineListView::Archive(BMessage *archive, bool deep = true) const
Archives the BOutlineListView object much as the
Archive()
function in the
BListView
class does, but makes sure that all items are
archived, including items in collapsed sections of the list, when the
deep flag is true.
See also: BListView::Archive()
, Instantiate()
static function
Collapse(), Expand()
void BOutlineListView::Collapse(BListItem *item)
void BOutlineListView::Expand(BListItem *item)
These functions collapse and expand the section of the list controlled by the item superitem. If item isn’t a superitem, it is nevertheless flagged as expanded or collapsed so that it will behave appropriately in case it does become a superitem.
See also: BListItem::SetExpanded()
CountItemsUnder()
int32 BOutlineListView::CountItemsUnder(BListItem *underItem, bool oneLevelOnly) const
Counts the items located under the underItem superitem and returns that value. If the oneLevelOnly argument is true, only items directly contained within the specified superitem are considered. If oneLevelOnly is false, all subitems of the specified item are considered, as are all subitems of those subitems and so forth.
Note
When oneLevelOnly is false,
CountItemsUnder() acts just like FullListCountItems()
, except the first item in the list
that’s considered is underItem instead of the first item in the
full list.
See also: BListView::CountItems()
EachItemUnder()
BListItem *BOutlineListView::EachItemUnder(BListItem *underItem, bool oneLevelOnly, BListItem *(*eachFunc)(BListItem*, void*), void *data)
Calls the function eachFunc for every item located under the underItem superitem. If oneLevelOnly is true, eachFunc is only called for items located directly under the underItem; if oneLevelOnly is false, the eachFunc is called once for every subitem of underItem, including subitems of subitems, recursively.
The data argument is passed through to each call to the eachFunc function as the second argument to that function, and may be used for whatever purpose your eachFunc requires.
If the eachFunc function returns a pointer to a
BListItem
(rather than NULL), processing is
stopped immediately, even if there are items still unvisited. The
BListItem
pointer returned by the eachFunc function
is returned by EachItemUnder().
Note
When oneLevelOnly is false,
EachItemUnder() acts just like FullListDoForEach()
, except the first item in the list
that’s considered is underItem instead of the first item in the
full list.
See also: BListView::DoForEach()
FullListCountItems(), FullListCurrentSelection(), FullListFirstItem(), FullListLastItem(), FullListIndexOf(), FullListItemAt(), FullListHasItem(), FullListIsEmpty(), FullListDoForEach(), FullListSortItems()
int32 BOutlineListView::FullListCountItems() const
int32 BOutlineListView::FullListCurrentSelection(int32 index = 0) const
BListItem *BOutlineListView::FullListFirstItem() const
BListItem *BOutlineListView::FullListLastItem() const
int32 BOutlineListView::FullListIndexOf(BPoint point) const
int32 BOutlineListView::FullListIndexOf(BListItem *item) const
BListItem *BOutlineListView::FullListItemAt(int32 index) const
bool BOutlineListView::FullListHasItem(BListItem *item) const
bool BOutlineListView::FullListIsEmpty() const
void BOutlineListView::FullListDoForEach(bool (*func)(BListItem*))
void BOutlineListView::FullListDoForEach(bool (*func)(BListItem*), void* ))
void BOutlineListView::FullListDoForEach(bool (*func)(BListItem*), void* ), void* )
void BOutlineListView::FullListSortItems(int (*compareFunc)(const BListItem*, const BListItem*))
These functions parallel a similar set of functions defined in the
BListView
class. The BListView
functions have
identical names, but without the FullList…() prefix. When
applied to a BOutlineListView object, the inherited functions
consider only items in sections of the outline that can be displayed
on-screen—that is, they skip over items in collapsed portions of the list.
These BOutlineListView functions, on the other hand, consider
all items in the list. For example, IndexOf()
and FullListIndexOf() both return an index
to a given item. However, for IndexOf()
the index is to the position of the item in the list that can be currently
displayed, but for FullListIndexOf() it’s to the item’s position
in the full list, including collapsed sections.
IsExpanded()
bool BOutlineListView::IsExpanded(int32 index)
Returns true if the item at index is marked as controlling an expanded section of the list, and false if it’s marked as controlling a collapsed section or if there’s no item at that index. If a superitem is expanded, the BOutlineListView can display its subitems; if not, the subitems are hidden.
The index passed to this function is to the full list of items assigned to the BOutlineListView.
See also: BListItem::IsExpanded()
ItemUnderAt()
BListItem *BOutlineListView::ItemUnderAt(BListItem *underItem, bool oneLevelOnly, int32 index) const
Returns a pointer to the indexth item under the specified underItem. If oneLevelOnly is true, only items located directly under the underItem are considered. If oneLevelOnly is false, subitems are scanned recursively to locate the appropriate index.
Note
When oneLevelOnly is false, ItemUnderAt()
acts just like FullListItemAt()
, except the first item in the list
that’s considered is underItem instead of the first item in the
full list.
MakeEmpty()
virtual void BOutlineListView::MakeEmpty()
Overrides the BListView
version of MakeEmpty()
to remove all items from the list. The
BListView
version of this function won’t work as advertised on
a BOutlineListView.
RemoveItem(), RemoveItems()
virtual bool BOutlineListView::RemoveItem(BListItem *item)
virtual BListItem *BOutlineListView::RemoveItem(int32 index)
virtual bool BOutlineListView::RemoveItems(int32 index, int32 count)
These functions work like their BListView
counterparts,
except that:
They can remove items from any part of the list, including collapsed sections. The index counts all items assigned to the BOutlineListView; the specified item can be hidden.
If the item being removed is a superitem, they also remove all of its subitems.
Warning
The BListView
versions of these functions will not produce
reliable results when applied to a BOutlineListView, even if the
item being removed is in an expanded section of the list and is not a
superitem.
See also: BListView::RemoveItem()
SortItemsUnder()
void BOutlineListView::SortItemsUnder(BListItem *underItem, bool oneLevelOnly, int (*compareFunc)(const BListItem*, const BListItem*))
Sorts the items located under the specified underItem. If oneLevelOnly is true, only items located directly under the underItem are considered. If oneLevelOnly is false, subitems are scanned recursively and sorted.
The hierarchy of the list is ignored when sorting with oneLevelOnly set to false; items can (and will) be moved from one level to another. If you want to sort without moving items from one level to another, you should call SortItemsUnder() once for each superitem with oneLevelOnly set to true.
Note
When oneLevelOnly is false,
SortItemsUnder() acts just like FullListSortItems()
, except the first item in the list
that’s considered is underItem instead of the first item in the
full list.
Superitem()
BListItem *BOutlineListView::Superitem(const BListItem *item)
Returns the superitem for the item passed as an argument—that is, the item under which the argument item is grouped—or NULL if the item is at the outermost level of the outline (level 0) or isn’t in the list.
Static Functions¶
Instantiate()
static BArchivable *BOutlineListView::Instantiate(BMessage *archive)
Returns a new BOutlineListView object, allocated by new and
created with the version of the constructor that takes a
BMessage
archive. However, this function returns
NULL if the specified archive doesn’t contain data
for a BOutlineListView object.
See also: BArchivable::Instantiate()
,
instantiate_object()
,
Archive()