NewListView

Adds a listview control to a form.

The ListView control displays data as ListItem objects. Each ListItem object can have an optional icon associated with the label of the object.


Four Different Views Available

The ListView control can display data in four different view modes:

●

Icon

Can be manipulated with the mouse, allowing the user to rearrange objects

●

SmallIcon

Allows more objects to be viewed. Like Icon view, objects can be rearranged

●

List

A sorted view of ListItem objects

●

Report

A sorted view, with SubItems allowing for extra information to be displayed

Two ImageList Controls for Icons and SmallIcons

A ListItem object consists of a label (the Text property) and an optional image which is supplied by an ImageList control. However, the ListView control, unlike other controls, can use two ImageList controls, which you set using the Icons and SmallIcons properties. Whether or not you use one or both ImageList controls depends on the intended display mode, as determined by the View property.

In the List, SmallIcon, and Report views, you can use a small icon to represent the ListItem object. One ImageList control (specified by the SmallIcons property) supplies the images for use in any of these three views. Set the SmallIcons property to the ImageList control that will supply these images.

In contrast, when the control is in Icon view, the control uses a different set of images supplied by a second ImageList control. Set the Icons property to this second ImageList.

Set Column Text with the ListSubItems Collection

Notice that in any of the views except Report view, the ListItem object displays only one label - the Text property. But in Report view, every ListItem object can have several other text items. Each of these text items are members of the ListSubItems collection. To create a ListSubItem object, use the Add method of the ListSubItems collection.

ListSubItems Depend on ColumnHeaders Presence

Both the presence and number of ListSubItem objects depends on the presence and number of ColumnHeader objects. That is, you cannot create any ListSubItem objects if there are no ColumnHeader objects present. Further, the number of ColumnHeader objects determines the number of ListSubItem objects you can set for the ListItem object. And the number of ListSubItems is always one less than the number of ColumnHeader objects. This is because the first ColumnHeader object is always associated with the Text property of the ListItem object, not with a ListSubItem object.

[Set oCtl =] oFrm.NewListView

( Name, Left, Top, Width, Height, [Container] )

Part

Description

Set oCtl =

(optional) Store a reference to the new control in the variable oCtl. This variable can be used to access the control's properties and methods.

oFrm

A reference to a form object (see the NewForm method)

Name

The name of the control. It must be unique within the form and may not be empty or start with an asterisk (*)

Left

See the list of properties below

Top

See the list of properties below

Width

See the list of properties below

Height

See the list of properties below

Container

(optional) The name of an existing frame control that will act as container for the listbox. If unspecified or an empty string, the Form itself will be the container. Please note that the Left and Top properties are relative to the container's left and top edges

Property

Description

AllowColumn
Reorder

(boolean) Determines if the user can reorder columns using the mouse. The default is True

Arrange

Determines how the icons are arranged in Icon or SmallIcon view

0

(none) No arrangement

1

(left) Items are aligned along the left side of the control

2

(top) Items are aligned along the top of the control (default)

BackColor

Background color (use the RGB function to assign a color value).

CheckBoxes

(boolean) Determines if checkboxes appear. The default is False

ColumnHeader
Icons

Returns or sets the Imagelist control that supplies images for the ColumnHeaders collection. To set an icon for a ColumnHeader object, set its Icon property to an index, key, or object reference to a ListImage object in the ImageList control specified by the ColumnHeaderIcons property

ColumnHeaders

A reference to a collection of ColumnHeaders (containing heading texts).

You can manipulate ColumnHeaders using standard collection methods (for example, the Remove method). Each ColumnHeader can be accessed either by its index or by a unique key, stored in the Key property

Enabled

(boolean) Determines if the control can respond to user-generated events

Font

The Font object contains information needed to format text (for display in the interface of an application or for printed output). It's properties are:

Bold

(boolean) Turns bold formatting on or off

Charset

Returns or sets the character set used in the font. Setting the Charset property to one of its available values selects the character set only if it is available in the current font.

Some common character set values are:

0

Standard Windows characters

2

The symbol character set

255

Extended characters normally displayed by DOS applications

Italic

(boolean) Turns italic formatting on or off

Name

Returns or sets the name of the font used

Size

Returns or sets the size of the font in points

StrikeThrough

(boolean) Turns strikethrough formatting on or off

Underline

(boolean) Turns underline formatting on or off

Weight

Returns or sets the weight of the characters. Weight refers to the thickness of the characters, or the "boldness factor"

ForeColor

Foreground color (use the RGB function to assign a color value)

FullRowSelect

(boolean) Determines if the entire row is selected (only in Report view).
The default is True

GridLines

(boolean) Determines if the ListView displays gridlines (in Report view).
The default is True

Height

(read-only) The height of the control in twips

HideColumn
Headers

(boolean) Determines if ColumnHeaders are hidden in Report view.
The default is False

HideSelection

(boolean) Determines whether selected text appears highlighted when the ListView control loses the focus. The default is False

HoverSelection

(boolean) Determines if a ListItem is selected when the mouse pointer hovers over it. The default is False

Icons

Returns or sets the ImageList controls associated with the Icon view.
Each ListItem object in the ListView also has an Icon property, which indexes the ListImage objects and determines which image is displayed.

LabelEdit

Determines if a user can edit the labels of the ListItem objects

0

Automatic (default). Label editing of a listitem is initiated when a selected object is clicked. That is, the first click on the object will select it; a second (single) click will initiate the label editing operation.

1

Manual. The StartLabelEdit method must be invoked to start label editing.

LabelWrap

(boolean) Determines whether or not labels are wrapped when a ListView control is in Icon view. The default is False

Left

The distance from the left edge of the specified container in twips

ListItems

Returns a reference to a collection of ListItems.

You can manipulate ListItems using standard collection methods (for example, the Remove method). Each ListItem can be accessed either by its index or by a unique key, stored in the Key property

MultiSelect

(boolean) Determines whether a user can select multiple objects or items.
The default is True

Parent

(read-only) Returns the parent form, object or collection. You can use the parent property to access the properties and methods of an object's parent

Picture

Returns or sets a graphic to be displayed in the control. This property can be set to any other object's DragIcon, Icon, Image, or Picture property, or you can assign it a graphic returned by the LoadPic function

Picture
Alignment

Determines the picture alignment:

0

Top left

1

Top right

2

Bottom left

3

Bottom right

4

Centered

5

Tiled (default)

SelectedItem

Returns a reference to a selected ListItem object. This property returns a reference to a ListItem object that can be used to set properties and invoke methods. It is typically used to return a reference to a ListItem object that the user has clicked or selected. To programmatically select a ListItem object, use the Set statement with the SelectedItem property, as follows:
Set ListView.SelectedItem = ListView.ListItems(1)

SmallIcons

Returns or sets the ImageList controls associated with the SmallIcon view.
Each ListItem object in the ListView also has a SmallIcon property, which indexes the ListImage objects and determines which image is displayed.

Sorted

(boolean) Determines whether the Listitems are sorted (according to the SortOrder property). Each time the coordinates of a ListItem change, the Sorted property is set to False. The default is False (not sorted)

SortKey

Determines how the ListItems are sorted

0

Sort using the ListItem's Text property

>0

Sort using the Subitem whose collection index is specified here

SortOrder

Determines whether items are sorted in ascending or descending order

0

Ascending order. Sorts from the beginning of the alphabet (A-Z) or the earliest date. Numbers are sorted as strings (the first digit determines the initial position in the sort, subsequent digits determine subsorting

1

Descending order. Sorts from the end of the alphabet (Z-A) or the latest date. Numbers are sorted as strings (see above)

TabStop

(boolean) Determines whether the TAB key can be used to move the focus

Tag

(reserved) Used internally to store the user-defined controlname

TextBackground

Determines if a ListItem object's text background is opaque or transparent

0

The text background is transparent (default)

1

The text background is the same color as the BackColor property

ToolTipText

Explanatory text that appears in a small rectangle below the object when you pause the mouse pointer (hover) over it for about one second

Top

The distance from the top edge of the specified container in twips

View

Determines the appearance of the ListItem objects

0

(Default) Icon. Each ListItem is represented by a full-sized (standard) icon and a text label

1

SmallIcon. Each ListItem is represented by a small icon and a text label that appears to the right of the icon. Items appear horizontally

2

List. Each ListItem is represented by a small icon and a text label that appears to the right of the icon. The ListItems are arranged vertically, each on its own line with information arranged in columns

3

Report. Each ListItem is displayed with its small icon and text labels. You can provide additional information for each ListItem in a subitem. The icons, text labels, and information appear in columns with the leftmost column containing the small icon, followed by the text label. Additional columns display the text for each of the subitems

Visible

(boolean) Determines whether the control is visible or hidden

Width

The width of the control in twips

Method

Description

FindItem

Parameters : String, [Value], [Index], [Match]

Finds and returns a reference to a ListItem object

String

A string expression indicating the ListItem object to be found.

Value

(optional) Determines how the specified string will be matched :

0

Matches with a Listitems Text property

1

Matches with any string in a Listitems SubItems property

2

Matches with a Listitems Tag property

Index

(optional) An integer or string that uniquely identifies a member of the ListItems collection and specifies the location from which to begin the search. The integer is the value of the Index property; the string is the value of the Key property. If not specified, the default is 1.

Match

(optional) Determines when a match will occur: This setting is ignored if the criteria is not text

0

(wholeword) A match will occur if the item's Text property begins with the whole word being searched.

1

(partial) A match will occur if the item's Text property begins with the string being searched.

GetFirstVisible

A listview can contain more ListItems than can be seen in the internal area of the ListView. You can use the reference returned by the GetFirstVisible method to determine the first visible ListItem object in List or Report view.

Move

Parameters: left [, top [, width ]]

Only the left argument is required. However, to specify any other arguments, you must specify all arguments that appear in the syntax before the argument you want to specify. For example, you can't specify width without specifying left and top. Any trailing arguments that are unspecified remain unchanged

Refresh

Forces a complete repaint of a control

SetFocus

Moves the focus to the specified control

StartLabelEdit

Enables a user to edit a label. This method must be used to initiate a label editing operation when the LabelEdit property is set to 1 (Manual)

Event

Description

Event raised

DblClick

Occurs when a listitem is double-clicked

Controlname

Enter

Occurs when the ENTER key is pressed

BackSpace

Occurs when the BACKSPACE key is pressed

Controlname <0>
"KeyBack"

Delete

Occurs when the DELETE key is pressed

Controlname <0>
"KeyDelete"

Insert

Occurs when the INSERT key is pressed

Controlname <0>
"KeyInsert"

AfterLabelEdit

Occurs after a user finishes editing the label of a listitem

Controlname <0>
Eventname <0>
New label

ItemCheck

Occurs when a listitem's checkbox is either selected or cleared (and the CheckBoxes property is enabled)

Controlname <0>
Eventname <0>
Listitem index

ItemClick

Occurs when a listitem is clicked

To be able to handle events you need to operate a form in callback mode.
This subject is described in the following topics: Callback forms, ClickHandler

See the NewListViewFileItem and GetAssociatedIcon pages for some more examples

Option Explicit

Const vbModal = 1

Dim oDlg, oFrm, oItem, sMsg

'Create the WshDialog.Kit object and store a reference in oDlg
Set oDlg = Wscript.CreateObject("WshDialog.Kit", "oDlg_")

'Call BuildForm to build the form and store a reference in oFrm
Set oFrm = BuildForm

'Show the form
oFrm.Show vbModal

'Show which listitems were checked and/or selected
For Each oItem In oFrm.Ctl("LVW1").ListItems
    sMsg = sMsg & oItem.Text & " : " & vbTab
    If oItem.Checked Then sMsg = sMsg & "Checked"
    sMsg = sMsg & vbTab
    If oItem.Selected Then sMsg = sMsg & " Selected"
    sMsg = sMsg & vbCrlf
Next
MsgBox sMsg, vbOkOnly, "Checked and/or selected item(s)"

'-------------------------------------------------------------------------------
' The BuildForm function builds the form and returns a reference to it
'-------------------------------------------------------------------------------
Function BuildForm

    Dim X, oFrm, oCtl, oItem, oSubItem, sIconLib, nColor, sOfficeDir

    'Add a form and store a reference to it in the variable oFrm
    Set oFrm = oDlg.NewForm("")

    'Set the form's caption
    oFrm.Caption = "Testing Listview and ImageList controls"

    'Add a FINISH button and set it's Default Property
    Set oCtl = oFrm.NewButton("FINISH", 3500, 200, 1000, 375, "&Finish")
    oCtl.Default = True

    '---------------------------------------------------------------------------
    'Add imagelist controls for small and large icons
    '---------------------------------------------------------------------------

    nColor = &H80000005 'Standard Windows background color
    sOfficeDir = "C:\Program Files\Microsoft Office\Office\"

    Set oCtl = oFrm.NewImageList("IMGSMALL", 16, 16)
    oCtl.ListImages.Add 1,"Vbs", oDlg.GetAssociatedIcon(WScript.ScriptFullName, True, nColor)
    oCtl.ListImages.Add 2,"Word", oDlg.GetICon(sOfficeDir & "WinWord.exe", True, , nColor)
    oCtl.ListImages.Add 3,"Excel", oDlg.GetICon(sOfficeDir & "Excel.exe", True, 1, nColor)

    Set oCtl = oFrm.NewImageList("IMGLARGE", 32, 32)
    oCtl.ListImages.Add 1,"Vbs", oDlg.GetAssociatedIcon(WScript.ScriptFullName, False, nColor)
    oCtl.ListImages.Add 2,"Word", oDlg.GetICon(sOfficeDir & "WinWord.exe", False, , nColor)
    oCtl.ListImages.Add 3,"Excel", oDlg.GetIcon(sOfficeDir & "Excel.exe", False, 1,nColor)

    '---------------------------------------------------------------------------
    'Add buttons to change the listview's view mode
    '---------------------------------------------------------------------------

    sIconLib = "C:\Program Files\Common Files\Microsoft Shared\Repostry\Repbrrc.dll"

    Set Octl = oFrm.NewButton("LVWBTN0", 150, 150, 500, 500, "")
    oCtl.Picture = oDlg.GetIcon(sIconLib, True, 46, oCtl.BackColor)
    oCtl.ToolTipText = "Large icons"
    Set oCtl = oFrm.NewButton("LVWBTN1", 750, 150, 500, 500, "")
    oCtl.Picture = oDlg.GetIcon(sIconLib, True, 47, oCtl.BackColor)
    oCtl.ToolTipText = "Small icons"
    Set oCtl = oFrm.NewButton("LVWBTN2", 1350, 150, 500, 500, "")
    oCtl.Picture = oDlg.GetIcon(sIconLib, True, 48, oCtl.BackColor)
    oCtl.ToolTipText = "List"
    Set oCtl = oFrm.NewButton("LVWBTN3", 1950, 150, 500, 500, "")
    oCtl.Picture = oDlg.GetIcon(sIconLib, True, 49, oCtl.BackColor)
    oCtl.ToolTipText = "Details"

    '---------------------------------------------------------------------------
    'Add the listview control
    '---------------------------------------------------------------------------

    Set oCtl = oFrm.NewListView("LVW1", 100, 750, 4500, 1500)

    oCtl.CheckBoxes = True 'If used, must be set before adding listitems!

    oCtl.Columnheaders.Add , "#1", "Article", oCtl.Width * 0.48
    oCtl.Columnheaders.Add , "#2", "Code", oCtl.Width * 0.30
    oCtl.Columnheaders.Add , "#3", "Stock", oCtl.Width * 0.20

    Set oItem = oCtl.ListItems.Add(, , "Bio-neural gel pack")
    'Method #1: Using the ColumnHeader KEY to add the SubItems
    oItem.SubItems(oCtl.ColumnHeaders("#2").SubItemIndex) = "VOY-116"
    oItem.SubItems(oCtl.ColumnHeaders("#3").SubItemIndex) = "34"

    Set oItem = oCtl.ListItems.Add(, , "Dilithium crystal")
    'Method #2: Using the Columnheader INDEX to add the SubItems
    oItem.SubItems(1) = "TOS-044"
    oItem.SubItems(2) = "7"

    Set oItem = oCtl.ListItems.Add(, , "Plasma infuser")
    'Method #3: Using the ListSubItems collection to add the SubItems
    Set oSubItem = oItem.ListSubItems.Add(, , "TNG-248")
    Set oSubItem = oItem.ListSubItems.Add(, , "12")

    'Assign the imagelists
    oCtl.Icons = oFrm.Ctl("IMGLARGE")
    oCtl.SmallIcons = oFrm.Ctl("IMGSMALL")

    'Assign an icon to each listitem
    For Each oItem In oCtl.ListItems
        oItem.Icon = oFrm.Ctl("IMGLARGE").ListImages(oItem.Index).Key
        oItem.SmallIcon = oFrm.Ctl("IMGSMALL").ListImages(oItem.Index).Key
    Next

    'Center the 2nd column and right-align the 3rd
    oCtl.ColumnHeaders(2).Alignment = 2
    oCtl.ColumnHeaders(3).Alignment = 1

    'Some addditional properties
    octl.AllowColumnReorder = True
    oCtl.GridLines = True
    oCtl.FullRowSelect = True
    oCtl.HideSelection = False
    oCtl.HoverSelection = True
    oCtl.LabelEdit = 0
    oCtl.LabelWrap = False
    oCtl.MultiSelect = True

    'Sort the listview in ascending order on the first column
    oCtl.Sorted = True
    oCtl.SortOrder = 0
    oCtl.SortKey = 0

    'Show the listview in report mode
    oCtl.View = 3

    '---------------------------------------------------------------------------

    'Automatically size the form to the controls placed on it
    oFrm.AutoSize

    'Show the form in the taskbar
    oFrm.TaskBar = True

    'Enable event handling (callback) for this form
    oFrm.CallBack = True

    'Return the form object
    Set BuildForm = oFrm

End Function

'-------------------------------------------------------------------------------
' oDlg_ClickHandler handles the events sent by the controls
'-------------------------------------------------------------------------------
Sub oDlg_ClickHandler(sForm, sControl)

    Dim oFrm, oCtl

    Set oFrm = oDlg.Frm(sForm)
    Set oCtl = oFrm.Ctl(sControl)

    Select Case UCase(sControl)
    Case "*F2"
        'Allow the user to edit a listitem's text property
        oFrm.Ctl("LVW1").StartLabelEdit
    Case "LVWBTN0", "LVWBTN1", "LVWBTN2", "LVWBTN3"
        'Switch the listview's view mode
        oFrm.Ctl("LVW1").View = Int("0" & Right(sControl, 1))
    Case "LVW1"
        'Handle the listview's default event (double-click)
        MsgBox oCtl.SelectedItem & " (#" & oCtl.SelectedItem.Index & ") double-clicked"
    Case "*CLOSE", "FINISH"
        'The closebox or finish button was clicked. Dismiss the form (hide it)
        oFrm.Hide
    Case Else
        'Ignore all other events. Do NOT use oFrm.Hide here, or any event
        'not handled above will dismiss the form
    End Select

End Sub