Introduction to Image Lists

Description

An image list is an array of pictures of the same size. The pictures are created as a single icon or bitmap and each icon or bitmap can be located using its index. The array is zero-based, meaning 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 display. This means that, when you decide to create an image list, you must know why you need one and what you intend to use it for.

1. Start Embarcadero RAD Studio
2. To create a new application, on the main menu, click File -> New -> VCL Forms Application - C++Builder
3. In the Object Inspector, click Caption and type Picture Review

The image list does not create the necessary images for the list. It only stores them for eventual retrieval. Therefore, before creating a list of images, you must first create the actual pictures that would make up the list. To prepare the images, you can use any normal picture editor, including Windows Paint that installs with the operating system.

There are two categories of image lists:

• A masked image list is made of two pictures (bitmaps) of the same size. The first bitmap is made of colors. Here is an example:
  
  
   
  The second is in black and white. Here is an example
   
  
• A non-masked image list is a colored bitmaps with one or more pictures. Here is an example:

Based on the above description, there are two layouts to follow for an image list. You can create or use one picture, in color or not. This would be used on masked scenarios. The second technique consists of creating a single, long picture that contains each of the needed pictures. In this case, you would add this single picture to the image list at once. The picture should (must) provide a series of pictures uniformly dimensioned.

• Copy the chicken images and paste them in a folder of your choice

In the Win32, an image list of a handle to HIMAGELIST. To create an image list, you call the ImageList_Create() function. Its syntax is:

HIMAGELIST ImageList_Create(
    int cx,
    int cy,
    UINT flags,
    int cInitial,
    int cGrow
);

The VCL provides support for image lists through a class named TImageList. The TImageList class is derived from TDragImageList that itself is based on the TCustomImageList class. The TCustomImageList class is derived from TComponent:

To visually start an image list, in the Win32 section of the Tool Palette, click the TImageList button and click the form (or a container). If you are planning to use images that are larger than 32x32 pixels, you should create the control programmatically.

To dynamically create an image list, declare a pointer to TImageList. Here is an example:

//---------------------------------------------------------------------------
class TForm1 : public TForm
{
__published: // IDE-managed Components
private:
	TImageList *lstImages; // User declarations
public: // User declarations
	__fastcall TForm1(TComponent* Owner);
};
//---------------------------------------------------------------------------

Before implementing it, use the new operator on its constructor to indicate its owner. This could be done as follows:

//---------------------------------------------------------------------------
__fastcall TForm1::TForm1(TComponent* Owner)
: TForm(Owner)
{
    lstImages = new TImageList(this);
}
//---------------------------------------------------------------------------

If you plan to use more than one image list, you can then declare either various TImageList variables or an array of TImageList variables. An example would be:

//---------------------------------------------------------------------------
class TForm1 : public TForm
{
__published: // IDE-managed Components
private:
	TImageList *lstSingleImages;
	TImageList *lstMultipleImages; // User declarations
public: // User declarations
	__fastcall TForm1(TComponent* Owner);
};
//---------------------------------------------------------------------------

//---------------------------------------------------------------------------
__fastcall TForm1::TForm1(TComponent* Owner)
	: TForm(Owner)
{
    lstSingleImages = new TImageList(this);
    lstMultipleImages = new TImageList(this);
}
//---------------------------------------------------------------------------

1. Under the Code Editor, click Unit1.h and, in the private section, declare a variable as follows: TImageList *lstPictures;
2. Click Unit1.cpp and change the constructor as follows:

   //---------------------------------------------------------------------------
   __fastcall TForm1::TForm1(TComponent* Owner)
   	: TForm(Owner)
   {
   	lstPictures = new TImageList(this);
   }
   //---------------------------------------------------------------------------

3. Press F12 to display the form

After visually adding an image list to a form or container, to add one or more pictures, right-click it and click ImageList Editor... or double-click it. This would open the ImageList Editor. In the ImageList Editor, click the Add button, locate and select the picture. Click Open. In the same way, you can add as many pictures as you need. The other buttons on the dialog box allow you to delete one picture or to clear the whole list. The pictures are added subsequently and each occupies a specific position. If you want to change the position of a picture, click and drag it left or right.

 If you are programmatically creating the list of images, you can add each icon or picture individually if they were created as separate entities. You can also add a single long bitmap that is made of various pictures.

To add a bitmap to an image list, call the Add() method. Its syntax is:

int __fastcall Add(Graphics::TBitmap* Image, Graphics::TBitmap* Mask);

The first parameter, Image, is the bitmap you are adding to the list.

1. Double-click the middle of the form to generate its OnCreate event
2. Implement it as follows (change the path to the one where your pictures are located):

   //---------------------------------------------------------------------------
   void __fastcall TForm1::FormCreate(TObject *Sender)
   {
   	Graphics::TBitmap * bmpPicture = NULL;
   
   	bmpPicture = new Graphics::TBitmap;
   	bmpPicture->LoadFromFile(L"C:\\Exercise\\chicken1.bmp");
   	lstPictures->Add(bmpPicture, bmpPicture);
   
   	bmpPicture = new Graphics::TBitmap;
   	bmpPicture->LoadFromFile(L"C:\\Exercise\\chicken2.bmp");
   	lstPictures->Add(bmpPicture, bmpPicture);
   
   	bmpPicture = new Graphics::TBitmap;
   	bmpPicture->LoadFromFile(L"C:\\Exercise\\chicken3.bmp");
   	lstPictures->Add(bmpPicture, bmpPicture);
   
   	bmpPicture = new Graphics::TBitmap;
   	bmpPicture->LoadFromFile(L"C:\\Exercise\\chicken4.bmp");
   	lstPictures->Add(bmpPicture, bmpPicture);
   
   	bmpPicture = new Graphics::TBitmap;
   	bmpPicture->LoadFromFile(L"C:\\Exercise\\chicken5.bmp");
   	lstPictures->Add(bmpPicture, bmpPicture);
   
   	// Adjust the size of the form to size of the image
   	ClientWidth = lstPictures->Width;
   	ClientHeight = lstPictures->Height;
   }
   //---------------------------------------------------------------------------

Like other graphics controls, an image list has dimensions. The width of the image list is the width of each one of its pictures. Remember that all pictures must have the same width. The width is set or controlled by the Width property. This would be specified as follows:

//---------------------------------------------------------------------------
__fastcall TForm1::TForm1(TComponent* Owner)
	: TForm(Owner)
{
	lstSingleImages = new TImageList(this);
	lstMultipleImages = new TImageList(this);

	Graphics::TBitmap *multipleBitmaps[4];

	multipleBitmaps[0] = new Graphics::TBitmap;
	lstMultipleImages->Width = multipleBitmaps[0]->Width;

	multipleBitmaps[1] = new Graphics::TBitmap;
	lstMultipleImages->Width = multipleBitmaps[1]->Width;
}
//---------------------------------------------------------------------------

The height of an image list is the normal height of each of its pictures. It is set or controlled by the Height property.

1. In the constructor, specify the size of the images of the list as follows:

   //---------------------------------------------------------------------------
   __fastcall TForm1::TForm1(TComponent* Owner)
   	: TForm(Owner)
   {
   	lstPictures = new TImageList(this);
   	lstPictures->Width  = 500;
   	lstPictures->Height = 375;
   }
   //---------------------------------------------------------------------------

2. Press F12 to display the form

As stated already, there are two categories of bitmaps or icons that can be used on an image list: masked or non-masked. To make an image list masked, set the Masked property to true.

If you are programmatically adding the pictures to the image list using the Add() method, if the bitmap is masked, specify the bitmap used as the mask for the second argument. If you had set the Masked property to false, the Mask argument would be ignored. This means that you can pass it as NULL.

If the image list is made of a single bitmap, you can simply add it normally. If the list will be created from various separate bitmaps, make sure you add each. Here is an example:

//---------------------------------------------------------------------------
__fastcall TForm1::TForm1(TComponent* Owner)
	: TForm(Owner)
{
	lstMultipleImages = new TImageList(this);
	lstMultipleImages->Masked = False;
	Graphics::TBitmap *multipleImages[4];

	multipleImages[0] = new Graphics::TBitmap;
	multipleImages[0]->LoadFromFile("Picture1.bmp");
	lstMultipleImages->Width = multipleImages[0]->Width;
	lstMultipleImages->Height = multipleImages[0]->Height;
	lstMultipleImages->Add(multipleImages[0], NULL);

	. . .
}
//---------------------------------------------------------------------------

If you had set the Masked property to true but the bitmap is not doubled, instead of using a color as the mask, call the AddMasked() method. Its syntax is:

int __fastcall AddMasked(Graphics::TBitmap* Image, Graphics::TColor MaskColor);

The Image parameter is the bitmap to add to the list. Once again, the second argument will depend on whether the Masked property is true. If it is, you can pass a MaskColor color to be used to mask the bitmap.

After specifying that the image list will use the Masked attribute, use the ImageType property to indicate whether the picture is doubled or will use two sets of colors. The possible values of this property derive from the TImageType enumerator whose members are:

After specifying that the picture of an image list is masked, when drawing a picture from an image list, you can control what color would serve as its background. This is set or retrieved using the BkColor property. If the Masked property is set to true, the BkColor color would be used to replace the masked sections of the picture.

To retrieve the bitmap stored at a specific position in the list, call the GetBitmap() method. Its syntax is:

void __fastcall GetBitmap(int Index, Graphics::TBitmap* Image);

Before calling this method, you should declare a pointer to TBitmap and pass it as the second argument. The Index value indicates the index of the bitmap in the list. If the bitmap exists, it is returned as the Image parameter.

To add an icon to an image list, call the AddIcon() method. Its syntax is:

int __fastcall AddIcon(Graphics::TIcon* Image);

The Image parameter is the icon that needs to be added.

Each of these methods (Add() and AddIcon()) returns the index of the bitmap or icon that was added if the method succeeded. If it fails, it returns –1 indicating that the icon or bitmap was not added.

Once the bitmaps or icons have been added, if you want to find out how many images are in the list, get the TImageList::Count property.

1. In the top section of the Object Inspector, click Events and double-click OnClick
2. Implement the event as follows:

   //---------------------------------------------------------------------------
   void __fastcall TForm1::FormClick(TObject *Sender)
   {
   	static int CurrentPosition = 0;
   
   	if( CurrentPosition == lstPictures->Count )
   		CurrentPosition = 0;
   	else
   	{
   		Graphics::TBitmap * bmpCurrent = new Graphics::TBitmap;
   
   		lstPictures->GetBitmap(CurrentPosition++, bmpCurrent);
   		Canvas->Draw(0, 0, bmpCurrent);
   	}
   }
   //---------------------------------------------------------------------------

3. Press F9 to execute the application
4. Click the middle of the form
    
   
    
   
5. Close the form and return to your programming environment

If you want to remove a picture from the image list, call the TImageList::Delete() method. Its syntax:

void __fastcall Delete(int Index);

The Index value is the index of the picture to be removed. Instead of removing a picture, you can just replace it with another picture. This is done using the TImageList::Replace() method whose syntaxes are:

void __fastcall Replace(int Index,
                        Graphics::TBitmap* Image,
                        Graphics::TBitmap* Mask);

The Index value specifies the index bitmap to replace.

The Image parameter is the new bitmap. If the bitmap is masked, the second parameter, Mask, specifies what bitmap will serve as mask.

If you want to replace an icon, call the ReplaceIcon() method.

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 form. To do this, you would call the TImageList::Draw() method. It comes in two syntaxes as follows:

void __fastcall Draw(Graphics::TCanvas* Canvas,
                     int X,
                     int Y,
                     int Index,
                     bool Enabled = true);
void __fastcall Draw(Graphics::TCanvas* Canvas,
                     int X,
                     int Y,
                     int Index,
                     TDrawingStyle ADrawingStyle,
                     TImageType AImageType,
                     bool Enabled = true);

The Draw() method is used to draw one of the images on a device context. The Canvas parameter specifies the device on which the bitmap or icon will be drawn.

The X and the Y values are the point location where the drawing would start. That will be the top-left corner of the displaying bitmap or icon.

The Index parameter specifies the index of the picture to be drawn, from the list of images. The list is zero-based, meaning the first image has an index of 0, the second is 1, etc.

Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::Image2Click(TObject *Sender)
{
	static int ImgCounter = 0;

	Graphics::TBitmap *Bmp = new Graphics::TBitmap;

	if( ImgCounter < MultiImages->Count )
	{
		MultiImages->GetBitmap(ImgCounter, Bmp);
		// Image2->Picture->Bitmap = Bmp;
		MultiImages->Draw(this->Canvas,
		                  Image2->Left, 
		                  Image2->Top,
		                  ImgCounter);
		ImgCounter++;
	}
	else
		ImgCounter = 0;
}
//---------------------------------------------------------------------------