jsImageList Design and Description

jsImageList is a non-visual dBL class which encapsulates basic ImageList functionality.

The 'spirit' of jsImageList is to exist as a standalone object, typically as a 'child' object of another object. jsImageList can also exist as a child of the global _sys object, similar to the way the frameWin is a child to the global _app object in the core product.
The image list concept is supported in the operating system's Common Controls Library. However, the ImageList is not a control or window at all. An image list is simply an in-memory bitmap which is represented by a handle, the same as bitmaps, fonts, brushes, and pens. And although the term "image list" might imply a textual list of image names, an image list is not that either. An image list is simply a bitmap containing a series of graphic images, all of which have the same height, and are arranged horizontally side-by-side in a horizontal strip. Here's an example of a simple image list bitmap:


This image list bitmap is 16 pixels high, and each graphic within the image list bitmap is 16 pixels wide. The system does not allow for irregular-width images within the image list. All images within the image list must be the same width. Each image space within an image list is sometimes referred to as a 'slot', or a position or index in the image list. The slot numbers are zero-based indexes into the image list. Starting at the left, the first image is at index zero, the second image is at index one, and so on.

The concept of image lists was developed for managing a relatively high quantity of relatively small images. As you have seen in other operating system facilities and applications such as the Explorer, although you may not have realized it, it is the image list facility that supports the loading, accessing, and displaying of all of those namespace, folder, and file icons. The operating system maintains a special image list, known as the system image list. The purpose of the system image list is to serve as a system-wide facility for storing and displaying the hundreds of icons used in the system in Explorer and other applications. In fact, jsProNav uses the system image list for the display of all icons. The system image list is operated as an on-demand image list. When a new icon needs to be displayed that has not yet been loaded into the system image list, it is dynamically loaded on the fly. If the system image list approaches its maximum capacity, there is supporting logic in the system to reuse 'slots' in the system image list based on a least recently accessed algorithm.

Image lists can be up to 32767 pixels wide. Considering that most image lists are used to hold images of 32 x 32 pixels, that computes to 1023 individual images that could theoretically be contained in a single image list. And 2047 16 x 16 pixel images could be contained in a single image list. Obviously, with the possible exception of the system image list, a typical application might need a few hundred images in total. Using image lists to load and manage the same-sized icons and bitmaps is much more efficient than trying to manage them in the way of the old 16-bit operating system using individual bitmap handles. Image lists also lead to more efficient use of memory. Rather than a few hundred individual images each with an associated handle, an image list can, as we have seen, hold hundreds of images, and all of the images can be accessed through the same handle, and all of the images are physically stored side-byside in a single memory block normally. The most efficient use of image lists is to preallocate an image list of sufficient size to hold all of the images required. The images don't have to be placed into the image list as a single group. They can be placed in the image list as needed on the fly.

The jsImageList class is used to load image list bitmaps like the one shown above. It can also create a 'blank' image list, into which individual same-sized bitmaps and icons can be placed, thereby creating an in-memory image list on the fly and on-demand, similar to the way the operating system dynamically maintains and updates the system image list. Additionally, jsImageList can load image list bitmaps, and then 'grow' the in-memory image list with additional blank slots into which individual bitmaps and icons can be inserted, thereby dynamically growing the original image list. The image list bitmaps and individual bitmaps and icons that are loaded into the image list with jsImageList can be in dll files, and/or in multiple individual bmp and ico files.

It is important to note that when an image list is created, a numeric handle is returned which represents the image list in memory. The handle returned when an image list is created is used to assign the image list to jsComboBoxEx, jsListView, jsNoteBook, and jsTreeView objects for displaying the images. It is very important to destroy this handle to release the system resources associated with the image list when the image list is no longer needed. The jsImageList class provides a destroy method for this purpose. Failure to destroy an image list handle when it is no longer needed will result in system resource leaks.