The Interface Kit: BListItem

The Interface Kit Table of Contents | The Interface Kit Index

# BListItem

Derived from: none

Declared in: be/interface/ListItem.h

Library: libbe.so

Allocation: Constructor only

###### Summary

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()

### 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.

### 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()`.

### 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.

The Interface Kit Table of Contents | The Interface Kit Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..