# CLVListItem

Derived from: public BListItem

Declared in: CLVListItem.h

Library: none

## Overview

A CLVListItem is an object that can cooperate with a ColumnListView to display one item in a list. The CLVListItem draws the item and keeps track of its current state. The ColumnListView 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.

CLVListItem is an abstract class; derived classes must implement a `DrawItemColumn()` function to draw the columns of the item.

The class provides functions to set and return these properties. However, setting a CLVListItem property doesn't by itself alter the display or inform the ColumnListView. The view communicates with the CLVListItem, but the item doesn't reciprocate and communicate with the ColumnListView. Therefore, once a CLVListItem has been added to a list, it's generally best to manipulate it through ColumnListView functions, rather than directly through its own functions.

CLVListItem functions in a manner virtually identical to BListItem, with only a few exceptions. First, in a BOutlineListView, an item is a superitem only if it has subitems. A CLVListItem can be manually specified at construction to be a superitem. In this manner, a CLVListItem can be a superitem with no subitems.

## Hook Functions

`ColumnWidthChanged()` | Called when the user resizes a column.
`DrawItemColumn()` | Must be implemented to draw the item.
`FrameChanged()` | Called when a column is reordered to a new position.
`Update()` | Can be implemented to update cached information.

## Inherited Functions

The CLVListItem class inherits most of its functionality from the BListItem class. See BListItem for documentation for the following functions:

OutlineLevel()

Select(), Deselect(), IsSelected()

SetEnabled(), IsEnabled()

SetExpanded(), IsExpanded()

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

## Constructor and Destructor

### CLVListItem()

          CLVListItem(uint32 level = 0, bool superitem = false, bool expanded = true, float minheight = 0.0)
          CLVListItem(BMessage *archive)    /*Not implemented*/

Marks the CLVListItem as being at the specified outline level , as being an expandable superitem if the superitem flag is `true`, and as controlling an expanded section of the outline if the expanded flag is `true` or a collapsed section if expanded is `false`. Minheight specifies the minimum height that the item may be. This is useful if the item's height is to vary to respond to user preferences, but elements of the item (an icon, for example), place a constraint on how small the item may be. 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.

Construction from an archive is currently not implemented. It isn't high on my priorities, since archival is not something I'm making use of. If someone needs this functionality and fills it in, please send me the modified code so that others can benefit from it.

### ~CLVListItem()

          virtual ~CLVListItem()

Does nothing.

## Member Functions

### Archive()

          virtual status_t Archive(BMessage *archive, bool deep = true) const

Currently not implemented. It isn't high on my priorities, since archival is not something I'm making use of. If someone needs this functionality and fills it in, please send me the modified code so that others can benefit from it.

See also: `BArchivable::Archive()`, `Instantiate()` static function

### ColumnWidthChanged()

          virtual void ColumnWidthChanged(int32 column_index, float column_width, ColumnListView* the_view)

Called when the user resizes the column. This should be overridden if changes in width affect the displayed content of the item, for example when doing string truncation when the string is too long to fit.

### DrawItemColumn()

          virtual void DrawItemColumn(BView *owner, BRect itemColumnRect, int32 columnIndex, bool complete) = 0

Implemented by derived classes to draw one column in the item in the itemColumnRect 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.

The columnIndex is based on the order in which the CLVColumn's were added to the ColumnListView, not the order in which they are currently displayed. Thus, if a ColumnListView has three columns: an icon column, a name column, and a size column, the icon column will always have columnIndex == 0, the name column will always have columnIndex == 1, and the size column will always have columnIndex == 2, even if the user drags the columns into a different display order. The column index may also be negative, in which case you are to draw the background outside of the context of any column. The itemColumnRect will be adjusted when DrawItemColumn is called to take the column's position into account. A negative index indicates that the area after the last column is to be drawn. This is important so that if an item is highlighted upon selection, the highlight bar will be drawn all the way across the ColumnListView, even if the last column ends before the right side of the ColumnListView is reached. In a hierarchical ColumnListView, `DrawItemColumn()` will also be called for the expander column for the same reason: to allow highlighting to be drawn. It is not necessary to draw the expander handle, as that is taken care of by CLVListItem.

To draw the item, this function should call the graphic functions of the owner BView. For example:

       void MyItem:DrawItemColumn(BView * owner, BRect itemColumnRect, int32 columnIndex, bool complete)
       {
           if ( complete ) {
               rgb_color color;
               if ( IsSelected() ) {
                   color = my_highlight_color;
               else
                   color = owner->ViewColor();
               owner->SetHighColor(color);
               owner->FillRect(itemRect);
           }
           . . .
       }

``

`DrawItemColumn()` 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. As with the display order, if the level is important, the owner BView will have already taken it into account in calculating the itemColumnRect rectangle.

See also: `ColumnListView::Draw()`

### ExpanderShift()

          float ExpanderShift(uint32 column_index, ColumnListView* owner)

The shift to the right of the contents of the column due to the outline level.

### FrameChanged()

          virtual void FrameChanged(int32 column_index, BRect new_frame, ColumnListView* the_view)

Called when the user moves a column to a new position. This is important because in a hierarchical list view, such a change can affect the width available for display of text if the column is dragged into or out of a position where it is pushed by an expander.

### ItemColumnFrame()

          BRect ItemColumnFrame(int32 column_index, ColumnListView* owner)

The frame for the item content in the column specified in column_index for this item, in the ColumnListView specified in owner.

### SetOutlineLevel(), OutlineLevel()

          void SetOutlineLevel(uint32 outlinelevel)

          int32 OutlineLevel() const

Returns or alters the outline level of the item. It does not change the level of any sub-items, and does not update the ColumnListView. Whenever `SetOutlineLevel()` is called, any subitems should have their levels altered as well if the item was a superitem, and `ColumnListView::InvalidateItem()` should be called for the item to update the display.

### SetSuperItem(), IsSuperItem()

          void SetSuperItem(bool superitem)

          bool IsSuperItem() const

Alters or returns whether the item is a superitem or not. `SetSuperItem()` does not remove any sub-items when superitem is changed to false, and does not update the ColumnListView. Whenever `SetSuperItem()` is called, any subitems should be removed if it was a superitem, and `ColumnListView::InvalidateItem()` should be called for the item to update the display. `IsSuperItem()` returns `true` if the item is a superitem, even if it is a superitem with nothing inside of it. If the item is not a superitem, it returns `false`.

###

Update()

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

Modifies the width of the CLVListItem 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.. If the resulting height is less than the minimum height specified in the CLVListItem constructor, the height is set to that minimum height. 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. To manually control the height of the item, override Update and have it call CLVListItem::Update so that the width will be set properly, then call SetHeight() to alter the height to the desired value.

## Nonmember Utility Functions

### ToUpperStr()

          char* ToUpperStr(char* source)

Returns a copy of the source string in which any lowercase letters have been converted to uppercase. The copy must be delete[]'d.

By Brian Tietz

Copyright 1997

Bug reports (including documentation errors) and feature requests can be sent to briant@digaudio.com.