CLVColumn

 

Derived from: public BArchivable /*Not currently*/

Declared in: CLVColumn.h

Library: none


Overview

 

A CLVColumn is an object that can cooperate with a ColumnListView to display one column as a header for one column of items in a list.


Constructor and Destructor

 


CLVColumn()

 

      CLVColumn(const char* label, float width = 20.0, uint32 flags = 0,
            float min_width = 20.0);
 
      CLVColumn(BMessage *archive)    /*Not implemented*/

 

Initializes the new CLVColumn. The label will appear in the column heading.

The flags can be:

CLV_SORT_KEYABLE

The user can select this column to be the key column for sorting the items in the list

CLV_NOT_MOVABLE

The user can't drag this column to move it

CLV_NOT_RESIZABLE

The user can't drag the resize handle to change the size of this column

CLV_LOCK_AT_BEGINNING

This column is locked at the beginning for display purposes

CLV_LOCK_AT_END

This column is locked at the end for display purposes

CLV_HIDDEN

This column is initially hidden from the user

CLV_MERGE_WITH_RIGHT

This column is merged with the column to the right of it. It will not show a border / resize handle between the two items

CLV_LOCK_WITH_RIGHT

This column is locked to the column to the right of it. If either column is dragged to a new position, the partner will be dragged with it. Any number of columns may be locked together

CLV_EXPANDER

This column should display an expander. You may only use one expander in a ColumnListView, and an expander may not be added to a non-hierarchal ColumnListView. It may not have a label. Its width is automatically set to 20.0. The only flags that affect it are CLV_NOT_MOVABLE, CLV_LOCK_AT_BEGINNING, CLV_NOT_SHOWN and CLV_LOCK_WITH_RIGHT. The others are set for you: CLV_NOT_RESIZABLE | CLV_MERGE_WITH_RIGHT. If the user uses the arrow in an expander to display the items underneath it, the subitems will be indented, and will push the contents of the next column to the right by an appropriate amount

CLV_PUSH_PASS

Allows the column, if pushed by an expander, to "pass on" that push and push the next column over as well. Typically, this is used in an icon column following an expander, so that the name (or whatever) column that follows it will be pushed by the expander as well.

CLV_HEADER_TRUNCATE

Causes the text in the column label to be truncated with an ellipsis if it doesn't fit in the width of the column header.

CLV_TELL_ITEMS_WIDTH

Causes this column to call ColumnWidthChanged for all items when the width of this column changes. This is necessary for columns with string truncation using CLVEasyItem.

CLV_RIGHT_JUSTIFIED

Causes this column to Causes the column, when resized, to shift its content, not just the content of subsequent columns. This does not affect the rendering of content in items in the column, just the area that gets scrolled. Rendering of items in your CLVListItem-derived class's DrawItemColumn method should reflect this behavior. For CLVEasyItems, set right_justified to true in your SetColumnContent calls.

See also: ColumnListView::AddColumn()


~CLVColumn()

 

      virtual ~CLVColumn()

 

If the column has been added to a ColumnListView, removes it then deletes the column.


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


DrawColumnHeader()

 

      virtual void DrawColumnHeader(BView* view, BRect header_rect, bool sort_key, 
            bool focus, float font_ascent)

 

Can be overridden to implement your own column header drawing. It should be rendered in view, in the header_rect provided. If sort_key is true, it should be underlined. If focus is true, it is being dragged or clicked on and should be rendered in BeFocusBlue. font_ascent is the ascent of the font selected for the ColumnListView to use for the header.

- The background will already be filled with and LowColor set to BeBackgroundGrey
- The highlight and shadow edges will already be drawn
- The header_rect does not include the one-pixel border for the highlight and shadow edges
- The view font will already be set to the font specified when the ColumnListView was constructed, and should not be changed
- If text is being rendered, it should be rendered at BPoint text_point(header_rect.left+8.0,header_rect.top+1.0+font_ascent)
- If sort_key is true, the text should be underlined, with the underline being drawn from BPoint(text_point.x-1,text_point.y+2.0) to BPoint(text_point.x-1+label_width,text_point.y+2.0)
- If focus is true, the text and underline should be in BeFocusBlue, otherwise in Black.

See also: CLVColumn()


Flags()

 

      uint32 void Flags() const

 

Returns the flags for this column.

See also: CLVColumn()


GetHeaderView()

 

      BView* GetHeaderView() const
 

 

Returns the header view which contains this column.


GetLabel()

 

      const char* GetLabel() const
 

 

Returns the label for this column.


GetParent()

 

      ColumnListView* GetParent() const
 

 

Returns the ColumnListView which owns this column.


SetShown(), IsShown()

 

      virtual void SetShown(bool shown)
 
      bool IsShown() const

 

Sets or returns whether the column is currently shown. IsShown() returns true if the column is currently shown (though not necessarily visible as it may be outside the ColumnListView's rectangle, in which case it is accessible using the horizontal scroll bar if the ColumnListView has one). Returns false otherwise.


SetWidth(), Width()

 

      virtual void SetWidth(float width)
 
      float Width() const

 

Sets or returns the width of the column. To detect changes in the width of the column, override ColumnListView::ColumnWidthChanged().


SetSortMode(), SortMode()

 

      virtual void SetSortMode(CLVSortMode mode)
 
      CLVSortMode SortMode() const

 

Sets or returns the sort mode of the column. Sort modes may be Ascending, Descending or NoSort. A mode other than ascending or descending does not necessarily make it used for sorting, as it also needs to be selected as a sort key. To detect user changes in the sort mode of the column, override ColumnListView::SetSortMode().

See also: ColumnListView::SetSortKey(), ColumnListView::AddSortKey()

 


Utility Functions

 


GetTruncatedString()

 

      void GetTruncatedString(const char* full_string, char* truncated, float width,
            int32 truncate_buf_size, const BFont* font)

 

Truncates a full_string to fit in the space provided, placing the results in a buffer which must be provided in truncated.


By Brian Tietz

Copyright 1997-2000

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