Windows Controls: An Image List

Once you get an image list, there is no pre-defined way you must use it. Some Windows controls use an image list to use the pictures they need but there are various other unpredictable ways you can use an image list.

1. To create a new application, on the main menu, click File -> New Project...
2. In the middle list, click Windows Application
3. Set the name to ImageViewer1 and click OK

To support image lists, the .NET Framework provides a class called ImageList that is defined in the System.Windows.Forms namespace of the System.Windows.Forms.dll library. At design time, to create an image list, from the Components section of the Toolbox, you can click the ImageList button  and click the form.

To programmatically create an image list, declare a variable of type ImageList and initialize it using one of its two constructors. The default constructor is used to simply signal that you are going to use an image list. Here is an example:

using System;
using System.Windows.Forms;

public class Exercise : Form
{
    private ImageList lstImages;

    public Exercise()
    {
        InitializeComponent();
    }

    void InitializeComponent()
    {
        lstImages = new ImageList();
    }
}

public class Program
{
    public static int Main()
    {
        Application.Run(new Exercise());

        return 0;
    }
}

The ImageList class is equipped with another constructor whose syntax is:

public ImageList(IContainer container);

This constructor expects as argument the control container that will be responsible for getting rid of the image list when the application exits.

1. From the Components section of the Toolbox, click ImageList and click the form
2. In the Properties window, change its Name to lstPictures
3. From the Components section of the Toolbox, click Timer and click the form
4. In the Properties window, change its characteristics as follows:
   Enabled: True
   Interval: 2000
5. From the Common Controls section of the Toolbox, click PictureBox and click the form
6. In the Properties window, change its characteristics as follows:
   (Name): pbxViewer
   Dock: Fill
7. Save all

Before creating an image list, you must prepare the image(s). As mentioned previously, you can use individual images that would be made into a set. When creating the images, your primary concern is the size you give them. The default size of a picture is 16x16.

If you are creating a list of icons, you can create each with the default size of 16x16. In some cases (for example if you intend to use the images for a list view), you can create or design a second set of icons whose size are 32x32 (and/or 48x48) each.

You can use a larger size:

• The maximum length a picture can have is 256 pixels
• The maximum height the picture can have is 256 pixels

To create or design your bitmaps, you can use either the bitmap designer of Microsoft Visual Studio or you can use a more advanced external application to prepare the pictures. Although the pictures used in an image list are usually square (16x16, 32x32, 48x48, 96x96, etc), you can use a different length and a different height but, if you are creating individual pictures, they should each have the same size (same length and same height).

Instead of using different pictures, you can create one long picture whose sections would be used to identify each picture. There is no particular way you must design the long picture and there is no real rule about its dimensions: the size would become an issue when it is time to use the picture(s). Alternatively, when creating the picture, if it will include the different pictures that would be considered in the list, make sure you know where each sectional picture starts and where it ends. In that case, there is one long picture made of different sections and each section holds a particular picture. When creating this type, you must know the size that holds each particular picture.

After preparing the pictures, you can get ready to create the image list. If you want, you can specify the size of each picture before actually creating the list. To support this, the ImageList class is equipped with a property named ImageSize. The ImageSize property is of type Size. You can use it to specify the size of each picture. Here is an example:

using System;
using System.Drawing;
using System.Windows.Forms;

public class Exercise : Form
{
    private ImageList lstImages;

    public Exercise()
    {
        InitializeComponent();
    }

    void InitializeComponent()
    {
        lstImages = new ImageList();
        lstImages.ImageSize = new Size(256, 256);
    }
}

If the image list has been created already, to find out the size of the picture, you can get the value of the ImageSize property.

1. Copy each of the following pictures and paste them in a directory or folder of your computer
    
2. Under the form, click lstPictures and, in the Properties window, set the ImageSize to 250, 165

Before creating the list of images, you must specify the number of bits that will be used to specify the color of each pixel. This information is referred to as the color depth. To support it, the ImageList class is equipped with a property named ColorDepth. The possible values are Depth4Bit, Depth8Bit, Depth16Bit, Depth24Bit, and Depth32Bit. The default value is Depth8Bit.

• Under the form, click lstPictures and, in the Properties window, set the ColorDeph to Depth32Bit

After preparing the pictures, to visually create the list of images, under the form, click the image list control to select it. Then:

• Click the arrow button on the control . Then click Choose Images
   
  
• In the Properties window, click the ellipsis button of the Images field

This would open the Images Collection Editor. To add a picture, you can click the Add button, locate a picture and select it. You can continue doing this until you have selected all necessary pictures. Here is an example:

After selecting the pictures, you can click OK.

To assist you with creating the list of images, the ImageList class is equipped with a property named Images, which is a collection. The ImageList.Images property is of type ImageCollection. The ImageCollection class implements the IList, the ICollection, and the IEnumerable interfaces.

Using the ImageCollection class through the Images property, you can add the necessary icons or pictures one at a time. To help you with this, the ImageCollection class implements the Add() method. If you are creating a list of icons, you can call the following version of the Add() method:

public void Add(Icon value);

If you are creating a list of pictures, you can call the following version of the Add() method:

public void Add(Image value);

Here is an example:

public class Exercise : Form
{
    private ImageList lstImages;

    public Exercise()
    {
        InitializeComponent();
    }

    void InitializeComponent()
    {
        lstImages = new ImageList();
        lstImages.ImageSize = new Size(256, 256);

        Image img1 = Image.FromFile("E:\\Programs\\image1.jpg");
        lstImages.Images.Add(img1);
        Image img2 = Image.FromFile("E:\\Programs\\Image2.jpg");
        lstImages.Images.Add(img2);
    }
}

Instead of adding one picture at a time, you can first store them in an array. To add an array of pictures, the ImageCollection class provides a method named AddRange and whose syntax is:

public void AddRange(Image[] images);

Here is an example:

void InitializeComponent()
{
        lstImages = new ImageList();
        lstImages.ImageSize = new Size(256, 256);

        Image img1 = Image.FromFile(@"E:\Programs\image1.jpg");
        lstImages.Images.Add(img1);
        Image img2 = Image.FromFile(@"E:\Programs\Image2.jpg");
        lstImages.Images.Add(img2);

        Image[] images =
        {
            Image.FromFile(@"E:\Programs\image3.jpg"),
            Image.FromFile(@"E:\Programs\Image4.jpg"),
            Image.FromFile(@"E:\Programs\Image5.jpg")
        };

        lstImages.Images.AddRange(images);
}

1. Under the form, click lstPictures
2. In the Properties window, click Images and click the ellipsis button
3. In the Images Collection Editor, click Add, locate one of the pictures you had saved, select it, and click Open
4. Do the same to select the other pictures
    
   
5. Click OK

After creating an image list, you can use it in your application. As it name implies, an image list is just a collection of images. The control that holds this collection does not define why or when the images would be used. Some Windows controls, such as the list view, the tab control or the toolbar, use them. Most of the time, you will know when a certain control needs an image list and how to use it. Otherwise, you can use the pictures in an image list in various ways. For example, you can use those pictures like any others, such as to display one on a form.

To support the ability to display the pictures of an image list, the ImageList class is equipped with a method named Draw. When calling this method, because the image list doesn't know where it would be used, and because the target control would not define where the picture is coming from, the primary argument to this method is the platform on which to display the picture. This platform is a Graphics object. Once you have decided on the receiving graphics, you must specified the location where the picture would be positioned. You have two primary options. You can specify the location by the left and top coordinates. In this case, you would use the following version of the Draw() method:

public void Draw(Graphics g, int x, int y, int index);

Alternatively, you can specify the location by a Point value. In this case, you would use the following version of the method:

public void Draw(Graphics g, Point pt, int index);

In both cases, the last argument is the index of the desired picture within the collection.

1. Under the form, double-click timer1 and change the file as follows:
   

   using System;
   using System.Collections.Generic;
   using System.ComponentModel;
   using System.Data;
   using System.Drawing;
   using System.Linq;
   using System.Text;
   using System.Windows.Forms;
   
   namespace ImageViewer1
   {
       public partial class Form1 : Form
       {
           static int index = 0;
   
           public Form1()
           {
               InitializeComponent();
           }
   
           private void timer1_Tick(object sender, EventArgs e)
           {
               if (index < 6)
               {
                   lstPictures.Draw(pbxViewer.CreateGraphics(),
                                              pbxViewer.Left,
                             	           pbxViewer.Top,
                             	           index);
                   index++;
               }
               else
                   index = 0;
           }
       }
   }

2. Execute the application to see the result
    
   
3. Close the form and return to your programming environment

When drawing the pictures of an image list, you can designate one color that the compiler will ignore or "see through". This is referred to as the transparent color. To support this, the ImageList class is equipped with a property named TransparentColor, which is of type Color.