Columns

Sets up the columns of a ListView in the report view, and the header above them, which the user clicks, resizes, moves and filters by.

Private Sub Form_Load()
    With ListView1
        .View = LvwViewReport
        .ColumnHeaders.Add , "name", "Name", 2400
        .ColumnHeaders.Add , "size", "Size", 1000, LvwColumnHeaderAlignmentRight
        .ColumnHeaders.Add , "type", "Type"
        .AllowColumnReorder = True
        .FullRowSelect = True
        .GridLines = True
    End With
End Sub

Private Sub ListView1_ColumnClick(ByVal ColumnHeader As LvwColumnHeader)
    Debug.Print "Sort by "; ColumnHeader.Text
End Sub

Columns and the header

ColumnHeaders returns the columns as an LvwColumnHeaders collection, and its Add method adds one, with its text, its width and the alignment of its texts. Each column is an LvwColumnHeader. The first column shows the items’ own texts and the others their subitems, one column for each subitem number. The columns are shown in the report view; in the tile view an item shows some of its subitems, named by the column numbers in its TileViewIndices.

The header is a window of its own, hWndHeader, above the items. HideColumnHeaders hides it, and GetHeaderHeight returns its height. Its own pointer is HeaderMousePointer.

What the user does with the header

The user Allowed by Events
clicks a column’s header ClickableColumnHeaders ColumnClick, ColumnDblClick
drags the divider between two headers to resize a column ResizableColumnHeaders and the column’s Resizable ColumnBeforeResize, ColumnAfterResize
double-clicks a divider, which sizes the column to its contents the same ColumnDividerDblClick
drags a header to another place AllowColumnReorder ColumnBeforeDrag, ColumnAfterDrag
clicks the arrow of a split button the column’s SplitButton ColumnDropDown
checks a column’s check box AllowColumnCheckboxes and the column’s CheckBox ColumnCheck
clicks the chevron at the right of a header too wide for the control UseColumnChevron ColumnChevronPushed
types a filter under a header UseColumnFilterBar BeforeFilterEdit, ColumnFilterChanged, AfterFilterEdit, ColumnFilterButtonClick

The split buttons, the check boxes and the chevron are there when the program has visual styles.

The order of the columns

A column has a number, its Index, and a place among the others, its Position, from 1. They are the same until the user drags a header to another place, or the program sets a Position. ColumnOrder holds the order as an array that counts from 0: its first element is the number, less 1, of the column at the first place.

Dim Order As Variant
With ListView1
    .View = LvwViewReport
    .ColumnHeaders.Add , "n", "Name"
    .ColumnHeaders.Add , "s", "Size"
    .ColumnHeaders.Add , "t", "Type"
    .ColumnHeaders("t").Position = 1
    Order = .ColumnOrder
    Debug.Print Order(0); Order(1); Order(2)
    Debug.Print .ColumnHeaders.ItemFromPosition(1).Text
    .ColumnOrder = Empty                    ' back to the order of the numbers
    Debug.Print .ColumnHeaders("t").Position
End With
' Output:
'  2  0  1
' Type
'  3

Check boxes in the header

With AllowColumnCheckboxes True, a column whose CheckBox is True shows a check box in its header, such as one that checks every item. The user’s click and an assignment to the column’s Checked both change it and raise ColumnCheck. A column without a check box stays unchecked.

Dim Watch As New ColumnWatcher
Set Watch.LV = ListView1
With ListView1
    .View = LvwViewReport
    .AllowColumnCheckboxes = True
    .ColumnHeaders.Add , , "All"
    .ColumnHeaders(1).Checked = True        ' no check box yet: nothing happens
    .ColumnHeaders(1).CheckBox = True
    .ColumnHeaders(1).Checked = True
End With
' Output:
' ColumnCheck All True

ColumnWatcher in this sample is a class of the program’s own that holds the control WithEvents and prints the event.

Properties

AllowColumnCheckboxes

Whether the header shows the check boxes of the columns whose CheckBox is True. Boolean. Default: False. It has an effect when the program has visual styles.

AllowColumnReorder

Whether the user can drag a column’s header to another place. Boolean. Default: False.

ClickableColumnHeaders

Whether the headers act as buttons that the user clicks. Boolean. Default: True.

ColumnFilterChangedTimeout

How long after the user changes a filter ColumnFilterChanged is raised, in milliseconds. Long. A new header has 1000. -1 raises the event only when the user ends the filter’s editing. It reads 0 while the control has no header, before it has been in the report view.

0, and a value less than -1, raise run-time error 380.

ColumnHeaderIcons

The image list of the icons of the column headers. Variant: an ImageList control, its name or the handle of an image list, as for Icons. Default: none. A column names its icon by its Icon.

ColumnHeaders

The columns of the control, as an LvwColumnHeaders collection. Read-only.

ColumnOrder

The order of the columns from left to right. Variant: an array of Long, from 0, with one element for each column: the column’s number less 1. See The order of the columns.

An assignment takes such an array of numbers less 1, or of the columns’ keys as strings. Empty, or an array with no elements, puts the columns in the order of their numbers.

A number that is no column’s raises run-time error 381. A value that is no array and not Empty raises run-time error 380, and an array of more than one dimension raises run-time error 5.

GridLines

Whether lines are drawn between the rows and the columns of the report view. Boolean. Default: False.

HeaderMouseIcon

The pointer shown over the header when HeaderMousePointer is CCMousePointerCustom. A picture that holds an icon or a cursor; a picture of another kind raises run-time error 380.

HeaderMousePointer

The pointer shown while the mouse is over the header. A member of CCMousePointerConstants. Default: CCMousePointerDefault. Another value raises run-time error 380. Over the divider of a column that the user cannot resize, the header shows this pointer, or the arrow, in place of the pointer for resizing.

HideColumnHeaders

Whether the header is hidden in the report view. Boolean. Default: False.

HighlightColumnHeaders

Whether a header is highlighted while the pointer is over it. Boolean. Default: False. With visual styles Windows highlights the headers in its own way.

hWndHeader

The handle of the header’s window. LongPtr, read-only. 0 until the control has been in the report view.

hWndHeaderToolTip

The handle of the window that shows the tool tips of the headers. LongPtr, read-only. 0 while ShowColumnTips is False.

ResizableColumnHeaders

Whether the user can resize the columns, by dragging or double-clicking a divider, or with Ctrl and the plus key of the keypad. Boolean. Default: True. A single column can be fixed by its Resizable.

SelectedColumn

The column whose texts are drawn on a shaded background, as the column a list is sorted by often is. An LvwColumnHeader, or Nothing. Setting it to Nothing shades no column. While the background Picture is tiled, an assignment of a column does nothing.

ShowColumnTips

Whether a header shows its column’s ToolTipText while the pointer rests on it, and the ToolTipTextFilterBtn and ToolTipTextDropDown over its filter button and split button. Boolean. Default: False.

TrackSizeColumnHeaders

Whether the column is drawn at its new width while the user drags its divider. Boolean. Default: True. With False a line shows where the divider is until the user lets go.

UseColumnChevron

Whether the header shows a chevron button when the columns are wider than the control, which raises ColumnChevronPushed. Boolean. Default: False. It has an effect when the program has visual styles.

UseColumnFilterBar

Whether the header has a row of filter boxes under the column titles, in which the user types a value to filter by. Boolean. Default: False. The control does not filter the items itself: the program reads the columns’ FilterValue in ColumnFilterChanged and shows the items that match.

Methods

GetHeaderHeight

Returns the height of the header, in the scale units of the control’s container. Single. 0 while the control has no header.

Syntax: object.GetHeaderHeight( ) As Single

Events

AfterFilterEdit

Raised when the user stops editing a column’s filter.

Syntax: object_AfterFilterEdit( ByVal ColumnHeader As LvwColumnHeader )

BeforeFilterEdit

Raised when the user starts to edit a column’s filter.

Syntax: object_BeforeFilterEdit( ByVal ColumnHeader As LvwColumnHeader, ByVal hWndFilterEdit As LongPtr )

hWndFilterEdit
The handle of the edit box in which the user types.

ColumnAfterDrag

Raised when the user drops a header that was dragged to another place.

Syntax: object_ColumnAfterDrag( ByVal ColumnHeader As LvwColumnHeader, ByVal NewPosition As Long, Cancel As Boolean )

NewPosition
The Position the column will have, from 1.
Cancel
False when the event is raised. A handler that sets it to True keeps the column at its place.

ColumnAfterResize

Raised when the user has dragged a divider to resize a column.

Syntax: object_ColumnAfterResize( ByVal ColumnHeader As LvwColumnHeader, NewWidth As Single )

NewWidth
The width the user gave the column, in the scale units of the control’s container. A handler that changes it gives the column that width instead; 0 or less makes the column 0 wide.

ColumnBeforeDrag

Raised when the user starts to drag a header to another place, while AllowColumnReorder is True.

Syntax: object_ColumnBeforeDrag( ByVal ColumnHeader As LvwColumnHeader )

ColumnBeforeResize

Raised when the user starts to drag a divider to resize a column that can be resized.

Syntax: object_ColumnBeforeResize( ByVal ColumnHeader As LvwColumnHeader, Cancel As Boolean )

Cancel
False when the event is raised. A handler that sets it to True keeps the width.

ColumnCheck

Raised when the check box of a column’s header changes, by the user or by an assignment to its Checked.

Syntax: object_ColumnCheck( ByVal ColumnHeader As LvwColumnHeader )

ColumnChevronPushed

Raised when the user clicks the chevron button of the header, while UseColumnChevron is True. The program shows a menu of the columns that do not fit.

Syntax: object_ColumnChevronPushed( ByVal ColumnHeader As LvwColumnHeader )

ColumnHeader
The column that Windows names with the click.

ColumnClick

Raised when the user clicks a column’s header. A program sorts by that column here; see Sorting and Searching.

Syntax: object_ColumnClick( ByVal ColumnHeader As LvwColumnHeader )

ColumnDblClick

Raised when the user double-clicks a column’s header.

Syntax: object_ColumnDblClick( ByVal ColumnHeader As LvwColumnHeader )

ColumnDividerDblClick

Raised when the user double-clicks the divider at the right of a column that can be resized, which makes the column as wide as its widest text.

Syntax: object_ColumnDividerDblClick( ByVal ColumnHeader As LvwColumnHeader, Cancel As Boolean )

Cancel
False when the event is raised. A handler that sets it to True keeps the width.

ColumnDropDown

Raised when the user clicks the arrow of a column’s split button. The program shows a menu under it.

Syntax: object_ColumnDropDown( ByVal ColumnHeader As LvwColumnHeader )

ColumnFilterButtonClick

Raised when the user clicks the filter button at the right of a column’s filter box.

Syntax: object_ColumnFilterButtonClick( ByVal ColumnHeader As LvwColumnHeader, RaiseFilterChanged As Boolean, ByVal ButtonLeft As Long, ByVal ButtonTop As Long, ByVal ButtonRight As Long, ByVal ButtonBottom As Long )

RaiseFilterChanged
False when the event is raised. A handler that changed the filter, from a menu of its own, sets it to True to have ColumnFilterChanged raised.
ButtonLeft, ButtonTop, ButtonRight, ButtonBottom
The edges of the button, in pixels of the header’s window, for placing a menu under it.

ColumnFilterChanged

Raised when the filter of a column has changed, ColumnFilterChangedTimeout after the user’s last key.

Syntax: object_ColumnFilterChanged( ByVal ColumnHeader As LvwColumnHeader )

LvwColumnHeaderAlignmentConstants

The values of a column’s Alignment.

Member Value Description
LvwColumnHeaderAlignmentLeft 0 The texts are at the left.
LvwColumnHeaderAlignmentRight 1 The texts are at the right, as numbers often are.
LvwColumnHeaderAlignmentCenter 2 The texts are centered.

LvwColumnHeaderSortArrowConstants

The values of a column’s SortArrow.

Member Value Description
LvwColumnHeaderSortArrowNone 0 No arrow.
LvwColumnHeaderSortArrowDown 1 An arrow that points down, for a descending order.
LvwColumnHeaderSortArrowUp 2 An arrow that points up, for an ascending order.

LvwColumnHeaderAutoSizeConstants

The values of the argument of a column’s AutoSize.

Member Value Description
LvwColumnHeaderAutoSizeToItems 0 As wide as the widest text of the column’s items.
LvwColumnHeaderAutoSizeToHeader 1 As wide as the widest text of the items and of the header together; the last column fills the rest of the control.

LvwColumnHeaderFilterTypeConstants

The values of a column’s FilterType.

Member Value Description
LvwColumnHeaderFilterTypeText 0 The filter is a text.
LvwColumnHeaderFilterTypeNumber 1 The filter is a whole number.

See Also