ImageList class

An ImageList is a list of pictures of one size, kept for other controls to show: a button takes its picture from it, a list its icons. The control itself shows nothing at run time.

ImageList1.ListImages.Add , "open", ColorSquare(vbRed)
ImageList1.ListImages.Add , "save", ColorSquare(vbBlue)
Debug.Print ImageList1.ListImages.Count
Debug.Print ImageList1.ImageWidth; ImageList1.ImageHeight
Debug.Print ImageList1.ListImages("save").Index
' Output:
'  2
'  16  16
'  2

ColorSquare in the samples of this page is a function of the program’s own. It returns a bitmap of one color, 16 pixels wide and high unless it is given another size. A program takes its pictures from files with LoadPicture, or from the Picture of another control.

The control stands in place of the ImageList of the Microsoft common controls (MSCOMCTL.OCX). The WinNativeCommonCtls package has an ImageList too. This one adds RightToLeftMirror and SystemColorDepth. It differs in three things: a new list keeps 24 bits for each pixel, not 32; it does not scale a bitmap to the size of the list; and a program can clear it while a control shows its pictures.

Of the common members, the control has Name, Parent and Tag alone. It has no window, so it has no place on the form at run time and no mouse or keyboard members.

Its sub-objects have pages of their own:

Filling the list

ListImages returns the collection of the pictures, and its Add method puts a picture into the list, with a key by which the program can name it later. The pictures are numbered from 1.

Every picture of a list has the same size, ImageWidth by ImageHeight pixels. In a new list both are 0, and the first picture added sets them to its own size. A program that wants another size sets both before it adds the first picture. While the list holds a picture, an assignment to either raises run-time error 35611, Property is read-only if image list contains images.

Debug.Print ImageList1.ImageWidth
ImageList1.ListImages.Add , , ColorSquare(vbRed, 24, 24)
Debug.Print ImageList1.ImageWidth
On Error Resume Next
ImageList1.ImageWidth = 32
Debug.Print Err.Number
' Output:
'  0
'  24
'  35611

A picture is an icon or a bitmap. An icon of another size is scaled to the size of the list. A bitmap is not scaled, so a program gives the list bitmaps of the list’s own size.

Clear, and a Remove of the only picture left, make the list new again: ImageWidth and ImageHeight are 0, also where the program had set them, and hImageList is 0.

Transparent parts

An icon has its own transparent parts. For a bitmap, the list makes one color transparent as the bitmap is added: every pixel of the color MaskColor, while UseMaskColor is True. Both are read at the time of Add, so a program sets them before it adds a bitmap, and a change does nothing to the pictures already in the list.

ImageList1.MaskColor = vbMagenta                        ' magenta pixels are transparent
ImageList1.ListImages.Add , "open", ColorSquare(vbRed)
ImageList1.UseMaskColor = False                         ' the next bitmap has no transparent part
ImageList1.ListImages.Add , "photo", ColorSquare(vbMagenta)

What is behind a picture shows through its transparent parts. With UseBackColor set to True the list fills them with BackColor wherever a picture is drawn, in a control or by Draw.

Giving the list to a control

A control that shows pictures from an image list has a property that takes the list. On CheckBoxW, OptionButtonW, CommandButtonW and CommandLink it is ImageList, and so it is on CoolBar, ImageCombo, TabStrip and TreeView. A ToolBar takes one in each of ImageList, HotImageList, PressedImageList and DisabledImageList. A ListView takes one in each of Icons, SmallIcons, ColumnHeaderIcons and GroupIcons. Such a property takes the ImageList control itself, the name of an ImageList control on the same form as a string, or the handle that hImageList returns.

The other control takes the image list of Windows that the ImageList control holds at the time of the assignment. An empty list holds none, so the program fills the list first and assigns it afterwards. An empty list leaves the other control without an image list, with no error.

CheckBoxW1.ImageList = ImageList1                       ' too early: the list is empty
Debug.Print TypeName(CheckBoxW1.ImageList)
ImageList1.ListImages.Add , , ColorSquare(vbRed)
CheckBoxW1.ImageList = ImageList1
Debug.Print TypeName(CheckBoxW1.ImageList)
' Output:
' Nothing
' ImageList

A picture added to a list that a control already shows is in that control’s list too. Clear, and the removal of the only picture left, destroy the image list of Windows, and the other control is left with a handle that is no longer valid: assign the list to it again once the list has pictures.

Pictures made from the list

The list also gives pictures back. The Draw method of a picture draws it on a device context, the ExtractIcon method returns it as an icon, and Overlay returns an icon of one picture with another drawn over it, such as a file’s icon with the arrow of a shortcut.

Dim Icon As StdPicture
ImageList1.ListImages.Add , "file", ColorSquare(vbWhite)
ImageList1.ListImages.Add , "arrow", ColorSquare(vbBlue)
Set Icon = ImageList1.Overlay("file", "arrow")
Debug.Print Icon.Type = vbPicTypeIcon
' Output:
' True
A page and the arrow of a shortcut, each drawn from the list with ListImages("file") and ListImages("arrow"), and beside them the icon that Overlay("file", "arrow") returns: the page with the arrow over its bottom left corner

Properties

BackColor

The color that fills the transparent parts of a picture where it is drawn, while UseBackColor is True. OLE_COLOR. Default: vbWindowBackground.

A value that is not a color, such as -1, raises run-time error 380.

ColorDepth

The number of bits the list keeps for each pixel of a picture. A member of ImlColorDepthConstants. Default: ImlColorDepth24Bit.

Another value raises run-time error 380. While the list holds a picture, an assignment raises run-time error 35611.

hImageList

The handle of the image list of Windows that holds the pictures, for an API function or for the property of a control that takes a handle. LongPtr, read-only. The control owns the image list and destroys it: a program does not.

It is 0 while the list is empty, unless the program has set both ImageWidth and ImageHeight.

ImageHeight

The height of every picture of the list, in pixels. Long. Default: 0, with which the first picture added sets it. See Filling the list.

A negative value raises run-time error 380. While the list holds a picture, an assignment raises run-time error 35611.

ImageWidth

The width of every picture of the list, in pixels. Long. Default: 0, with which the first picture added sets it. See Filling the list.

A negative value raises run-time error 380. While the list holds a picture, an assignment raises run-time error 35611.

ListImages

The pictures of the list. An ImlListImages collection, read-only.

MaskColor

The color of a bitmap that becomes transparent as the bitmap is added, while UseMaskColor is True. OLE_COLOR. Default: &HC0C0C0, a light gray. A system color, such as vbButtonFace, stands for the color it has at the time of the addition.

A change has no effect on the pictures already in the list.

RightToLeftMirror

Whether Windows draws the pictures mirrored in a window that is laid out from right to left, so that a picture that points in a direction of the text still does. Boolean. Default: False. It has an effect when the program has visual styles.

While the list holds a picture, an assignment raises run-time error 35611.

SystemColorDepth

The number of bits for each pixel of the display. ImlColorDepthConstants, read-only. A program can assign it to ColorDepth where it is one of that enumeration’s members.

UseBackColor

Whether the transparent parts of a picture are filled with BackColor where the picture is drawn. Boolean. Default: False, with which they show what is behind the picture. A change applies at once to every picture of the list.

UseMaskColor

Whether the color MaskColor of a bitmap becomes transparent as the bitmap is added. Boolean. Default: True.

With False a bitmap is added whole, with no transparent part.

Methods

Overlay

Returns a new icon: one picture of the list with another drawn over it. The first picture shows through the transparent parts of the second.

Syntax: object.Overlay( Index1, Index2 ) As IPictureDisp

Index1
required The number or the key of the picture underneath.
Index2
required The number or the key of the picture drawn over it.

The icon has the size of the list’s pictures, and it is the program’s: it does not change when the list does. In an empty list the method returns Nothing. A number or a key that the list does not have raises the error that Item raises for it.

ImlColorDepthConstants

The values of ColorDepth: the number of bits for each pixel.

Member Value Description
ImlColorDepth4Bit 4 16 colors.
ImlColorDepth8Bit 8 256 colors.
ImlColorDepth16Bit 16 65,536 colors.
ImlColorDepth24Bit 24 Every color, a byte each for red, green and blue.
ImlColorDepth32Bit 32 Every color, and a fourth byte that says how far a pixel is transparent: the depth for icons with soft edges.

ImlDrawConstants

The values of the Style argument of the Draw method of a picture. The members can be added together.

A picture of a folder drawn with each style over a chequered ground, in two rows. With UseBackColor set to False: ImlDrawNormal and ImlDrawTransparent show the ground round the folder, ImlDrawSelected covers the folder with every other pixel blue, ImlDrawFocus with one pixel in four blue, and ImlDrawNoMask fills the transparent parts black. With UseBackColor set to True and BackColor to vbYellow, the transparent parts are yellow in every style but ImlDrawTransparent, ImlDrawNoMask included
Member Value Description
ImlDrawNormal 1 The picture as the list holds it: its transparent parts are filled with BackColor while UseBackColor is True.
ImlDrawTransparent 2 The transparent parts are left as they are on the device context, whatever UseBackColor is.
ImlDrawSelected 4 The picture mixed half and half with the highlight color of Windows, as a selected icon is shown.
ImlDrawFocus 8 The picture mixed with a quarter of the highlight color.
ImlDrawNoMask 16 The picture without its transparent parts: the pixels of a bitmap that had the mask color are drawn black, or in BackColor when UseBackColor is True.

See Also

  • ImlListImages class – the collection of the pictures
  • ImlListImage class – one picture
  • Common members – the members this control shares with the package’s other controls
  • ImageList – the control of the same name in the WinNativeCommonCtls package