Before we can talk about how information is added to the list control, we need to say a few words about how a list control manages images. Any image used within a list control must first be added to an image list, which is an indexed array of images stored with the list control. When associating an image with a specific item in the list control, the index of the image within the image list is used to refer to the image, rather than using the image itself. This mechanism ensures that each image is loaded only once, no matter how often it is used in the list. This serves to conserve memory in the case where an icon is repeated in several items in a list. It also allows for a relatively straightforward connection between multiple versions of the same image that can be used to denote different modes. For more information on creating wxPython images and bitmaps, see chapter 12.
Creating an image list
The image list is an instance of wx.lmageList, with the following constructor.
wx.ImageList(width, height, mask=True, initialCount=1)
The width and height parameters specify the pixel size of the images added to the list. Images larger than the specified size are not allowed. The mask parameter is a Boolean. If True, the image is drawn with its mask, if it has one. The initial-Count parameter sets the initial internal size of the list. If you know that the list is going to be quite large, specifying the count initially may save memory allocations and time later on.
You can add an image to the list using the method Add(bitmap, mask=wx.NullBit-map), where bitmap and mask are both instances of wx.Bitmap. The mask argument is a monochrome bitmap that represents the transparent parts of the image, if any. If the bitmap already has a mask associated with it, the associated mask is used by default. If the bitmap doesn't have a mask and you don't have a monochrome transparency map, but would rather set a specific color of the bitmap as the transparent color, you can use the method AddWithColourMask(bitmap, colour), where the colour is the wxPython color (or the name of one) to use as the mask. If you have a wx.lcon object to add to the image list, use the method Addlcon(icon). All of the add methods return the index where the new image has been assigned inside the list, which you can hold on to if you want to use the image later on.
The following code snippet displays an example of creating an image list (similar to listing 13.1).
il = wx.ImageList(32, 32, True) for name in glob.glob("icon??.png"):
bmp = wx.Bitmap(name, wx.BITMAP_TYPE_PNG) il_max = il.Add(bmp)
The image list must then be assigned to a list control using the following method call.
To remove an image from the image list, use the Remove(index) method, where index is the integer index into the image list. This method modifies the index values for any image after that point in the image list, which might cause problems if you are dependent on specific index values elsewhere in the program. To remove the entire image list, use RemoveAll(). You can modify the bitmap at a specific index with the method Replace(index, bitmap, mask=wx.NullBitmap), where index is the index in the image list to modify, and bitmap and mask are as in Add(). If the item to modify is an icon, use the method ReplaceIcon(index, icon). There isn't a replace method that manages color masks.
You can get the length of the image list by using the method GetImageCount(), and the size of each individual image by using the method GetSize(), which returns a tuple (width, height).
While not directly relevant in the list control context, you can also draw an image from an image list onto a device context. For more information about device contexts, see chapters 6 and 12. The method is Draw, as in the following:
Draw(index, dc, x, y, flags=wx.IMAGELIST_DRAW_NORMAL, solidBackground=False)
In this call, the index parameter is the index of the item to draw within the image list and the dc parameter is a wx.DC device context to draw to. The x and y parameters are the starting position on the device context to draw the image. The flags control how the image is drawn, and bitmask of one or more of the constants wx.IMAGELIST_DRAW_NORMAL, wx.IMAGELIST_DRAW_TRANSPARENT, wx.IMAGELIST_ DRAW_SELECTED, and wx.IMAGELIST_DRAW_FOCUSED. If solidBackground is True, the draw method uses a faster algorithm works only if the background being drawn on is solid.
Once you have an image list, you need to attach it to the list control. This is done using one of two list control methods, AssignImage(imageList, which) or SetImage(imageList, which). The two methods take identical parameters, the first being the image list, and the second being an integer flag with the value wx.IMAGE_LIST_NORMAL or wx.IMAGE_LIST_SMALL. The only difference between the two is how the image list is managed on the C + + side. With AssignImage(), the image list becomes part of the list control and is destroyed when the list control is. With SetImage(), the image list retains a separate life, and is not automatically disposed of when the list control is destroyed, but will instead be disposed of when the Python object goes out of scope.
The list control can have two image lists assigned to it. The normal list, which is the one assigned with wx.image_list_normal, is used in the display of regular icon mode. The small image list, assigned with wx.image_list_small, is used in report and small icon mode. Under most circumstances, you only need to add one image list, but if you want the list to display in multiple modes (so the user can move from normal to small icon mode), you should provide both lists. If you do that, remember that the list control items will only know about images via the index into the image list, so the two image lists must match index for index. If the document icon is index two in the normal sized image list, it must also be index two in the small image list.
There is also an associated getter method for the list control, GetImage-List(which), that returns the image list associated with the which flag passed to the method.
Was this article helpful?