Derived from: public BArchivable
Declared in: be/interface/ListItem.h
Library: libbe.so
A BListItem is an object that can cooperate with a BListView, including a BOutlineListView, to display one item in a list. The BListItem draws the item and keeps track of its current state. The BListView manages the list, responds to messages, provides its items with the graphics environment they need to draw, and calls upon them to draw when needed.
BListItem is an abstract class; derived classes must implement a DrawItem() function to draw the item. The BStringItem class is the only implementation of a BListItem available in the Interface Kit. It draws the item as a line of text.
A BListItem records some properties that are relevant only if it's part of a BOutlineListView--in particular, the level of the item in the outline and whether it's expanded (its subitems are displayable) or collapsed (its subitems are not displayable). Other properties apply to all lists--for example, whether or not the item is selected and whether it's enabled or disabled.
The class provides functions to set and return these properties. However, setting a BListItem property doesn't by itself alter the display or inform the container BView. The view communicates with the BListItem, but the item doesn't reciprocate and communicate with the BListView. Therefore, once a BListItem has been added to a list, it's generally best to manipulate it through BListView (and BOutlineListView) functions, rather than directly through its own functions.
DrawItem() | Must be implemented to draw the item. |
UpdateInfo() | Can be implemented to update cached information. |
BListItem(uint32 level = 0, bool expanded = true) BListItem(BMessage *archive)
Marks the BListItem as being at the specified outline level and as controlling an expanded section of the outline if the expanded flag is true or a collapsed section if expanded is false. Outline levels are indicated by an index, with 0 as the outer level, 1 for one level of indentation, 2 for two levels of indentation, and so on.
Initially, the item has a width and height of 0.0 coordinate units, is enabled, and is not selected.
virtual ~BListItem(void)
Does nothing.
virtual status_t Archive(BMessage *archive, bool deep = true) const
Calls the inherited version of Archive(), then adds four pieces of information to the archive BMessage:
See also: BArchivable::Archive(), Instantiate() static function
virtual void DrawItem(BView *owner, BRect itemRect, bool complete = false) = 0
Implemented by derived classes to draw the item in the itemRect portion of the owner BView. If the complete flag is true, this function should touch every pixel in the itemRect rectangle. If the flag is false, it can assume that background pixels are already the correct color.
To draw the item, this function should call the graphic functions of the owner BView. For example:
void MyItem:DrawItem(BView * owner, BRect itemRect, bool complete) { if ( complete ) { rgb_color color; if ( IsSelected() ) { color = my_highlight_color; else color = owner->ViewColor(); owner->SetHighColor(color); owner->FillRect(itemRect); } . . . }
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. However, it should not consider the outline level. If the level is important, the owner BView will have already taken it into account in calculating the itemRect rectangle.
See also: BListView::Draw()
uint32 OutlineLevel(void) const
Returns the outline level of the item. The greater the return value, the deeper the level. The outermost level is 0.
See also: the BOutlineListView class
void Select(void) void Deselect(void) bool IsSelected(void) const
Select() and Deselect() mark the item as being selected or unselected. However, these functions don't inform the BListView of the change. To select and deselect items that have been added to a view, call the container BListView's Select() and Deselect() functions instead. Those functions update the display on-screen and mark the BListItem accordingly.
IsSelected() returns true if the item is selected and false if not.
See also: BListView::Select(), BListView::Deselect()
void SetEnabled(bool enabled) bool IsEnabled(void) const
SetEnabled() marks the BListItem as being enabled if the enabled flag is true, or disabled if the flag is false. IsEnabled() returns the current enabled state of the item.
SetEnabled() doesn't alter how the item is displayed; you must take steps to invalidate the region of the BView where the item is displayed so that DrawItem() will be called.
See also: BListView::InvalidateItem()
void SetExpanded(bool expanded) bool IsExpanded(void) const
SetExpanded() marks the item as controlling an expanded section of the list if the expanded flag is true, or as controlling a collapsed section if expanded is false. IsExpanded() returns the current state of the BListItem.
SetExpanded() doesn't affect the on-screen display. If the item is in a BOutlineListView in a window, it's better to call that view's Collapse() and Expand() functions so that the changes can take effect immediately.
See also: BOutlineListView::Collapse()
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.
See also: Update()
virtual void Update(BView *owner, const BFont *font)
Modifies the width of the BListItem to match the width of the owner BView where it will draw and modifies the item's height to fit the height of the BView's current font. This function is called whenever an item is assigned to a BListView (including a BOutlineListVIew) and when the owning object undergoes a change that might affect the item.
Derived classes can augment this function to record the owner BView, cache the font, query the owner about other aspects of the graphics environment, or take any other action that's required to keep the item up to date.
The Be Book, in lovely HTML, for the BeOS Preview Release.
Copyright © 1997 Be, Inc. All rights reserved.
Be is a registered trademark; BeOS, BeBox, BeWare, GeekPort, the Be logo, and the BeOS logo are trademarks of Be, Inc.
Last modified September 18, 1997.