CImageList Class

CImageList Class

An "image list" is a collection of same-sized images, each of which can be referred to by its zero-based index. Image lists are used to efficiently manage large sets of icons or bitmaps. All images in an image list are contained in a single, wide bitmap in screen device format. An image list may also include a monochrome bitmap that contains masks used to draw images transparently (icon style). The Microsoft Win32 application programming interface (API) provides image list functions that enable you to draw images, create and destroy image lists, add and remove images, replace images, merge images, and drag images.

 

CImageList::Create

Initializes an image list and attaches it to a CImageList Class object.

BOOL Create(

   int cx,

   int cy,

   UINT nFlags,

   int nInitial,

   int nGrow 

);

BOOL Create(

   UINT nBitmapID,

   int cx,

   int nGrow,

   COLORREF crMask 

);

BOOL Create(

   LPCTSTR lpszBitmapID,

   int cx,

   int nGrow,

   COLORREF crMask 

);

BOOL Create(

   CImageList& imagelist1,

   int nImage1,

   CImageList& imagelist2,

   int nImage2,

   int dx,

   int dy 

);

BOOL Create(

   CImageList* pImageList 

);

Parameters

cx

Dimensions of each image, in pixels.

cy

Dimensions of each image, in pixels.

nFlags

Specifies the type of image list to create. This parameter can be a combination of the following values, but it can include only one of the ILC_COLOR values.

Value	Meaning
ILC_COLOR	Use the default behavior if none of the other ILC_COLOR* flags is specified. Typically, the default is ILC_COLOR4; but for older display drivers, the default is ILC_COLORDDB.
ILC_COLOR4	Use a 4-bit (16 color) device-independent bitmap (DIB) section as the bitmap for the image list.
ILC_COLOR8	Use an 8-bit DIB section. The colors used for the color table are the same colors as the halftone palette.
ILC_COLOR16	Use a 16-bit (32/64k color) DIB section.
ILC_COLOR24	Use a 24-bit DIB section.
ILC_COLOR32	Use a 32-bit DIB section.
ILC_COLORDDB	Use a device-dependent bitmap.
ILC_MASK	Uses a mask. The image list contains two bitmaps, one of which is a monochrome bitmap used as a mask. If this value is not included, the image list contains only one bitmap. See Drawing Images from an Image List for additional information on masked images.

nInitial

Number of images that the image list initially contains.

nGrow

Number of images by which the image list can grow when the system needs to resize the list to make room for new images. This parameter represents the number of new images the resized image list can contain.

nBitmapID

Resource IDs of the bitmap to be associated with the image list.

crMask

Color used to generate a mask. Each pixel of this color in the specified bitmap is changed to black, and the corresponding bit in the mask is set to one.

lpszBitmapID

A string containing the resource IDs of the images.

imagelist1

A reference to a CImageList object.

nImage1

Index of the first existing image.

imagelist2

A reference to a CImageList object.

nImage2

Index of the second existing image.

dx

Offset of the x-axis of the second image in relationship to the first image, in pixels.

dy

Offset of the y-axis of the second image in relationship to the first image, in pixels.

pImageList

A pointer to a CImageList object.

  

Return Value

 

Nonzero if successful; otherwise 0.

 Example

m_myImageList.Create(32, 32, ILC_COLOR8, 0, 4);

CImageList::Add

Call this function to add one or more images or an icon to an image list.

int Add(

   CBitmap* pbmImage,

   CBitmap* pbmMask 

);

int Add(

   CBitmap* pbmImage,

   COLORREF crMask 

);

int Add(

   HICON hIcon 

);

Parameters

pbmImage

Pointer to the bitmap containing the image or images. The number of images is inferred from the width of the bitmap.

pbmMask

Pointer to the bitmap containing the mask. If no mask is used with the image list, this parameter is ignored.

crMask

Color used to generate the mask. Each pixel of this color in the given bitmap is changed to black and the corresponding bit in the mask is set to one.

hIcon

Handle of the icon that contains the bitmap and mask for the new image.

Return Value

 

Zero-based index of the first new image if successful; otherwise – 1.

Example

// Add my icons.

m_myImageList.Add(AfxGetApp()->LoadIcon(IDI_ICON1));

m_myImageList.Add(AfxGetApp()->LoadIcon(IDI_ICON2));

// Add my bitmap, make all black pixels transparent.

CBitmap bm;

bm.LoadBitmap(IDB_BITMAP1);

m_myImageList.Add(&bm, RGB(0, 0, 0));

CImageList::Attach

Call this function to attach an image list to a CImageList object.

BOOL Attach(

   HIMAGELIST hImageList 

);

Parameters

hImageList

A handle to an image list object.

Return Value

 

Nonzero if the attachment was successful; otherwise 0.

 Example

void AddQuestion(HIMAGELIST hmyImageList)

{

   CImageList imgList;

   // Attach the image list handle to the CImageList object.

   imgList.Attach(hmyImageList);

   // Add a new icon to the image list.

   imgList.Add(AfxGetApp()->LoadStandardIcon(IDI_QUESTION));

   // Detach the handle from the CImageList object.

   imgList.Detach();

}

CImageList::Write

Call this function to write an image list object to an archive.

BOOL Write(

   CArchive* pArchive 

);

Parameters

pArchive

A pointer to a CArchive object in which the image list is to be stored.

Return Value

Nonzero if successful; otherwise 0.

Example

// Open the archive to store the image list in.

CFile   myFile(_T("myfile.data"), CFile::modeCreate | CFile::modeWrite);

CArchive ar(&myFile, CArchive::store);

// Store the image list in the archive.

m_myImageList.Write(&ar);