Derived From:
Mix-in Classes:BArchivable
Declared In:interface/ListItem.h
Allocation:Constructor only
Class Overview

Constructor and Destructor


BListItem(uint32 level = 0,
          bool expanded = true);

The constructors create a new BListItem object. The level and expanded arguments are only used if the item is added to a BOutlineListView object; see BOutlineListView::AddItem() for more information.



The destructor is empty.

Hook Functions


virtual void DrawItem(BViewowner,
                      BRect itemRect,
                      bool drawEverything = false) = 0;

Hook function that's invoked when the item's owner (a BListView object) needs to draw this item. itemRect is the area within the owner to which the item's drawing is clipped. If drawEverything is true, this function should touch every pixel in itemRect; if it's false, the function can assume that the background color for the item is already painted. DrawItem() should be implemented to visually reflect the state of the item, highlighting it if it's selected, dimming it if it's disabled, and so on.

The owner view provides the drawing environment for this item. All drawing instructions should be invoked on owner. See "Creating a Custom List Item" for an example DrawItem() function.


virtual void Update(BViewowner,
                    const BFontfont);

Hook function that's called whenever the item's owner changes in a way that could affect the appearance of this item. It's always called when the item is added to a list view.

The default implementation sets the item's width to that of the owner, and sets its height so it will accommodate font (the owner's current BFont setting).

Member Functions


uint32 OutlineLevel() const;

Returns the outline level of the item; this is only meaningful if the item is in a BOutlineListView.

Select(), Deselect(), IsSelected()

void Select();void Deselect();bool IsSelected() const;

Select() and Deselect() set the item's selected state; IsSelected() returns the state. The setting functions don't automatically update the item's display: After calling Select() or Deselect(), you must tell the owner to redrawn this item (see BListView::InvalidateItem()).

Also, Select() doesn't deselect the current selection. If this item is part of a single-selection list view, you have to deselect the current selection yourself.


If possible, you should use BListView's versions of these functions (see BListView::Select(). They update the view and manage the selection for you.

SetEnabled(), IsEnabled()

void SetEnabled(bool enabled);bool IsEnabled() const;

SetEnabled() sets the list item's enabled state; IsEnabled() returns the state. A disabled item can't be selected by the user or by BListView::Select() , but it can be selected through BListItem::Select(). If an item is already selected, SetEnabled(false) doesn't deselect it.

After calling SetEnabled(), you must tell the owner list view to redraw the item (see BListView::InvalidateItem()).

Note that BListView doesn't provide smart versions of these functions (as it does for Select()).

SetExpanded(), IsExpanded()

void SetExpanded(bool expanded);bool IsExpanded() const;

These functions set and return the item's expanded state. This is only meaningful if the item is part of a BOutlineListView. The item is not automatically redrawn; you must tell the BOutlineListView to redraw the item (and its sublist) through BListView::InvalidateItem().


If possible, you should use BOutlineListView's Expand() and Collapse() functions instead of SetExpanded(). The BOutlineListView functions redraw the affected part of the list for you.

SetHeight(), SetWidth(), Height(), Width()

void SetHeight(float height);void SetWidth(float height);float Height() const;float Width() const;

These functions set and return the width and height of the item. The item's dimensions are adjusted when Update() is called.

Archived Fields

The Archive() function adds the following fields to its BMessage argument:

FieldType codeDescription
_selB_BOOL_TYPEtrue if the item is selectable.
_disableB_BOOL_TYPEtrue if the item is disabled.
_li_expandedB_BOOL_TYPEtrue if the item is expanded.
_li_outline_levelB_INT32_TYPEThe outline level of the item.

Some of these fields may not be present if the setting they represent isn't used, or is the default value. For example, if the item is not selectable, the _sel field won't be found in the archive.

Creative Commons License
Legal Notice
This work is licensed under a Creative Commons Attribution-Non commercial-No Derivative Works 3.0 License.