BListItem

Derived from: none
Mix-in classes: BArchivable
Declared in:  be/interface/ListItem.h
Library: libbe.so
Allocation: Constructor only
Summary:  more...

A BListItem represents a single item in a BListView (or BOutlineListView). The BListItem object provides drawing instructions that can draw the item (through DrawItem()), and keeps track of the item's state. To use a BListItem, you must add it to a BListView through BListView::AddItem() (BOutlineListView provides additional item-adding functions). The BListView object provides the drawing context for the BListItem's DrawItem() function.

BListItem is abstract; each subclass must implement DrawItem(). BStringItem—the only BListItem subclass provided by Be—implements the function to draw the item as a line of text. For an example of a custom BListView subclass, see "BListItem: Creating a Custom List Item".

Synchronizing a List Item with its List View

A BListItem object doesn't automatically get redrawn when the item changes. If you change a list item's content or state, you must tell the item's owner (the BListView object) to redraw the item by calling BListView::InvalidateItem(). For example:

/* listItem belongs to listView. We change the state of the item... */ listItem->SetEnabled(false); /* ...so we have to tell the list view to redraw it. */ listView->LockLooper(); listView->InvalidateItem(listView->IndexOf(listItem)); listView->UnlockLooper();

If you're making a lot of changes, you can flush them all at the same time through a single BListView::Invalidate() call:

listItemA->SetEnabled(false); listItemB->SetEnabled(false); listItemC->SetEnabled(false); listView->LockLooper(); listView->Invalidate(); listView->UnlockLooper();

Note that you don't have to lock the list view's window to change one of its items—you only have to lock the window when you talk to the list view itself.

BListView provides its own smart version

Hook Functions

• DrawItem()

• Update()

Constructor and Destructor

BListItem() , ~BListItem()

BListItem(uint32 level = 0, bool expanded = true) 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.

The destructor is empty.

Member Functions

Deselect()  see Select()

DrawItem()

virtual void 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 "BListItem: Creating a Custom List Item" for an example DrawItem() function.

	Height()  see SetHeight()
	IsEnabled()  see SetEnabled()
	IsExpanded()  see SetExpanded()
	IsSelected()  see Select()

OutlineLevel()

uint32 OutlineLevel(void) const

Returns the outline level of the item; this is only meaningful if the item is in a BOutlineListView. See BOutlineListView for more information about levels.

Select() , Deselect() , IsSelected()

void Select(void) void Deselect(void) bool IsSelected(void) 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(void) 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(void) 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 BOutlineListView::Invalidate().

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 width) float Height(void) const float Width(void) const

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

Update()

virtual void 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).

Width()  see SetHeight()

Archived Fields

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

Field	Type code	Meaning
"_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.