Microsoft Visual C++/MFC: Images Lists

	Images Lists

Introduction to Image Lists

Description

An image list is an array of pictures of the same size. The pictures are created as a series of icons, a single bitmap, or a group of bitmaps. Each icon or bitmap can be located using its index. The array is zero-based, meansing that the first picture has an index of 0. The second has an index of 1, etc.

An image list is not a traditional control. It does not display to the user who in fact is never aware of it. It is used to complement a control that needs a series of pictures for its own use.

Creating an Image List

In an MFC application, an image list is based on the CImageList class. This object is created in two main steps that do not necessarily follow each other. On one hand, you must have the pictures that will make the list. On the other hand, you must have a CImageList variable or pointer.

The easiest way is probably to first create the picture. There are two kinds: masked or nonmasked. A nonmasked image list is designed as an array of pictures where all pictures have the same width and the same height but the pictures do not have to be square. Here is an example:

A masked image list contains two pictures of the same with and height. Unlike the unmasked image list, both pictures of the masked image normally represent the same illustration. The first picture is in color and the second would be monochrome (black and white). Here is an example:

To actually create an image list, declare a CImageList variable or pointer and call one of its Create() member functions to initialize it. It is provided in various versions as follows:

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);

The first version of this member function allows you to describe the type of image list that will be created. This is done by specifying the width (cx) of each picture, the height (cy) of each picture, and a flag for the type of image list to create. The nInitial argument is the number of images that the image list will contain. The nGrow argument represents the number of images by which the image list can grow.

If you had designed an unmasked bitmap using the image editor and you want to initialize it, call the second or the third versions of the Create() member function. The nBitmapID argument is the identifier of the bitmap. If you want to provide the string that contains the identifiers of the images, pass it as the lpszBitmapID argument. The cx value represents the width of each picture. The crMask is the color used to mask the transparency of the picture. Each pixel of the picture that matches this color will turn to black. Here is an example of using this Create() member function:

BOOL CAnimation1Dlg::OnInitDialog()
{
    CDialog::OnInitDialog();

    SetIcon(m_hIcon, TRUE); // Set big icon
    SetIcon(m_hIcon, FALSE); // Set small icon

    // TODO: Add extra initialization here
    CImageList ImgList;

    ImgList.Create(IDB_IMGLIST, 48, 4, RGB(255, 55, 5));

    return TRUE; // return TRUE unless you set the focus to a control
}

Operations on an Image Lists

Adding an Item

Besides, or instead of using, the Create() member function, you can call CImageList::Add() to add a bitmap to the CImageList variable. Its syntaxes are:

int Add(CBitmap* pbmImage,
	CBitmap* pbmMask);
int Add(CBitmap* pbmImage,
	COLORREF crMask);
int Add(HICON hIcon);

The pbmImage argument represents the bitmap to be added, unless you want to add an icon, in which case you would use the third version. The pbmMask argument is the bitmap that will be used to mask the image list. You can use a color instead, in which case you would pass a COLORREF value as the second argument to the second version.

Deleting an Item

If you want to remove a picture from the image list, call the CImageList::Remove() member function. Its syntax:

BOOL Remove(int nImage);

The nImage argument is the index of the picture to be removed.

Replacing an Item

Instead of removing a picture, you can just replace it with another picture. This is done using the CImageList::Replace() member function whose syntaxes are:

BOOL Replace(int nImage, CBitmap* pbmImage, CBitmap* pbmMask);
int Replace(int nImage, HICON hIcon);

Drawing an Item

Once an image list is ready, you can use it directly in an application or make it available to a control that can use it. One way you can use an image list is to display one or more of its pictures on a dialog box, a form, or a view. To do this, you would call the CImageList::Draw() member function. Its syntax is:

BOOL Draw(CDC* pdc, int nImage, POINT pt, UINT nStyle);

The first argument, pdc, specifies the device context on which you are drawing. The nImage argument is the index of the picture you want to draw. The pt argument is a POINT or a CPoint value that specifies the location of the new picture. The nStyle argument is a flag that specifies how the picture will be drawn.