Image list

Image Lists

Image List 是同样大小的图片集合，每个图片通过索引引用。
Image Lists 被用来高效管理大量图标和位图。
在Image List中的所有图片被包含 单个，宽位图以screen device 格式。
一个Image list同样可以包含单色位图，这些位图中包含掩码，被用来透明的绘画图片(icon style)。

Using Image Lists
Image List Updates in Internet Explorer
Image List Reference

Using Image Lists
The Microsoft Win32 application programming interface (API)提供image list 函数,使用这些函数让你创建和销毁image lists,添加，删除图片，代替合并图片，绘制图片和拖动图片

为了使用image list函数，应该包含通用控件头文件，和连接到通用控件的导出库.另外，在调用image list函数之前，使用InitCommonControls函数来确保通用控件动态连接库被加载了.

Types
这里有两种类型的image lists:有掩码的和无掩码的.nonmasked image list由一个色彩位图组成，它包含一个或多个图片。 masked image list由两个等大的位图组成，一个是色彩位图，它包含图片，另一个是一个单色位图，它包含一系列掩码---每一个对应第一个位图中的图片.

当nonmasked image list被绘制时，它只是简单的被复制到目标device context;也就是说，他以覆盖原来device context的背景色的方式来绘制。当masked image被绘制时，这些图片的位和掩码的位组合，在位图中产生透明的区域，在那里目标背景色就被显示出来了。有不同种绘制方式，你能通过指定这些当绘制一个masked image。For example, you can specify that the image be dithered to indicate a selected object.

Creating and Destroying Image Lists

通过调用ImageList_Create来创建image list.参数包括创建image list的类型，每个图片的尺寸，你想添加到image list中的image数目。对nonmasked image list来说,函数创建一个单个位图，大的足以保存指定数目的固定尺寸图片。然后他创建一个屏幕相关 device context 和将位图选入list中。对masked image list
来说，函数创建俩个位图和两个屏幕相关device contexts。他将图片选进一个device context，将mask bitmap选进另一个。通用控件dll包含这个image list 函数的执行代码。

在ImageList_Create，中你可指定初始化image list中image的数目，同时也可指定增长的数目。因此，如果你想增加更多图片比你在开始时指定的数目大。image list 就自动增长根据相应新的图片。

如果ImageList_Create成功，他返回一个HIMAGELIST的handle,你使用这个handle在别的image list函数中访问和管理images.你可以增加和删除images，从另一个image list中复制一个image到别的中去,也可以合并不同image list的中的images。当你不在需要image list时，你可以销毁它通过指定handle在ImageList_Destroy函数中.

下面的代码创建一个masked image list 然后使用ImageList_AddIcon函数增加两个Icons到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;
 }

Adding and Removing Images
   你可以增加bitmapped images,icon,或者cursors到image list中。你可以通过指定两个bitmap的handle调用ImageList_Add函数来增加图片.第一bitmap包含一个或两个images，第二个bitmap包含增加到mask bitmap中的mask.对nonmasked image lists来说,第二个bitmap handle被忽略；他可以设置为NULL。

   ImageList_AddMasked 函数增加bitmapped images 到masked image list.这个函数同ImageList_Add相似，除了你不需要指定mask bitmap。的确，你可以指定一个系统组合image bitmap的color来产生masks.每个指定color的像素在image bitmap中被转换为黑色，然后相应的位在mask中被设为1。结果，在image 中的任何匹配指定color的像素是透明的当image被绘制时。
   ImageList_AddIcon函数增加icon或cursor到image list。如果image list是masked,ImageList_AddIcon增加icon或cursor提供的mask到mask bitmap。如果image list是nonmasked,icon或cursor的mask不会被使用。
   你可以创建一个icon基于image 和mask在image list 中，通过使用ImageList_GetIcon,这个函数返回一个新的handle到新的图片。

   ImageList_Add, ImageList_AddMasked,和 ImageList_AddIcon为每一个图片给一个索引当他增加图片到image list中。索引是基于0开始的；也就是说，一个图片的索引是0,第二个是1,如此来推。增加一个image 后，函数返回图片的索引。当两个或多个图片被添加时，函数返回第一个图片的索引。

   ImageList_Remove移出一个图片从image list中.

Replacing and Merging Images
   ImageList_Replace 和ImageList_ReplaceIcon代替一个image list中的一个图片。ImageList_Replace 代替一个是bitmapped iamge 和mask的图片，而ImageList_ReplaceIcon用icon或cursor来代替一个image。

   ImageList_Merge合并两个images,存储新的image到新的image list中。新的image通过第二个
透明绘制第一来创建。新的image的mask是两个存在mask的or运算.

Drawing Images
    为了绘制一个image,你使用ImageList_Draw或ImageList_DrawEx。你可以指定image list的handle,和要绘制的image的索引,指向目标device context的handle,device context中的位置,和一个或多个style.

    当你指定ILD_TRANSPARENT风格时，ImageList_Draw(Ex)使用两步处理masked image。第一，他执行 AND操作，使image的bit和mask的bit相互AND.然后执行XOR在第一操作的结果上和目标device context 的背景.
这个处理创建一个透明的区域在结果image，也就是每个白色位在mask 引起相应的位在结果中变成透明。

    在绘制一个masked image在solid color背景上前，你应该使用ImageList_SetBkColor函数来设置image list的背景色和目标一样的颜色。设置颜色消除了在image中创建透明区域的需要，使ImageList_Draw(Ex)简单的复制图片到目标device context。导致性能的增加。要绘制一个image,使用ILD_NORMAL风格来调用ImageList_Draw(Ex).

   你能设置背景色为masked image list在任何时候，因此他能正确的绘制在任何solid 背景。设置背景色为CLR_NONE引起被画的图片透明的绘制。为了取得image list的背景色，使用ImageList_GetBkColor
  
   ILD_BLEND25  ILD_BLEND50风格混摇图片和系统的高亮色。这些风格是有用的如果你使用一个maksed image 来表示用户可以选择的对象。例如,你使用ILD_BLEND50来绘制一个图片，当用户选择它时。

   一个nonmasked image 被复制到目的device context 使用SRCCOPY而不是其他操作。在image中的颜色，同样显示无论device context的背景色。在ImageList_Draw(Ex)中指定的绘制风格没有效果在nonmasked image上。

Drawing the image

下面的函数绘制一个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;
 }
Dragging Images
    Win32 API 包括在屏幕上拖动图片的函数。拖动函数移动一个图片不会导致光标闪烁。masked 和unmasked images都能被拖动。

    ImageList_BeginDrag函数开始拖动操作。参数包括image lis handle,要拖动image的索引和在图片中的
hot spot的位置。hot spot是一个简单的像素，拖动函数认为图片的屏幕位置。一般来说，应用程序设置hot spot来一致鼠标的hot spot.ImageList_DragMove移动image到新位置
    ImageList_DragEnter函数设置在窗口内拖动图片的初始位置，和绘制图片的位置。参数包括绘制窗口的handle和窗口内初始位置。坐标相对与窗口的左上，不是客户区。这对于所有图片拖动函数都是一样的。这就意味着你要补偿窗口元素的宽度例如边框，标题栏，和菜单栏挡指定坐标时。如果你指定一个NULL，为window handle当调用ImageList_DragEnter,这个拖动函数绘制图片在桌面窗口的device context，坐标相对于屏幕的左上角。

    ImageList_DragEnter锁住所有给窗口的更新操作.如果你需要在拖动的时候做别的事,就像高亮操作目标,你能临时的隐藏配拖动的图片使用ImageList_DragLeave函数.另一个方法是使用GetDCEx函数使用DCX_LOCKWINDOWUPDATE来相关一个device context允许你绘画.要小心,不要删除被拖动的图片.

    ImageList_SetDragCursorImage通过组合已给的图片和当前的拖动图片创建一个新的图片.因为拖动函数使用这个新图片在拖动期间,你必须使用ShowCursor函数来隐藏实际鼠标的光标在调用ImageList_SetDragCursorImage.否则,系统可能显示两个鼠标光标在拖动期间.

    当程序调用ImageList_BeginDrag,系统创建一个临时,内部image list 然后复制指定要拖动的图片到这个内部image list.你能取得这个临时的image list使用ImageList_GetDragImage函数,函数取得当前拖动的位置和相对开始推动时的距离.

Beginning the drag operation
   下面的函数被调用来负责响应鼠标按下的消息,向WM_LBUTTONDOWN.函数决定用户是否在图片的边界内单击图片.如果是,函数捕获鼠标的输入,擦去在客户区的图片,为hot spot 计算位置.函数设置hot spot来使鼠标的hot spot一致.然后函数开始拖动操作通过调用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;
 }

 

 

Moving the image
下面函数来拖动图片到一个新地方,在WM_MOUSEMOVE消息中调用.
 // 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;
 }

Ending the drag operation
下面函数结束拖动操作,绘制这个图片在最终的位置,释放鼠标捕获
// 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;
 }

Image Information
这里有很多函数来取得image list的信息.ImageList_GetImageInfo用单个图片的信息填充一个IMAGEINFO结
构,包括image的handle和mask bitmaps的handle,color planes的数目,每像素的位,image 的边界矩形.你能使用这些信息操作这个image 的bitmaps.ImageList_GetImageCount返回list中的image 数目.