Using ListView controls

A ListView control allows you to display items and icons in a variety of arrangements. You can display large icon or small icon freeform lists, or you can display a vertical static list. You can also display additional information about each list item by associating additional columns with each list item:

ListView controls consist of ListView items, which are stored in an array. Each ListView item consists of a:

  • Label

    The name of the ListView item

  • Index

    The position of the ListView item in the control

  • Picture index

    The number that associates the ListView item with an image

    Depending on the style of the presentation, an item could be associated with a large picture index and a small picture index.

  • Overlay picture index

    The number that associates the ListView item with an overlay picture

  • State picture index

    The number that associates the ListView item with a state picture

For more information about ListView items, picture indexes, and presentation style, see the section called “ListView” in Users Guide.

Creating ListView controls

You add ListView controls to windows in the same way you add other controls: select ListView from the Insert>Control menu and click the window.

Adding ListView items

In the painter

Use the Items property page for the control to add items.

To add items to a ListView:

  1. Select the Items tab in the Properties view for the control.

  2. Enter a name and a picture index number for each of the items you want to add to the ListView.

    Clearing all entries on the Items tab page

    Setting the picture index for the first item to zero clears all the settings on the tab page.

    For more information about adding pictures to a ListView control, see Adding pictures to ListView controls.

In a script

Use the AddItem and InsertItem functions to add items to a ListView dynamically at runtime. There are two levels of information you supply when you add items to a ListView using AddItem or InsertItem.

You can add an item by supplying the picture index and label, as this example shows:

lv_1.AddItem ("Item 1", 1)

or you can insert an item by supplying the item's position in the ListView, label, and picture index:

lv_1.InsertItem (1,"Item 2", 2)

You can add items by supplying the ListView item itself. This example in the ListView's DragDrop event inserts the dragged object into the ListView:

listviewitem lvi
This.GetItem(index, lvi)
lvi.label = "Test"
lvi.pictureindex = 1
This.AddItem (lvi)

You can insert an item by supplying the ListView position and ListView item:

listviewitem l_lvi
//Obtain the information for the
//second listviewitem
lv_list.GetItem(2, l_lvi)
//Change the item label to Entropy
//Insert the second item into the fifth position
lv_list.InsertItem (5, l_lvi)

Adding pictures to ListView controls

PowerBuilder stores ListView images in four image lists:

  • Small picture index

  • Large picture index

  • State picture index

  • Overlay picture index

You can associate a ListView item with these images when you create a ListView in the painter or use the AddItem and InsertItem at runtime.

However, before you can associate pictures with ListView items, they must be added to the ListView control.

In the painter

Use the Pictures and Items property pages for the control to add pictures.

To add pictures to a ListView control:

  1. Select the Large Picture, Small Picture, or State tab in the Properties view for the control.

    Overlay images

    You can add overlay images only to a ListView control in a script.

  2. Select an image from the stock image list, or use the Browse button to select a bitmap, cursor, or icon image.

  3. Select a color from the PictureMaskColor drop-down menu for the image.

    The color selected for the picture mask appears transparent in the ListView.

  4. Select a picture height and width for your image.

    This controls the size of the image in the ListView.

    Dynamically changing image size

    The image size can be changed at runtime by setting the PictureHeight and PictureWidth properties before you add any pictures when you create a ListView. For more information about PictureHeight and PictureWidth, see the section called “PictureHeight” in Objects and Controls and the section called “PictureWidth” in Objects and Controls.

  5. Repeat the procedure for the:

    • Number of image types (large, small, and state) you plan to use in your ListView

    • Number of images for each type you plan to use in your ListView

In a script

Use the functions in the following table to add pictures to a ListView image.


Adds a picture to this list


Large image


Small image


State image

Adding large and small pictures

This example sets the height and width for large and small pictures and adds three images to the large picture image list and the small picture image list:

//Set large picture height and width

//Add large pictures

//Set small picture height and width

//Add small pictures

//Add items to the ListView
lv_1.AddItem("Item 1", 1)
lv_1.AddItem("Item 2", 1)
lv_1.AddItem("Item 3", 1)

Adding overlay pictures

Use the SetOverLayPicture function to use a large picture or small picture as an overlay for an item. This example adds a large picture to a ListView, and then uses it for an overlay picture for a ListView item:

listviewitem lvi_1
int li_index

//Add a large picture to a ListView
li_index = lv_list.AddLargePicture &

//Set the overlay picture to the
//large picture just added
lv_list.SetOverlayPicture (3, li_index)

//Use the overlay picture with a ListViewItem
lv_list.GetItem(lv_list.SelectedIndex (), lvi_1)
lvi_1.OverlayPictureIndex = 3
lv_list.SetItem(lv_list.SelectedIndex (), lvi_1)

Adding state pictures

This example uses an item's state picture index property to set the state picture for the selected ListView item:

listviewitem lvi_1

lv_list.GetItem(lv_list.SelectedIndex (), lvi_1)
lvi_1.StatePictureIndex = 2
lv_list.SetItem(lv_list.SelectedIndex (), lvi_1)

Deleting ListView items and pictures

You can delete items from a ListView one at a time with the DeleteItem function, or you can use the DeleteItems function to purge all the items in a ListView. Similarly, you can delete pictures one at a time with the DeleteLargePicture, DeleteSmallPicture, and DeleteStatePicture functions, or purge all pictures of a specific type by using the DeleteLargePictures, DeleteSmallPictures, and DeleteStatePictures functions.

This example deletes one item and all the small pictures from a ListView:

int li_index
li_index = This.SelectedIndex()
This.DeleteItem (li_index)
This.DeleteSmallPictures ()

Hot tracking and one- or two-click activation

Hot tracking changes the appearance of items in the Listview control as the mouse moves over them and, if the mouse pauses, selects the item under the cursor automatically. You can enable hot tracking by setting the TrackSelect property to TRUE.

Setting either OneClickActivate or TwoClickActivate to TRUE also enables hot tracking. When OneClickActivate is TRUE, you can specify that either selected or unselected items are underlined by setting the UnderlineHot or UnderlineCold properties. All these properties can be set on the control's general properties page or in a script.

The settings for OneClickActivate and TwoClickActivate shown in the following table affect when the ItemActivate event is fired.



ItemActivate is fired when you



Click any item



Click a selected item



Double-click any item

Using custom events

In PowerBuilder 7 and later releases, PowerBuilder uses Microsoft controls for ListView and Treeview controls, and the events that fire when the right mouse button is clicked are different than in earlier releases. These are the events that fire when the right mouse button is clicked in a ListView control:



Events fired

On an item in the ListView

Press right mouse button


Release right mouse button

pbm_lvnrclicked (stock RightClicked! event)


On white space in the ListView

Press right mouse button


pbm_lvnrclicked (stock RightClicked! event)


Release right mouse button



Using report view

ListView report view requires more information than the large icon, small icon, and list view. To enable report view in a ListView control, you must write a script that establishes columns with the AddColumn and SetColumn functions, and then populate the columns using the SetItem function.

Populating columns

Use AddColumn to create columns in a ListView. When you use the AddColumn function, you specify the:

  • Column label

    The name that will display in the column header

  • Column alignment

    Whether the text will be left-aligned, right-aligned, or centered

  • Column size

    The width of the column in PowerBuilder units

This example creates three columns in a ListView:

This.AddColumn("Name", Left!, 1000)
This.AddColumn("Size", Left!, 400)
This.AddColumn("Date", Left!, 300)

Setting columns

Use SetColumn to set the column number, name, alignment, and size:

This.SetColumn (1, "Composition", Left!, 860)
This.SetColumn (2, "Album", Left!, 610)
This.SetColumn (3, "Artist", Left!, 710)

Setting column items

Use SetItem to populate the columns of a ListView:

This.SetItem (1, 1, "St.Thomas")
This.SetItem (1, 2, "Saxophone Colossus")
This.SetItem (1, 3, "Sonny Rollins")
This.SetItem (2, 1, "So What")
This.SetItem (2, 2, "Kind of Blue")
This.SetItem (2, 3, "Miles Davis")
This.SetItem (3, 1, "Good-bye, Porkpie Hat")
This.SetItem (3, 2, "Mingus-ah-um")
This.SetItem (3, 3, "Charles Mingus")

For more information about adding columns to a ListView control, see the section called “AddColumn” in PowerScript Reference.