Image Lists and Icon Bundles

Sometimes it's useful to aggregate a number of images. You can use wxImageList directly in your application or in conjunction with some of the wxWidgets controls that require image lists when setting icons. wxNotebook, wxtreeCtrl, and wxListCtrl all support wxImageList to identify the icons used in the controls. You can also draw an individual image in a wxImageList on a device context.

Create a wxImageList with the width and height of each image, a boolean to specify whether a mask will be used, and the initial size of the list (purely for internal optimization purposes). Then add one or more wxBitmap or wxIcon images. You can't add a wxImage directly, but you can pass one to wxBitmap's constructor. wxImageList::Add returns an integer index you can use to identify that image; after you have added an image, the original image can be destroyed because wxImageList makes a copy of it.

Here are some examples of creating a wxImageList and adding images to it.

 // Create a wxImageList wxImageList *imageList = new wxImageList(16, 16, true, 1); // Add a bitmap with transparency from a PNG wxBitmap bitmap1(wxT("image.png"), wxBITMAP_TYPE_PNG); imageList->Add(bitmap1); // Add a bitmap with transparency from another bitmap wxBitmap bitmap2(wxT("image.bmp"), wxBITMAP_TYPE_BMP); wxBitmap maskBitmap(wxT("mask.bmp"), wxBITMAP_TYPE_BMP); imageList->Add(bitmap2, maskBitmap); // Add a bitmap with transparency specified with a color wxBitmap bitmap3(wxT("image.bmp"), wxBITMAP_TYPE_BMP); imageList->Add(bitmap3, *wxRED); // Add an icon #include "folder.xpm" wxIcon icon(folder_xpm); imageList->Add(icon); 

You can draw an image to a device context, passing flags that determine how the image will be drawn. Pass wxIMAGELIST_DRAW_TRANSPARENT to draw with transparency, and also one of these values to indicate the state that should be drawn: wxIMAGELIST_DRAW_NORMAL, wxIMAGELIST_DRAW_SELECTED, or wxIMAGELIST_DRAW_FOCUSED.

 // Draw all the images in the list wxClientDC dc(window); size_t i; for (i = 0; i < imageList->GetImageCount(); i++) {     imageList->Draw(i, dc, i*16, 0, wxIMAGELIST_DRAW_NORMAL|                                     wxIMAGELIST_DRAW_TRANSPARENT); } 

To associate icons with notebook tabs, create an image list containing 16x16 icons, and call wxNotebook::SetImageList or wxNotebook::AssignImageList. If you use the first form, the notebook doesn't delete the image list when it is destroyed; with the second form, the notebook takes over management of the list, and you don't have to worry about destroying it yourself. Now when you add pages, you can specify the index of an icon to use as the image next to the text label (or instead of it, if the text label is empty). The following code creates a notebook and adds two pages with icons on the tabs.

 // Create a wxImageList wxImageList *imageList = new wxImageList(16, 16, true, 1); // Add some icons wxBitmap bitmap1(wxT("folder.png"), wxBITMAP_TYPE_PNG); wxBitmap bitmap2(wxT("file.png"), wxBITMAP_TYPE_PNG); int folderIndex = imageList->Add(bitmap1); int fileIndex = imageList->Add(bitmap2); // Create a notebook and two pages wxNotebook* notebook = new wxNotebook(parent, wxID_ANY); wxPanel* page1 = new wxPanel(notebook, wxID_ANY); wxPanel* page2 = new wxPanel(notebook, wxID_ANY); // Assign the image list notebook->AssignImageList(imageList); // Add the pages, with icons notebook->AddPage(page1, wxT("Folder options"), true, folderIndex); notebook->AddPage(page2, wxT("File options"), false, fileIndex); 

wxtreeCtrl and wxListCtrl work in a similar way, with the option to assign or set the image list.

If you have a lot of icons and find it hard to keep track of icons by integer index, you might want to write a class that maps string names to the image list index. A simple implementation might look like this:

 #include "wx/hashmap.h" WX_DECLARE_STRING_HASH_MAP(int, IconNameToIndexHashMap); // Class to refer to image indices by name class IconNameToIndex { public:     IconNameToIndex() {}     // Add a named bitmap to the image list     void Add(wxImageList* list, const wxBitmap& bitmap,         const wxString& name) {         m_hashMap[name] = list->Add(bitmap);     }     // Add a named icon to the image list     void Add(wxImageList* list, const wxIcon& icon,         const wxString& name) {         m_hashMap[name] = list->Add(icon);     }     // Find the index from the name     int Find(const wxString& name) { return m_hashMap[name]; } private:     IconNameToIndexHashMap m_hashMap; }; 

The wxIconBundle class also aggregates images, but its purpose is to store an icon in multiple resolutions rather than multiple different images. This enables the system to choose the appropriate resolution for a given purpose. For example, the icon shown in the title bar of a frame may be smaller than the icon shown in a file or task manager. Here are some examples of creating and using an icon bundle.

 // Create a bundle with a single icon #include "file16x16.xpm" wxIconBundle iconBundle(wxIcon(file16x16_xpm)); // Add a further icon from a file iconBundle.Add(wxIcon(wxT("file32x32.png"), wxBITMAP_TYPE_PNG)); // Creates an icon bundle from several images in one file wxIconBundle iconBundle2(wxT("multi-icons.tif"), wxBITMAP_TYPE_TIF); // Gets the icon with the given size, or if not found, one with size // wxSYS_ICON_X, wxSYS_ICON_Y wxIcon icon = iconBundle.GetIcon(wxSize(16,16)); // Associates the icon bundle with a frame wxFrame* frame = new wxFrame(parent, wxID_ANY); frame->SetIcons(iconBundle); 

Under Windows, SetIcons exTRacts 16x16 and 32x32 icons from the icon bundle.