# CLVEasyItem

Derived from: public CLVListItem

Declared in: CLVEasyItem.h

Library: none

## Overview

A CLVEasyItem is a list item that automates display of text and graphics, automates string truncation of items that don't fit in the column, and automates sorting of the items based on the text. In most cases, it is best to use a CLVEasyItem instead of a CLVListItem, since it can save you a lot of work and gives nice results.

## Data Members

`float text_offset`
This member is protected so that derived classes can adjust the vertical offset from the top of the item to the font baseline used to render text. It is strongly advised that this be set in the child class's `Update()` method. The default implementation is:

`text_offset = ceil(FontAttributes.ascent) + (Height()-FontHeight)/2.0;`

where the CLVListItem version of `Update()` has already been called, setting the height returned by `Height()`, and FontAttributes was initialized with a call to `BFont::GetHeight()` using the current font for the owner ColumnListView. Derived classes can modify this implementation as necessary.

## Constructor and Destructor

### CLVEasyItem()

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

Marks the CLVEasyItem 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.

### ~CLVEasyItem()

          virtual ~CLVEasyItem()

Frees all memory used for storing the item's column contents.

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

### GetColumnContentBitmap(), GetColumnContentText()

          const Bitmap* GetColumnContentBitmap(int column_index)
          const char* GetColumnContentText(int column_index)

Gets the contents of the specified column. If the column either has the wrong content type for the function version or no content, the function returns `NULL`. If the specified column contains user text, it returns the string returned by `GetUserText(-1)`.

See also: `SetColumnContent()`, `GetUserText()`

### GetUserText()

          virtual const char* GetUserText(int32 column_index, float column_width)

Gets the user text for the specified column, which must have been set up to use user text content with a call to SetColumnUserTextContent(). If the column_width is negative, the complete user text string should be returned. Otherwise, the returned text should be string truncated to the specified width.

Note that during resizing, this function will be called very frequently, which will create performance problems if you're doing the string truncation on the fly. Therefore, if a column contains a small set of strings which occur repeatedly for multiple items in the column, it is advisable to have your ColumnListView or some string management object maintain the list of strings, and manage their truncation, caching the truncated versions. Also note that during column resizing, CLVEasyItem will ask for both the old and new string to determine whether invalidation is necessary. Therefore, in your ColumnListView or string management object, your truncation cache should be two deep for each string.

Finally, if a user text column is used in a hierarchical list view in a manner such that the same string can be truncated to different widths depending on the hierarchy depth, it is advisable to maintain a cache that is arbitrarily deep, but with a width modulus cache being two deep with respect to width%20, since hierarchical list views indent in increments of 20 pixels. For example, if you are asked for truncated strings at width 10, 11, 30, 31, 50, and 51, all of them should be cached, with the modulus cache containing 10 and 11. If you are then asked for truncated strings at width 11, 12, 31, 32, 51 and 52, the modulus cache will contain 11 and 12, with 10 being purged, and truncated strings at width 10, 30 and 50 therefore being no longer needed and purged from the cache.

See also: `SetColumnUserTextContent()`, `GetColumnContentText()`

### SetColumnContent()

          virtual void SetColumnContent(int column_index, const BBitmap *bitmap, float horizontal_offset = 2.0,
                bool copy = true, bool right_justify = false)
          virtual void SetColumnContent(int column_index, const char *text, bool truncate = true, bool right_justify = false)
          virtual void SetColumnUserTextContent(int column_index, bool truncate = true, bool right_justify = false)

For the bitmap version, sets the column column_index to display the specified bitmap. It will be rendered horizontal_offset pixels to the right of the left edge of the column. If `copy` is `true`, it will make a copy of the bitmap. Otherwise, it will just store a pointer to bitmap, and the application must not delete bitmap as long as the item is using it. The non-copying version facilitates the ColumnListView maintaining a bitmap database for conservation of memory, with multiple CLVEasyItems keeping references to a single bitmap entry.

For the text version of SetColumnContent, sets the column column_index to display the specified text. If truncate is `true`, if the text does not fit in the column, it will be truncated with an ellipsis instead of being chopped off at the edge of the column. If truncate is `true`, the CLVColumn for column_index should have its `CLV_HEADER_TRUNCATE` flag set, and must have its `CLV_TELL_ITEMS_WIDTH` flag set. In hierarchical ColumnListViews with string truncation columns, it is not advisable to have the `CLV_PUSH_PASS` flag set for a string truncation column. Doing so makes for bad UI since the text doesn't fall under its column header, and will cause some flicker during column resizing in the area where the content "encroaches" into the subsequent column. It can also lead to truncation failure for columns to the left of a column being resized (a display glitch, not a crash; it's a known bug which is being left for efficiency reasons because it only arises when these UI guidelines are ignored). The advisable column configuration is an expander column followed by an icon column with the `CLV_PUSH_PASS` flag set, followed by any number of string truncation or bitmap columns with the `CLV_PUSH_PASS` flag cleared.

For SetColumnUserTextContent, sets the column column_index to display user text as returned by the method `GetUserText()`, which should be implemented by derived classes making use of this facility. This, similar to SetColumnContent for bitmaps with `copy` set to `false`, is a memory conservation measure, allowing the ColumnListView or some other data management object to generate the text string on the fly. The `truncate` flag is used to tell the CLVEasyItem whether to call `GetUserText()` during column resizing to check for changes to the text content. If the text content changes, the screen will be `Invalidate()`'d as needed to facilitate the minimal required refresh. This means that `GetUserText()` should use the width passed to it to generate a string truncated version of the string. This also means that `GetUserText()` will be called during every redraw that touches that particular column, which could potentially be slow. For long lists of repetetive items, use SetColumnUserTextContent to conserve memory. Otherwise, use SetColumnContent for speed.

If `right_justify` is set to `true`, make sure to set the `CLV_HEADER_TRUNCATE` flag in the corresponding CLVColumn, as this is where the scrolling behavior is defined during column resizing.

See also: `GetColumnContentBitmap()`, `GetColumnContentText()`, `GetUserText()`

By Brian Tietz

Copyright 1999-2000

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