Visual Basic: Windows Controls

ImageList Control

See Also    Example    Properties    Methods    Events

An ImageList control contains a collection of ListImage objects, each of which can be referred to by its index or key. The ImageList control is not meant to be used alone, but as a central repository to conveniently supply other controls with images.

Syntax

ImageList

Remarks

The ImageList control functions as a storehouse for images, and as such, it needs a second control to display the stored images. The second control can be any control that can display an image's Picture object, or it can be one of the Windows Common Controls that were specifically designed to bind to the ImageList control. These include the ListView, ToolBar, TabStrip, ImageCombo, and TreeView controls. In order to use an ImageList with one of these controls, you must bind a particular ImageList control with the second control through an appropriate property. For the ListView control, you must set the Icons and SmallIcons properties to ImageList controls. For the TreeView, TabStrip, ImageCombo, and Toolbar controls, you must set the ImageList property to an ImageList control.

At design time, you can add images using the Images tab of the ImageList Control Properties dialog box. At run time, you can add images using the Add method for the ListImages collection.

For the Windows Common Controls, you can specify an ImageList at design time using the Custom Properties dialog box. At run time, you can also specify an ImageList control using the ImageList property, as in the following example:

TreeView1.ImageList = ImageList1  ' Specify ImageList

Important   When using the ImageList control with a Windows Common Control, insert all of the images you will require, in the order you desire, into the ImageList before binding it to the second control. Once the ImageList is bound to a second control, you cannot delete images, and you cannot insert images into the middle of the ListImages collection. However, you can add images to the end of the collection.

Once you associate an ImageList with a Windows Common Control, you can use the value of either the Index or Key property to refer to a ListImage object in a procedure. The following example sets the Image property of a TreeView control's third Node object to the first ListImage object in an ImageList control:

' Use the value of the Index property of ImageList1.
TreeView1.Nodes(3).Image = 1
' Or use the value of the Key property.
TreeView1.Nodes(3).Image = "image 1"   ' Assuming Key is "image 1."

To use the ImageList control with other controls (that can't be bound to the ImageList control), assign the Picture property of the second control to the Picture object of any image in the ImageList control. For example, the following code assigns the Picture object of the first ListImage object in a ListImages collection to the Picture property of a newly created StatusBar panel:

Dim pnlX As Panel
Set pnlX = StatusBar1.Panels.Add() ' Add a new Panel object.
Set pnlX.Picture = ImageList1.ListImages(1).Picture ' Set Picture.

Note   You must use the Set statement when assigning an image to a Picture object.

You can insert any size image into the ImageList control. However, the size of the image displayed by the second control depends on one factor: whether or not the second control is also a Windows Common control bound to the ImageList control.

When the ImageList control is bound to another Windows Common Control, images of different sizes can be added to the control, however the size of the image displayed in the associated Windows Common Control will be constrained to the size of the first image added to the ImageList. For example, if you add an image that is 16 by 16 pixels to an ImageList control, then bind the ImageList to a TreeView control (to be displayed with Node objects), all images stored in the ImageList control will be displayed at 16 by 16 pixels, even if they are much larger or smaller.

On the other hand, if you display images using the Picture object, any image stored in the ImageList control will be displayed at its original size, no matter how small or large.

Distribution Note   The ImageList control is part of a group of ActiveX controls that are found in the MSCOMCTL.OCX  file. To use the ImageList control in your application, you must add the MSCOMCTL.OCX  file to the project. When distributing your application, install the MSCOMCTL.OCX  file in the user's Microsoft Windows System or System32 directory. For more information on how to add an ActiveX control to a project, see the Programmer's Guide.