Puts an image in the control's image list into an overlay image list.

Applies to

ListView and TreeView controls


controlname.SetOverlayPicture ( overlayindex, imageindex )




The name of the ListView or TreeView control to which you want to add an overlay image.


The index number of the overlay picture in the overlay image list. The overlay image list is a 1-based array. Overlayindex must be 1 (for the first image), a previously designated index (replacing an image), or 1 greater than the current largest index (adding another image). SetOverlayPicture fails if you specify an index that creates gaps in the array.


The index number of an image in the control's main image list. For ListViews, both the large and small pictures at that index become overlay images. The image is still available for use as an item's main image.

Return value


Returns 1 if it succeeds and -1 if an error occurs.


An overlay picture must have the same height and width as the picture it is used to overlay. The color specified in the SetPictureMask property when the picture is inserted becomes transparent when the picture is used as an overlay, allowing part of the original image to be visible beneath the overlay.

The overlay list acts as a pointer back to the source image in the regular picture lists. If you delete an image that is also used in the overlay list, the displayed overlay pictures are affected too.


This example designates overlay images in a ListView control. The same picture is used for large and small images:

// Set up the overlay images
integer index
index = lv_1.AddLargePicture("shortcut.ico")
index = lv_1.AddSmallPicture("shortcut.ico")
lv_1.SetOverlayPicture(1, index)
index = lv_1.AddLargePicture("not.ico")
index = lv_1.AddSmallPicture("not.ico")
lv_1.SetOverlayPicture(2, index)
// Assign the second overlay image to the first item
listviewitem lvi
integer i
i = lv_1.GetItem(1, lvi)
lvi.OverlayPictureIndex = 2
i = lv_1.SetItem(1, lvi)

This example designates the first picture in the TreeView's main image list as the first overlay picture. The picture was added to the main image list on the TreeView's property sheet:

tv_list.SetOverlayPicture(1, 1)

This code in the TreeView's Clicked event assigns the overlay image to the clicked item:

treeviewitem tvi
tv_list.GetItem(handle, tvi)
tvi.OverlayPictureIndex = 1
tv_list.SetItem(handle, tvi)