The system uses icons throughout the user interface to represent objects such as files, folders, shortcuts, applications, and documents. The icon functions enable applications to create, load, display, arrange, animate, and destroy icons. For information on specifying icons for file types, see ExtractIcon.
This overview provides information on the following topics:
- Icon Hot Spot
- Icon Types
- Icon Sizes
- Icon Creation
- Icon Display
- Icon Destruction
- Icon Duplication
Icon Hot Spot
One of the pixels in an icon is designated as the hot spot, which is the point the system tracks and recognizes as the position of the icon. An icon's hot spot is typically the pixel located at the center of the icon. If you use the CreateIconIndirect function to create an icon, you can specify any pixel to be the hot spot.
The operating system provides a set of standard icons that are available for any application to use at any time. The software development kit (SDK) header files contain identifiers for the standard icons—the identifiers begin with the IDI_ prefix.
Each standard icon has a corresponding default image associated with it. The user can replace the default image associated with any standard cursor at any time.
Custom icons are designed for use in a particular application and can be any design. Following are several custom icons.
The system uses four icon sizes:
- System small
- System large
- Shell small
- Shell large
The system small icon is displayed in the window caption.
To change the size of the system small icon
- From Control Panel, click Display, then click the Appearance tab.
- Select Caption Buttons from the Item list, then set the Size field.
To retrieve the size of the system small icon
- Call the GetSystemMetrics function with SM_CXSMICON and SM_CYSMICON.
The system large icon is mainly used by applications, but it is also displayed in the Alt+Tab dialog. The CreateIconFromResource, DrawIcon, ExtractAssociatedIcon, ExtractIcon, ExtractIconEx, and LoadIcon functions all use system large icons. The size of the system large icon is defined by the video driver, therefore it cannot be changed.
To retrieve the size of the system large icon
- Call GetSystemMetrics with SM_CXICON and SM_CYICON.
The shell small icon is used in the Windows Explorer and the common dialogs. Currently, this defaults to the system small size.
To retrieve the size of the shell small icon
- Use the SHGetFileInfo function with
SHGFI_SHELLICONSIZE | SHGFI_SMALLICONto retrieve a handle to the system image list.
- Then call the ImageList_GetIconSize function to get the icon size.
The shell large icon is used on the desktop.
To change the size of the large icon
- From Control Panel , click Display, then click the Appearance tab,
- Select Icon from the Item list, then set the Size field (this size is stored in the registry, under HKEY_CURRENT_USER\Control Panel, Desktop\WindowMetrics\Shell Icon Size).
- Click the Plus! tab and then select the Use Large Icons check box.
To retrieve the size of the shell large icon
- Use the SHGetFileInfo function with SHGFI_SHELLICONSIZE to retrieve a handle to the system image list.
- Then call the ImageList_GetIconSize function to get the icon size.
The Start menu uses either shell small icons or shell large icons, depending on whether the Use Large Icons check box is selected.
Your application should supply groups of icon images in the following sizes:
- 48x48, 256 color
- 32x32, 16 color
- 16x16 pixels, 16 color
When filling in the WNDCLASSEX structure to be used in registering your window class, set the hIcon member to the 32x32 icon and the hIconSm member to the 16x16 icon. For more information about class icons, see Class Icons.
Standard icons are predefined, so it is not necessary to create them. To use a standard icon, an application can obtain its handle by using the LoadImage function. An icon handle is a unique value of the HICON type that identifies a standard or custom icon.
To create a custom icon for an application, you would typically use a graphics application and include the ICON Resource in the application's resource-definition file. At run-time, you can call LoadIcon or LoadImage to retrieve a handle to the icon. An icon resource can contain a group of images for several different display devices. LoadIcon and LoadImage automatically select the most appropriate icon from the group for the current display device.
An application can also create a custom icon at run-time by using the CreateIconIndirect function, which creates an icon based on the contents of an ICONINFO structure. The GetIconInfo function fills the structure with the hot-spot coordinates and information about the bitmask bitmap and color bitmap for the icon.
Applications should implement custom icons as resources and should use LoadIcon or LoadImage, rather than create the icon at run-time. Using icon resources avoids device dependence, simplifies localization, and enables applications to share icon shapes.
The CreateIconFromResourceEx function enables an application to browse through the system's resources and create icons and cursors based on resource data. CreateIconFromResourceEx creates an icon based on binary resource data from other executable files or DLLs. An application must precede this function with calls to the LookupIconIdFromDirectoryEx function and several of the resource functions. LookupIconIdFromDirectoryEx returns the identifier of the most appropriate icon data for the current display device.
You can retrieve the image for an icon by using the GetIconInfo function, and can draw it by using the DrawIconEx function. To draw the default image for a icon, specify the DI_COMPAT flag in the call to DrawIconEx. If you do not specify the DI_COMPAT flag, DrawIconEx draws the icon using the image that the user specified.
When the system displays an icon, it must extract the appropriate icon image from the .exe or .dll file. The system uses the following steps to select the icon image:
- Select the RT_GROUP_ICON resource. If more than one such resource exists, the system uses the first resource listed in the resource scrip.
- Select the appropriate RT_ICON image from the RT_GROUP_ICON resource. If more than one image exists, the system uses the following criteria to choose an image:
- The image closest in size to the requested size is chosen.
- If two or more images of that size are present, the one that matches the color depth of the display is chosen.
- If no images exactly match the color depth of the display, the image with the greatest color depth that does not exceed the color depth of the display is chosen. If all exceed the color depth, the one with the lowest color depth is chosen.
The system treats all color depths of 8 or more bpp as equal. Therefore, there is no advantage of including a 16x16 256-color image and a 16x16 16-color image in the same resource—the system will simply choose the first one it encounters. When the display is in 8-bpp mode, the system will choose a 16-color icon over a 256-color icon, and will display all icons using the system default palette.
To display an animated icon, use a static control as shown in the following code fragment.
hIcon = LoadImage(NULL, "ico.ani", IMAGE_ICON, 0, 0, LR_LOADFROMFILE); SendMessage( hStatic, STM_SETIMAGE, IMAGE_ICON, (LPARAM)(UINT)hIcon);
When an application no longer needs an icon it created by using the CreateIconIndirect function, it should destroy the icon. The DestroyIcon function destroys the icon handle and frees any memory used by the icon. Applications should use this function only for icons created with CreateIconIndirect; it is not necessary to destroy other icons.
The CopyIcon function copies an icon handle. This enables an application or DLL to get its own handle to an icon owned by another module. Then, if the other module is freed, the application that copied the icon will still be able to use the icon.
The CopyImage function creates a new icon based on the specified source icon. The new icon can be larger or smaller than the source icon.
For information about adding, removing, or replacing icon resources in executable (.exe) files, see Resources.
The DuplicateIcon function makes an actual copy of the icon.