
An image list is a collection of images of the same size, each of which can be referred to by its index. Image lists are used to efficiently manage large sets of icons or bitmaps. All images in an image list are contained in a single, wide bitmap in screen device format. An image list can also include a monochrome bitmap that contains masks used to draw images transparently (icon style).
Image List Updates in Internet Explorer
The Microsoft® Win32® application programming interface (API) provides image list functions that enable you to create and destroy image lists, add and remove images, replace and merge images, draw images, and drag images.
To use the image list functions, include the common control header file in your source code files and link with the common control export library. In addition, before calling any image list function, use the InitCommonControls function to ensure that the common control dynamic-link library (DLL) is loaded.
There are two types of image lists: nonmasked and masked. A nonmasked image list consists of a color bitmap that contains one or more images. A masked image list consists of two bitmaps of equal size. The first is a color bitmap that contains the images, and the second is a monochrome bitmap that contains a series of masksone for each image in the first bitmap.
When a nonmasked image is drawn, it is simply copied into the target device context; that is, it is drawn over the existing background color of the device context. When a masked image is drawn, the bits of the image are combined with the bits of the mask, typically producing transparent areas in the bitmap where the background color of the target device context shows through. There are several drawing styles that you can specify when drawing a masked image. For example, you can specify that the image be dithered to indicate a selected object.
You create an image list by calling the ImageList_Create function. The parameters include the type of image list to create, the dimensions of each image, and the number of images you intend to add to the list. For a nonmasked image list, the function creates a single bitmap large enough to hold the specified number of images of the given dimensions. Then it creates a screen-compatible device context and selects the bitmap into it. For a masked image list, the function creates two bitmaps and two screen-compatible device contexts. It selects the image bitmap into one device context and the mask bitmap into the other. The common control DLL contains the executable code for the image list functions.
In ImageList_Create, you specify the initial number of images that will be in an image list as well as the number of images by which the list can grow. So if you attempt to add more images than you initially specified, the image list automatically grows to accommodate the new images.
If ImageList_Create succeeds, it returns a handle to the HIMAGELIST type. You use this handle in other image list functions to access the image list and manage the images. You can add and remove images, copy images from one image list to another, and merge images from two different image lists. When you no longer need an image list, you can destroy it by specifying its handle in a call to the ImageList_Destroy function.
The following example creates a masked image list and uses the ImageList_AddIcon function to add two icons to the list.
// AddIconsToImageList - creates a masked image list and adds some
// icons to it.
// Returns the handle to the new image list.
// hinst - handle to the application instance.
//
// Global variables and constants
// g_nBird and g_nTree - indexes of the images.
// cx_icon and cy_icon - width and height of the icon.
// num_icons - number of icons to add to the image list.
extern int g_nBird, g_nTree;
#define CX_ICON 32
#define CY_ICON 32
#define NUM_ICONS 3
HIMAGELIST AddIconsToImageList(HINSTANCE hinst)
{
HIMAGELIST himlIcons; // handle to new image list
HICON hicon; // handle to icon
// Ensure that the common control DLL is loaded.
InitCommonControls();
// Create a masked image list large enough to hold the icons.
himlIcons = ImageList_Create(CX_ICON, CY_ICON, TRUE, NUM_ICONS, 0);
// Load the icon resources, and add the icons to the image list.
hicon = LoadIcon(hinst, MAKEINTRESOURCE(IDI_BIRD));
g_nBird = ImageList_AddIcon(himlIcons, hicon);
hicon = LoadIcon(hinst, MAKEINTRESOURCE(IDI_TREE));
g_nTree = ImageList_AddIcon(himlIcons, hicon);
return himlIcons;
}
You can add bitmapped images, icons, or cursors to an image list. You add bitmapped images by specifying the handles to two bitmaps in a call to the ImageList_Add function. The first bitmap contains one or more images to add to the image bitmap, and the second bitmap contains the masks to add to the mask bitmap. For nonmasked image lists, the second bitmap handle is ignored; it can be set to NULL.
The ImageList_AddMasked function also adds bitmapped images to a masked image list. This function is similar to ImageList_Add, except that you do not specify a mask bitmap. Instead, you specify a color that the system combines with the image bitmap to automatically generate the masks. Each pixel of the specified color in the image bitmap is changed to black, and the corresponding bit in the mask is set to 1. As a result, any pixel in the image that matches the specified color is transparent when the image is drawn.
The ImageList_AddIcon function adds an icon or cursor to an image list. If the image list is masked, ImageList_AddIcon adds the mask provided with the icon or cursor to the mask bitmap. If the image list is nonmasked, the mask for the icon or cursor is not used when drawing the image.
You can create an icon based on an image and mask in an image list by using the ImageList_GetIcon function. The function returns the handle to the new icon.
ImageList_Add, ImageList_AddMasked, and ImageList_AddIcon assign an index to each image as it is added to an image list. The indexes are zero-based; that is, the first image in the list has an index of zero, the next has an index of one, and so on. After adding a single image, the functions return the index of the image. When more than one image is added at a time, the functions return the index of the first image.
The ImageList_Remove function removes an image from an image list.
The ImageList_Replace and ImageList_ReplaceIcon functions replace an image in an image list with a new image. ImageList_Replace replaces an image with a bitmapped image and mask, and ImageList_ReplaceIcon replaces an image with an icon or cursor.
The ImageList_Merge function merges two images, storing the new image in a new image list. The new image is created by drawing the second image transparently over the first. The mask for the new image is the result of performing a logical OR operation on the bits of the masks for the two existing images.
To draw an image, you use the ImageList_Draw or ImageList_DrawEx function. You specify the handle to an image list, the index of the image to draw, the handle to the destination device context, a location within the device context, and one or more drawing styles.
When you specify the ILD_TRANSPARENT style, ImageList_Draw or ImageList_DrawEx uses a two-step process to draw a masked image. First, it performs a logical AND operation on the bits of the image and the bits of the mask. Then it performs a logical XOR operation on the results of the first operation and the background bits of the destination device context. This process creates transparent areas in the resulting image; that is, each white bit in the mask causes the corresponding bit in the resulting image to be transparent.
Before drawing a masked image on a solid color background, you should use the ImageList_SetBkColor function to set the background color of the image list to the same color as the destination. Setting the color eliminates the need to create transparent areas in the image and enables ImageList_Draw or ImageList_DrawEx to simply copy the image to the destination device context, resulting in a significant increase in performance. To draw the image, specify the ILD_NORMAL style in a call to ImageList_Draw or ImageList_DrawEx.
You can set the background color for a masked image list at any time so that it draws correctly on any solid background. Setting the background color to CLR_NONE causes images to be drawn transparently by default. To retrieve the background color of an image list, use the ImageList_GetBkColor function.
The ILD_BLEND25 and ILD_BLEND50 styles dither the image with the system highlight color. These styles are useful if you use a masked image to represent an object that the user can select. For example, you can use the ILD_BLEND50 style to draw the image when the user selects it.
A nonmasked image is copied to the destination device context using the SRCCOPY raster operation. The colors in the image appear the same regardless of the background color of the device context. The drawing styles specified in ImageList_Draw or ImageList_DrawEx also have no effect on the appearance of a nonmasked image.
The following function draws an image and saves the client coordinates of the image's bounding rectangle. A subsequent function uses the bounding rectangle to determine whether the user has clicked the image.
// DrawTheImage - draws an image transparently and saves
// the bounding rectangle of the drawn image.
// Returns TRUE if successful, or FALSE otherwise.
// hwnd - handle to the window in which to draw the image.
// himl - handle to the image list that contains the image.
// cx and cy - client coordinates for the upper-left corner of the image.
//
// Global variables and constants
// g_nImage - index of the image to draw.
// g_rcImage - bounding rectangle of the image.
// CX_IMAGE and CY_IMAGE - width and height of the image.
extern int g_nImage;
extern RECT g_rcImage;
#define CX_IMAGE 32
#define CY_IMAGE 32
BOOL DrawTheImage(HWND hwnd, HIMAGELIST himl, int cx, int cy)
{
HDC hdc;
if ((hdc = GetDC(hwnd)) == NULL)
return FALSE;
if (!ImageList_Draw(himl, g_nImage, hdc, cx, cy, ILD_TRANSPARENT))
return FALSE;
ReleaseDC(hwnd, hdc);
SetRect(&g_rcImage, cx, cy, CX_IMAGE + cx, CY_IMAGE + cy);
return TRUE;
}
The Win32 API includes functions for dragging an image on the screen. The dragging functions move an image smoothly, in color, and without any flashing of the cursor. Both masked and unmasked images can be dragged.
The ImageList_BeginDrag function begins a drag operation. The parameters include the handle to the image list, the index of the image to drag, and the location of the hot spot within the image. The hot spot is a single pixel that the dragging functions recognize as the exact screen location of the image. Typically, an application sets the hot spot so that it coincides with the hot spot of the mouse cursor. The ImageList_DragMove function moves the image to a new location.
The ImageList_DragEnter function sets the initial position of the drag image within a window and draws the image at the position. The parameters include the handle to the window in which to draw the image and the coordinates of the initial position within the window. The coordinates are relative to the window's upper-left corner, not the client area. The same is true for all of the image dragging functions that take coordinates as parameters. This means you must compensate for the widths of window elements such as the border, title bar, and menu bar when specifying the coordinates. If you specify a NULL window handle when calling ImageList_DragEnter, the dragging functions draw the image in the device context associated with the desktop window, and the coordinates are relative to the upper-left corner of the screen.
ImageList_DragEnter locks all other updates to the given window during the drag operation. If you need to do any drawing during a drag operation, such as highlighting the target of the operation, you can temporarily hide the dragged image by using the ImageList_DragLeave function. Another method is to use the GetDCEx function with the DCX_LOCKWINDOWUPDATE value to retrieve a device context that allows you to draw. Be careful, however, not to obliterate the dragged image.
The ImageList_SetDragCursorImage function creates a new drag image by combining the given image (typically a mouse cursor image) with the current drag image. Because the dragging functions use the new image during a drag operation, you should use the ShowCursor function to hide the actual mouse cursor after calling ImageList_SetDragCursorImage. Otherwise, the system may appear to have two mouse cursors for the duration of the drag operation.
When an application calls ImageList_BeginDrag, the system creates a temporary, internal image list and then copies the specified drag image to the internal list. You can retrieve the handle to the temporary drag image list by using the ImageList_GetDragImage function. The function also retrieves the current drag position and the offset of the drag image relative to the drag position.
The following function is intended to be called in response to a mouse button-down message, such as WM_LBUTTONDOWN. The function determines whether the user has clicked within the bounding rectangle of the image. If the user has clicked, the function captures the mouse input, erases the image from the client area, and calculates the position for the hot spot within the image. The function sets the hot spot to coincide with the hot spot of the mouse cursor. Then the function begins the drag operation by calling ImageList_BeginDrag.
// StartDragging - begins dragging a bitmap.
// Returns TRUE if successful, or FALSE otherwise.
// hwnd - handle to the window in which the bitmap is dragged.
// ptCur - coordinates of the cursor.
// himl - handle to the image list.
//
// Global variables
// g_rcImage - bounding rectangle of the image to drag.
// g_nImage - index of the image.
// g_ptHotSpot - location of the image's hot spot.
// g_cxBorder and g_cyBorder - width and height of border.
// g_cyCaption and g_cyMenu - height of title bar and menu bar.
extern RECT g_rcImage;
extern int g_nImage;
extern POINT g_ptHotSpot;
BOOL StartDragging(HWND hwnd, POINT ptCur, HIMAGELIST himl)
{
// Return if the cursor is not in the bounding rectangle of
// the image.
if (!PtInRect(&g_rcImage, ptCur))
return FALSE;
// Capture the mouse input.
SetCapture(hwnd);
// Erase the image from the client area.
InvalidateRect(hwnd, &g_rcImage, TRUE);
UpdateWindow(hwnd);
// Calculate the location of the hot spot, and save it.
g_ptHotSpot.x = ptCur.x - g_rcImage.left;
g_ptHotSpot.y = ptCur.y - g_rcImage.top;
// Begin the drag operation.
if (!ImageList_BeginDrag(himl, g_nImage,
g_ptHotSpot.x, g_ptHotSpot.y))
return FALSE;
// Set the initial location of the image, and make it visible.
// Because the ImageList_DragEnter function expects coordinates to
// be relative to the upper-left corner of the given window, the
// width of the border, title bar, and menu bar need to be taken
// into account.
ImageList_DragEnter(hwnd, ptCur.x + g_cxBorder,
ptCur.y + g_cyBorder + g_cyCaption + g_cyMenu);
g_fDragging = TRUE;
return TRUE;
}
The following function, which drags the image to a new location, is intended to be called in response to the WM_MOUSEMOVE message.
// MoveTheImage - drags an image to the specified coordinates.
// Returns TRUE if successful, or FALSE otherwise.
// ptCur - new coordinates for the image.
BOOL MoveTheImage(POINT ptCur)
{
if (!ImageList_DragMove(ptCur.x, ptCur.y))
return FALSE;
return TRUE;
}
The following function ends the drag operation and draws the image in its final location. It also releases the mouse capture.
// StopDragging - ends a drag operation and draws the image
// at its final location.
// Returns TRUE if successful, or FALSE otherwise.
// hwnd - handle to the window in which the bitmap is dragged.
// himl - handle to the image list.
// ptCur - coordinates of the cursor.
//
// Global variable
// g_ptHotSpot - location of the image's hot spot.
extern POINT g_ptHotSpot;
BOOL StopDragging(HWND hwnd, HIMAGELIST himl, POINT ptCur)
{
ImageList_EndDrag();
ImageList_DragLeave(hwnd)
g_fDragging = FALSE;
DrawTheImage(hwnd, himl, ptCur.x - g_ptHotSpot.x,
ptCur.y - g_ptHotSpot.y);
ReleaseCapture();
return TRUE;
}
There are a number of functions that retrieve information from an image list. The ImageList_GetImageInfo function fills an IMAGEINFO structure with information about a single image, including the handles of the image and mask bitmaps, the number of color planes and bits per pixel, and the bounding rectangle of the image within the image bitmap. You can use this information to directly manipulate the bitmaps for the image. The ImageList_GetImageCount function retrieves the number of images in an image list.
Every image list includes a list of indexes to use as overlays. An overlay is an image that is drawn transparently over another image. Any image currently in the image list can be used as an overlay. You can specify up to four overlays per image list. This limit has been expanded to 15 in version 4.71.
You add the index of an image to the list of overlays by using the ImageList_SetOverlayImage function, specifying the handle to the image list, the index of the existing image, and the desired overlay index. This, in effect, tells the image list that "the image at index x can be used as an overlay, and I want to refer to the overlay as overlay index y." The overlay indexes are one-based rather than zero-based because an overlay index of zero means that no overlay will be used.
You specify an overlay when drawing an image with the ImageList_Draw or ImageList_DrawEx function. The overlay is specified by performing a logical OR operation between the desired drawing flags and the result of the INDEXTOOVERLAYMASK macro. The INDEXTOOVERLAYMASK macro takes the overlay index and formats it for inclusion with the flags for these functions. This will draw the image with the specified overlay. The following example demonstrates how an overlay is added and specified when drawing the image.
ImageList_SetOverlayImage(himl, 0, 3); ImageList_Draw(himl, 1, hdc, 0, 0, ILD_MASK | INDEXTOOVERLAYMASK(3));
This will draw image 1 and then overlay that image with image 0. Because 3 is the overlay index that you specified in the ImageList_SetOverlayImage call, 3 is placed in the INDEXTOOVERLAYMASK macro.
The following features were added to the image list by Microsoft® Internet Explorer.
This section contains information about the programming elements used with image lists.
| Macros |
| ImageList_AddIcon |
| ImageList_ExtractIcon |
| ImageList_LoadBitmap |
| ImageList_RemoveAll |
| INDEXTOOVERLAYMASK |
| Structures |
| IMAGEINFO |
| IMAGELISTDRAWPARAMS |
This section contains information about the functions used with image lists.
int ImageList_Add(
HIMAGELIST himl,
HBITMAP hbmImage,
HBITMAP hbmMask
);
Adds an image or images to an image list.
The ImageList_Add function copies the bitmap to an internal data structure. Be sure to use the DeleteObject function to delete hbmImage and hbmMask after the function returns.
int ImageList_AddMasked(
HIMAGELIST himl,
HBITMAP hbmImage,
COLORREF crMask
);
Adds an image or images to an image list, generating a mask from the specified bitmap.
The ImageList_AddMasked function copies the bitmap to an internal data structure. Be sure to use the DeleteObject function to delete hbmImage and crMask after the function returns.
BOOL ImageList_BeginDrag(
HIMAGELIST himlTrack,
int iTrack,
int dxHotspot,
int dyHotspot
);
Begins dragging an image.
This function creates a temporary image list that is used for dragging. In response to subsequent WM_MOUSEMOVE messages, you can move the drag image by using the ImageList_DragMove function. To end the drag operation, you can use the ImageList_EndDrag function.
BOOL ImageList_Copy(
HIMAGELIST himlDst,
int iDst,
HIMAGELIST himlSrc,
int iSrc,
UINT uFlags);
Copies images within a given image list.
| ILCF_MOVE | The source image is copied to the destination image's index. This operation results in multiple instances of a given image. |
| ILCF_SWAP | The source and destination images exchange positions within the image list. |
Version 4.70
HIMAGELIST ImageList_Create(
int cx,
int cy,
UINT flags,
int cInitial,
int cGrow
);
Creates a new image list.
| ILC_COLOR | Use the default behavior if none of the other ILC_COLOR* flags is specified. Typically, the default is ILC_COLOR4, but for older display drivers, the default is ILC_COLORDDB. |
| ILC_COLOR4 | Use a 4-bit (16-color) device-independent bitmap (DIB) section as the bitmap for the image list. |
| ILC_COLOR8 | Use an 8-bit DIB section. The colors used for the color table are the same colors as the halftone palette. |
| ILC_COLOR16 | Use a 16-bit (32/64k-color) DIB section. |
| ILC_COLOR24 | Use a 24-bit DIB section. |
| ILC_COLOR32 | Use a 32-bit DIB section. |
| ILC_COLORDDB | Use a device-dependent bitmap. |
| ILC_MASK | Use a mask. The image list contains two bitmaps, one of which is a monochrome bitmap used as a mask. If this value is not included, the image list contains only one bitmap. |
BOOL ImageList_Destroy(
HIMAGELIST himl
);
Destroys an image list.
BOOL ImageList_DragEnter(
HWND hwndLock,
int x,
int y
);
Locks updates to the specified window during a drag operation and displays the drag image at the specified position within the window.
To begin a drag operation, use the ImageList_BeginDrag function.
BOOL ImageList_DragLeave(
HWND hwndLock
);
Unlocks the specified window and hides the drag image, allowing the window to be updated.
BOOL ImageList_DragMove(
int x,
int y
);
Moves the image that is being dragged during a drag-and-drop operation. This function is typically called in response to a WM_MOUSEMOVE message.
To begin a drag operation, use the ImageList_BeginDrag function.
BOOL ImageList_DragShowNolock(
BOOL fShow
);
Shows or hides the image being dragged.
BOOL ImageList_Draw(
HIMAGELIST himl,
int i,
HDC hdcDst,
int x,
int y,
UINT fStyle
);
Draws an image list item in the specified device context.
| ILD_BLEND25, | |
| ILD_FOCUS | Draws the image, blending 25 percent with the system highlight color. This value has no effect if the image list does not contain a mask. |
| ILD_BLEND50, | |
| ILD_SELECTED, | |
| ILD_BLEND | Draws the image, blending 50 percent with the system highlight color. This value has no effect if the image list does not contain a mask. |
| ILD_MASK | Draws the mask. |
| ILD_NORMAL | Draws the image using the background color for the image list. If the background color is the CLR_NONE value, the image is drawn transparently using the mask. |
| ILD_TRANSPARENT | Draws the image transparently using the mask, regardless of the background color. This value has no effect if the image list does not contain a mask. |
An overlay image is drawn transparently over the primary image specified in the i parameter. To specify an overlay image in the fStyle parameter, use the INDEXTOOVERLAYMASK macro to shift the one-based index of the overlay image. Use the OR operator to logically combine the return value of the macro with the drawing style flags specified in the fStyle parameter. You must first specify this image as an overlay image by using the ImageList_SetOverlayImage function.
BOOL ImageList_DrawEx(
HIMAGELIST himl,
int i,
HDC hdcDst,
int x,
int y,
int dx,
int dy,
COLORREF rgbBk,
COLORREF rgbFg,
UINT fStyle
);
Draws an image list item in the specified device context. The function uses the specified drawing style and blends the image with the specified color.
| CLR_NONE | No background color. The image is drawn transparently. |
| CLR_DEFAULT | Default background color. The image is drawn using the background color of the image list. |
| CLR_NONE | No blend color. The image is blended with the color of the destination device context. |
| CLR_DEFAULT | Default foreground color. The image is drawn using the system highlight color as the foreground color. |
| ILD_BLEND25, | |
| ILD_FOCUS | Draws the image, blending 25 percent with the blend color specified by rgbFG. This value has no effect if the image list does not contain a mask. |
| ILD_BLEND50, | |
| ILD_SELECTED, | |
| ILD_BLEND | Draws the image, blending 50 percent with the blend color specified by rgbFG. This value has no effect if the image list does not contain a mask. |
| ILD_MASK | Draws the mask. |
| ILD_NORMAL | Draws the image using the background color for the image list. If the background color is the CLR_NONE value, the image is drawn transparently using the mask. |
| ILD_TRANSPARENT | Draws the image transparently using the mask, regardless of the background color. This value has no effect if the image list does not contain a mask. |
An overlay image is drawn transparently over the primary image specified in the i parameter. To specify an overlay image in the fStyle parameter, use the INDEXTOOVERLAYMASK macro to shift the one-based index of the overlay image. Use the OR operator to logically combine the return value of the macro with the drawing style flags specified in the fStyle parameter. You must first specify this image as an overlay image by using the ImageList_SetOverlayImage function.
BOOL ImageList_DrawIndirect(
IMAGELISTDRAWPARAMS* pimldp);
Draws an image list image based on an IMAGELISTDRAWPARAMS structure.
Version 4.70
HIMAGELIST ImageList_Duplicate(
HIMAGELIST himl);
Creates a duplicate of an existing image list.
Version 4.71
BOOL ImageList_EndDrag(VOID)
Ends a drag operation.
COLORREF ImageList_GetBkColor(
HIMAGELIST himl
);
Retrieves the current background color for an image list.
HIMAGELIST ImageList_GetDragImage(
POINT FAR *ppt,
POINT FAR *pptHotspot
);
Retrieves the temporary image list that is used for the drag image. The function also retrieves the current drag position and the offset of the drag image relative to the drag position.
The temporary image list is destroyed when the ImageList_EndDrag function is called. To begin a drag operation, use the ImageList_BeginDrag function.
HICON ImageList_GetIcon(
HIMAGELIST himl,
int i,
UINT flags
);
Creates an icon or cursor based on an image and mask in an image list.
BOOL ImageList_GetIconSize(
HIMAGELIST himl,
int FAR *cx,
int FAR *cy
);
Retrieves the dimensions of images in an image list. All images in an image list have the same dimensions.
int ImageList_GetImageCount(
HIMAGELIST himl
);
Retrieves the number of images in an image list.
BOOL ImageList_GetImageInfo(
HIMAGELIST himl,
int i,
IMAGEINFO FAR *pImageInfo
);
Retrieves information about an image.
HIMAGELIST ImageList_LoadImage(
HINSTANCE hi,
LPCTSTR lpbmp,
int cx,
int cGrow,
COLORREF crMask,
UINT uType,
UINT uFlags
);
Creates an image list from the specified bitmap, cursor, or icon resource.
If the uFlags parameter includes LR_LOADFROMFILE, lpbmp is the address of a null-terminated string that names the file containing the image to load.
If the hi parameter is non-NULL and LR_LOADFROMFILE is not specified, lpbmp is the address of a null-terminated string that contains the name of the image resource in the hi module.
If hi is NULL and LR_LOADFROMFILE is not specified, the low-order word of this parameter must be the identifier of an OEM image to load. To create this value, use the MAKEINTRESOURCE macro with one of the OEM image identifiers defined in WINUSER.H. These identifiers have the following prefixes:
| OBM_ for OEM bitmaps |
| OIC_ for OEM icons |
| OCR_ for OEM cursors |
| IMAGE_BITMAP | Loads a bitmap. |
| IMAGE_CURSOR | Loads a cursor. |
| IMAGE_ICON | Loads an icon. |
| LR_DEFAULTCOLOR | Uses the color format of the display. |
| LR_LOADDEFAULTSIZE | Uses the width or height specified by the system metric values for cursors and icons if the cx parameter is set to zero. If this value is not specified and cx is set to zero, the function sets the size to the one specified in the resource. If the resource contains multiple images, the function sets the size to that of the first image. |
| LR_LOADFROMFILE | Loads the image from the file specified by the lpbmp parameter. |
| LR_LOADMAP3DCOLORS | Searches the color table for the image and replaces the following shades of gray with the corresponding three-dimensional color (see the comments section at the end of this topic for more information):
Dk Gray: RGB(128, 128, 128)COLOR_3DSHADOW Gray: RGB(192, 192, 192)COLOR_3DFACE Lt Gray: RGB(223, 223, 223)COLOR_3DLIGHT |
| LR_LOADTRANSPARENT | Retrieves the color value of the first pixel in the image and replaces the corresponding entry in the color table with the default window color (the COLOR_WINDOW display color). All pixels in the image that use that color become the default window value color. This value applies only to images that have a corresponding color table. See the comments section at the end of this topic for more information. |
| LR_MONOCHROME | Loads the image in black and white. |
| LR_SHARED | Shares the image handle if the image is loaded multiple times. Do not use this value for images that have nontraditional sizes that might change after loading or for images that are loaded from a file. |
LR_LOADTRANSPARENT does not load the image transparently. It creates an opaque image list that only appears transparent because all of the "background" pixels have been changed to COLOR_WINDOW. If the images are drawn over a background that is not the color COLOR_WINDOW, the image will not draw properly. Also, LR_LOADTRANSPARENT and LR_LOADMAP3DCOLORS use the system colors that were in effect at the time that ImageList_LoadImage was called. If the system colors subsequently change, the application must reload the image to remap the colors.
See also LoadImage
HIMAGELIST ImageList_Merge(
HIMAGELIST himl1,
int i1,
HIMAGELIST himl2,
int i2,
int dx,
int dy
);
Creates a new image by combining two existing images. The function also creates a new image list in which to store the image.
The new image consists of the second existing image drawn transparently over the first. The mask for the new image is the result of performing a logical OR operation on the masks of the two existing images.
HIMAGELIST ImageList_Read(
LPSTREAM pstm
);
Reads an image list from a stream.
BOOL ImageList_Remove(
HIMAGELIST himl,
int i
);
Removes an image from an image list.
When an image is removed, the indexes of the remaining images are adjusted so that the image indexes always range from zero to one less than the number of images in the image list. For example, if you remove the image at index 0, then image 1 becomes image 0, image 2 becomes image 1, and so on.
See also ImageList_RemoveAll
BOOL ImageList_Replace(
HIMAGELIST himl,
int i,
HBITMAP hbmImage,
HBITMAP hbmMask
);
Replaces an image in an image list with a new image.
The ImageList_Replace function copies the bitmap to an internal data structure. Be sure to use the DeleteObject function to delete hbmImage and hbmMask after the function returns.
int ImageList_ReplaceIcon(
HIMAGELIST himl,
int i,
HICON hicon
);
Replaces an image with an icon or cursor.
Because the system does not save hicon, you can destroy it after the function returns if the icon or cursor was created by the CreateIcon function. You do not need to destroy hicon if it was loaded by the LoadIcon function; the system automatically frees an icon resource when it is no longer needed.
COLORREF ImageList_SetBkColor(
HIMAGELIST himl,
COLORREF clrBk
);
Sets the background color for an image list.
BOOL ImageList_SetDragCursorImage(
HIMAGELIST himlDrag,
int iDrag,
int dxHotspot,
int dyHotspot
);
Creates a new drag image by combining the specified image (typically a mouse cursor image) with the current drag image.
BOOL ImageList_SetIconSize(
HIMAGELIST himl,
int cx,
int cy
);
Sets the dimensions of images in an image list and removes all images from the list.
BOOL ImageList_SetImageCount(
HIMAGELIST himl,
UINT uNewCount);
Resizes an existing image list.
If an application expands an image list with this function, it must add new images by using the ImageList_Replace function. If your application does not add valid images at the new indexes, draw operations that use the new indexes will be unpredictable.
If you decrease the size of an image list by using this function, the truncated images are freed.
Version 4.70
BOOL ImageList_SetOverlayImage(
HIMAGELIST himl,
int iImage,
int iOverlay
);
Adds a specified image to the list of images to be used as overlay masks. An image list can have up to four overlay masks in version 4.70 and earlier and up to 15 in version 4.71. The function assigns an overlay mask index to the specified image.
An overlay mask is an image drawn transparently over another image. To draw an overlay mask over an image, call the ImageList_Draw or ImageList_DrawEx function. The fStyle parameter of these functions can use the INDEXTOOVERLAYMASK macro to specify an overlay mask index.
BOOL ImageList_Write(
HIMAGELIST himl,
LPSTREAM pstm
);
Writes an image list to a stream.
This section contains information about the macros used with image lists.
int ImageList_AddIcon(
HIMAGELIST himl,
HICON hicon
);
Adds an icon or cursor to an image list. ImageList_AddIcon calls the ImageList_ReplaceIcon function.
Because the system does not save hicon, you can destroy it after the macro returns if the icon or cursor was created by the CreateIcon function. You do not need to destroy hicon if it was loaded by the LoadIcon function; the system automatically frees an icon resource when it is no longer needed.
The ImageList_AddIcon macro is defined as follows:
#define ImageList_AddIcon(himl, hicon) ImageList_ReplaceIcon(himl, -1, hicon)
HICON ImageList_ExtractIcon(
HINSTANCE hi,
HIMAGELIST himl,
int i
);
Calls the ImageList_GetIcon function to create an icon or cursor based on an image and mask in an image list.
HIMAGELIST ImageList_LoadBitmap(
HINSTANCE hi,
LPCTSTR lpbmp,
int cx,
int cGrow,
COLORREF crMask
);
Calls the ImageList_LoadImage function to create an image list from the specified bitmap resource.
BOOL ImageList_Remove(
HIMAGELIST himl
);
Calls the ImageList_Remove function to remove all of the images from an image list.
UINT INDEXTOOVERLAYMASK(
UINT iOverlay
);
Prepares the index of an overlay mask so that the ImageList_Draw function can use it.
The INDEXTOOVERLAYMASK macro is defined as follows:
#define INDEXTOOVERLAYMASK(i) ((i) << 8)
This section contains information about the structures used with image lists.
typedef struct _IMAGEINFO {
HBITMAP hbmImage;
HBITMAP hbmMask;
int Unused1;
int Unused2;
RECT rcImage;
} IMAGEINFO, FAR *LPIMAGEINFO;
Contains information about an image in an image list. This structure is used with the ImageList_GetImageInfo function.
typedef struct _IMAGELISTDRAWPARAMS {
DWORD cbSize;
HIMAGELIST himl;
int i;
HDC hdcDst;
int x;
int y;
int cx;
int cy;
int xBitmap;
int yBitmap;
COLORREF rgbBk;
COLORREF rgbFg;
UINT fStyle;
DWORD dwRop;
} IMAGELISTDRAWPARAMS, FAR * LPIMAGELISTDRAWPARAMS;
Contains information about an image list draw operation and is used with the ImageList_DrawIndirect function.
| CLR_DEFAULT | Default background color. The image is drawn using the image list background color. |
| CLR_NONE | No background color. The image is drawn transparently. |
This parameter is used only if the image list identified by himl was created with the ILC_MASK value.
| CLR_DEFAULT | Default foreground color. The image is drawn using the system highlight color as the foreground color. |
| CLR_NONE | No blend color. The image is blended with the color of the destination device context. |
This parameter is used only if fStyle includes the ILD_BLEND25 or ILD_BLEND50 flag.
Some common raster operation codes include:
| BLACKNESS | Fills the destination rectangle using the color associated with index zero in the physical palette. (This color is black for the default physical palette.) |
| DSTINVERT | Inverts the destination rectangle. |
| MERGECOPY | Merges the source rectangle colors with the specified pattern by using the Boolean AND operator. |
| MERGEPAINT | Merges the inverted source rectangle colors with the destination rectangle colors by using the Boolean OR operator. |
| NOTSRCCOPY | Copies the inverted source rectangle to the destination. |
| NOTSRCERASE | Combines the source and destination rectangle colors by using the Boolean OR operator. Inverts the resultant color. |
| PATCOPY | Copies the specified pattern into the destination bitmap. |
| PATINVERT | Combines the specified pattern colors with the destination rectangle colors by using the Boolean XOR operator. |
| PATPAINT | Combines the pattern colors with the inverted source rectangle colors by using the Boolean OR operator. Combines the result with the destination rectangle colors by using the Boolean OR operator. |
| SRCAND | Combines the source and destination rectangle colors by using the Boolean AND operator. |
| SRCCOPY | Copies the source rectangle directly to the destination rectangle. |
| SRCERASE | Combines the destination rectangle's inverted colors with the source rectangle colors by using the Boolean AND operator. |
| SRCINVERT | Combines the source and destination rectangle colors by using the Boolean XOR operator. |
| SRCPAINT | Combines the source and destination rectangle colors by using the Boolean OR operator. |
| WHITENESS | Fills the destination rectangle using the color associated with index one in the physical palette. (This color is white for the default physical palette.) |
An overlay image is an image that is drawn on top of the primary image specified in the i member of this structure. To specify an overlay image, logically OR the fStyle member with the INDEXTOOVERLAYMASK macro, passing the one-based index of the overlay image in the macro. This image must have been previously specified as an overlay image using the ImageList_SetOverlayImage API.
To extract the overlay image from the fStyle member, logically AND fStyle with the ILD_OVERLAYMASK value.
Version 4.70
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.