BListItem

Constructor and Destructor

BListItem()

BListItem::BListItem(uint32 level = 0, bool expanded = true)
BListItem::BListItem(BMessage *archive)

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.

~BListItem()

BListItem::~BListItem()

The destructor is empty.

Hook Functions

DrawItem()

virtual void BListItem::DrawItem(BView *owner, 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.

Update()

virtual void BListItem::Update(BView *owner, const BFont *font)

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

OutlineLevel()

uint32 BListItem::OutlineLevel() const

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

Select(), Deselect(), IsSelected()

void BListItem::Select()

void BListItem::Deselect()

bool BListItem::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.

Note

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 BListItem::SetEnabled(bool enabled)

bool BListItem::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 BListItem::SetExpanded(bool expanded)

bool BListItem::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().

Note

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 BListItem::SetHeight(float height)

void BListItem::SetWidth(float height)

float BListItem::Height() const

float BListItem::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:

Field	Type code	Description
_sel	B_BOOL_TYPE	true if the item is selectable.
_disable	B_BOOL_TYPE	true if the item is disabled.
_li_expanded	B_BOOL_TYPE	true if the item is expanded.
_li_outline_level	B_INT32_TYPE	The 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.