IMAGELIST SET OVERLAY statement

Purpose | Create and manage an IMAGELIST object to use with other functions.

Syntax

IMAGELIST ADD BITMAP hLst, hBmp [,hMsk] [TO dataValue&]

IMAGELIST ADD BITMAP hLst, Bmp$ [,Msk$] [TO dataValue&]

IMAGELIST ADD ICON hLst, hIcn [TO dataValue&]

IMAGELIST ADD ICON hLst, Icn$ [TO dataValue&]

IMAGELIST ADD MASKED hLst, hBmp, rgbColor& [TO dataValue&]

IMAGELIST ADD MASKED hLst, Bmp$, rgbColor& [TO dataValue&]

IMAGELIST GET COUNT hLst TO dataValue&

IMAGELIST KILL hLst

IMAGELIST NEW BITMAP|ICON nWidth&, nHeight&, depth&, initial& TO hLst

IMAGELIST SET OVERLAY hLst, image&, overlay&

hBmp | Handle of a Bitmap.
hIcn | Handle of an Icon.
hLst | Handle of the IMAGELIST.
hMsk | Handle of a Mask.
dataValue& | A long integer variable to which result data is assigned.
rgbColor& | A RGB color used in the bitmap to specify transparent pixels.

Remarks

An IMAGELIST is a structure which contains any number of graphical images, either bitmaps or icons, but not a mixture. All of the images are automatically converted to the type, size, and color depth specified when the IMAGELIST is created. A bitmap (file type *.BMP) is a single color image, while an icon (file type *.ICO) supports transparency by including both a color bitmap and a mask bitmap. The mask bitmap is a monochrome image (one bit per pixel), where each "set" bit describes a pixel which remains transparent. The IMAGELIST structure can best be described as a set, or array, of images. You can retrieve the images individually by index number, or pass the entire IMAGELIST to a control which requires it ( LISTVIEW, etc.).

An empty ImageList is first created with IMAGELIST NEW. Images are then added with IMAGELIST ADD, until the structure is complete. If you add an image which is wider than the size specified by nWidth&, the image is separated into multiple bitmaps, each of which is added in sequence. When an IMAGELIST is attached to a control like LISTVIEW, it is usually destroyed automatically when the control is destroyed. Consult the control documentation for that information. If not, you must explicitly destroy it with IMAGELIST KILL.

IMAGELIST ADD BITMAP hLst, hBmp [,hMsk] [TO dataValue&]

An image is added to the ImageList specified by hLst. With this syntax, the image is specified by a handle (hBmp), so it must have been loaded into memory (e.g. with string). If the ImageList is an ICON type, a second mask bitmap is also specified by a handle (hMsk). If the TO clause is included, the index position of the first added bitmap (starting with 1) is assigned to the variable designated by dataValue&. If the operation fails, the value 0 is assigned.

IMAGELIST ADD BITMAP hLst, Bmp$ [,Msk$] [TO dataValue&]

An image is added to the ImageList specified by hLst. With this syntax, the image is specified by a name string (Bmp$), which is the name of an embedded resource or a disk file. If the name string contains a period, it is presumed to be a disk file. Otherwise, an attempt is made to load it from a resource - if not found, it is then presumed to be a disk file. If the image name is a numeric resource, it should be described with a leading pound sign ("#12345"). If the ImageList is an ICON type, a second mask bitmap is also specified by a handle (hMsk). If the TO clause is included, the index position of the first added bitmap (starting with 1) is assigned to the variable designated by dataValue&. If the operation fails, the value 0 is assigned.

IMAGELIST ADD ICON hLst, hIcn [TO dataValue&]

An icon is added to the ImageList specified by hLst. With this syntax, the icon is specified by a handle (hIcn), so it must have been loaded into memory (e.g. with the WinApi LoadIcon. If the TO clause is included, the index position of the first added icon (starting with 1) is assigned to the variable designated by dataValue&. If the operation fails, the value 0 is assigned.

IMAGELIST ADD ICON hLst, Icn$ [TO dataValue&]

An icon is added to the ImageList specified by hLst. With this syntax, the icon is specified by a name string (Icn$), which is the name of an embedded resource or a disk file. If the name string contains a period, it is presumed to be a disk file. Otherwise, an attempt is made to load it from a resource - if not found, it is then presumed to be a disk file. If the icon name is a numeric resource, it should be described with a leading pound sign ("#12345"). If the TO clause is included, the index position of the first added bitmap (starting with 1) is assigned to the variable designated by dataValue&. If the operation fails, the value 0 is assigned.

IMAGELIST ADD MASKED hLst, hBmp, rgbColor& [TO dataValue&]

A bitmap is added to the icon ImageList specified by hLst. With this syntax, the bitmap is specified by a handle (hBmp), so it must have been loaded into memory (e.g. with GRAPHIC BITMAP). The parameter rgbColor& specifies the RGB color used in the bitmap to specify transparent pixels. Each pixel of that color is changed to the color black, and a mask bitmap is created to describe the transparent pixels. If the TO clause is included, the index position of the first added icon (starting with 1) is assigned to the variable designated by dataValue&. If the operation fails, the value 0 is assigned.

IMAGELIST ADD MASKED hLst, Bmp$, rgbColor& [TO dataValue&]

A bitmap is added to the icon ImageList specified by hLst. With this syntax, the bitmap is specified by a name string (Bmp$), which is the name of an embedded resource or a disk file. If the name string contains a period, it is presumed to be a disk file. Otherwise, an attempt is made to load it from a resource - if not found, it is then presumed to be a disk file. If the image name is a numeric resource, it should be described with a leading pound sign ("#12345"). The parameter rgbColor& specifies the RGB color used in the bitmap to specify transparent pixels. Each pixel of that color is changed to the color black, and a mask bitmap is created to describe the transparent pixels. If the TO clause is included, the index position of the first added bitmap (starting with 1) is assigned to the variable designated by dataValue&. If the operation fails, the value 0 is assigned.

IMAGELIST GET COUNT hLst TO dataValue&

The number of images in the IMAGELIST is retrieved, and assigned to the long integer variable specified by dataValue&.

IMAGELIST KILL hLst

The IMAGELIST specified by hLst is destroyed. All allocated memory and resources are released.

IMAGELIST NEW BITMAP|ICON nWidth&, nHeight&, depth&, initial& TO hLst

A new ImageList structure is created. If you specify BITMAP, each image you add will be stored as a single bitmap. If you specify ICON, each image you add will be stored as two bitmaps in order to support transparent areas. The parameters nWidth& and nHeight& specify the size of each image in pixels. The depth& parameter specifies the color depth in bits per pixel (4,8,16,24,32). A depth of 4 offers 16 colors, 8 offers 256 colors, etc. The initial& parameter specifies the initial size of the ImageList. While it can grow beyond this number, it is most efficient to allocate space accurately at the time of creation. The variable hLst receives the handle of the newly created ImageList, or zero if the operation failed.

IMAGELIST SET OVERLAY hLst, image&, overlay&

The image specified by the index number image& is declared to be an overlay image. The overlay& parameter must be in the range of 1 to 15, and it is used later to retrieve and/or specify this particular overlay image.

See also | GRAPHIC BITMAP LOAD, GRAPHIC BITMAP NEW, GRAPHIC IMAGELIST, LISTVIEW, TAB SET IMAGELIST, TREEVIEW, XPRINT IMAGELIST