The ICO File
An Icon file, which usually has the ICO extension, contains one icon resource. Given that an icon resource can contain multiple images, it is no surprise that the file begins with an icon directory:
typedef struct
{
WORD idReserved; // Reserved (must be 0)
WORD idType; // Resource Type (1 for icons)
WORD idCount; // How many images?
ICONDIRENTRY idEntries[1]; // An entry for each image (idCount of 'em)
} ICONDIR, *LPICONDIR;
The idCount member indicates how many images are present in the icon resource. The size of the idEntries array is determined by idCount. There exists one ICONDIRENTRY for each icon image in the file, providing details about its location in the file, size and color depth. The ICONDIRENTRY structure is defined as:
typedef struct
{
BYTE bWidth; // Width, in pixels, of the image
BYTE bHeight; // Height, in pixels, of the image
BYTE bColorCount; // Number of colors in image (0 if >=8bpp)
BYTE bReserved; // Reserved ( must be 0)
WORD wPlanes; // Color Planes
WORD wBitCount; // Bits per pixel
DWORD dwBytesInRes; // How many bytes in this resource?
DWORD dwImageOffset; // Where in the file is this image?
} ICONDIRENTRY, *LPICONDIRENTRY;
For each ICONDIRENTRY, the file contains an icon image. The dwBytesInRes member indicates the size of the image data. This image data can be found dwImageOffset bytes from the beginning of the file, and is stored in the following format:
typdef struct
{
BITMAPINFOHEADER icHeader; // DIB header
RGBQUAD icColors[1]; // Color table
BYTE icXOR[1]; // DIB bits for XOR mask
BYTE icAND[1]; // DIB bits for AND mask
} ICONIMAGE, *LPICONIMAGE;
The icHeader member has the form of a DIB BITMAPINFOHEADER. Only the following members are used: biSize, biWidth, biHeight, biPlanes, biBitCount, biSizeImage. All other members must be 0. The biHeight member specifies the combined height of the XOR and AND masks. The members of icHeader define the contents and sizes of the other elements of the ICONIMAGE structure in the same way that the BITMAPINFOHEADER structure defines a CF_DIB format DIB.
The icColors member is an array of RGBQUADs. The number of elements in this array is determined by examining the icHeader member.
The icXOR member contains the DIB bits for the XOR mask of the image. The number of bytes in this array is determined by examining the icHeader member. The XOR mask is the color portion of the image and is applied to the destination using the XOR operation after the application of the AND mask.
The icAND member contains the bits for the monochrome AND mask. The number of bytes in this array is determined by examining the icHeader member, and assuming 1bpp. The dimensions of this bitmap must be the same as the dimensions of the XOR mask. The AND mask is applied to the destination using the AND operation, to preserve or remove destination pixels before applying the XOR mask.
Note The biHeight member of the icHeader structure represents the combined height of the XOR and AND masks. Remember to divide this number by two before using it to perform calculations for either of the XOR or AND masks. Also remember that the AND mask is a monochrome DIB, with a color depth of 1 bpp.
The following is an incomplete code fragment for reading an .ICO file:
// We need an ICONDIR to hold the data
pIconDir = malloc( sizeof( ICONDIR ) );
// Read the Reserved word
ReadFile( hFile, &(pIconDir->idReserved), sizeof( WORD ), &dwBytesRead, NULL );
// Read the Type word - make sure it is 1 for icons
ReadFile( hFile, &(pIconDir->idType), sizeof( WORD ), &dwBytesRead, NULL );
// Read the count - how many images in this file?
ReadFile( hFile, &(pIconDir->idCount), sizeof( WORD ), &dwBytesRead, NULL );
// Reallocate IconDir so that idEntries has enough room for idCount elements
pIconDir = realloc( pIconDir, ( sizeof( WORD ) * 3 ) +
( sizeof( ICONDIRENTRY ) * pIconDir->idCount ) );
// Read the ICONDIRENTRY elements
ReadFile( hFile, pIconDir->idEntries, pIconDir->idCount * sizeof(ICONDIRENTRY),
&dwBytesRead, NULL );
// Loop through and read in each image
for(i=0;i<pIconDir->idCount;i++)
{
// Allocate memory to hold the image
pIconImage = malloc( pIconDir->idEntries.dwBytesInRes );
// Seek to the location in the file that has the image
SetFilePointer( hFile, pIconDir->idEntries.dwImageOffset,
NULL, FILE_BEGIN );
// Read the image data
ReadFile( hFile, pIconImage, pIconDir->idEntries.dwBytesInRes,
&dwBytesRead, NULL );
// Here, pIconImage is an ICONIMAGE structure. Party on it :)
// Then, free the associated memory
free( pIconImage );
}
// Clean up the ICONDIR memory
free( pIconDir );
Complete code can be found in the Icons.C module of IconPro, in a function named ReadIconFromICOFile.
DLL and EXE Files
Icons can also be stored in .DLL and .EXE files. The structures used to store icon images in .EXE and .DLL files differ only slightly from those used in .ICO files.
Analogous to the ICONDIR data in the ICO file is the RT_GROUP_ICON resource. In fact, one RT_GROUP_ICON resource is created for each ICO file bound to the EXE or DLL with the resource compiler/linker. The RT_GROUP_ICON resource is simply a GRPICONDIR structure:
// #pragmas are used here to insure that the structure's
// packing in memory matches the packing of the EXE or DLL.
#pragma pack( push )
#pragma pack( 2 )
typedef struct
{
WORD idReserved; // Reserved (must be 0)
WORD idType; // Resource type (1 for icons)
WORD idCount; // How many images?
GRPICONDIRENTRY idEntries[1]; // The entries for each image
} GRPICONDIR, *LPGRPICONDIR;
#pragma pack( pop )
The idCount member indicates how many images are present in the icon resource. The size of the idEntries array is determined by idCount. There exists one GRPICONDIRENTRY for each icon image in the resource, providing details about its size and color depth. The GRPICONDIRENTRY structure is defined as:
#pragma pack( push )
#pragma pack( 2 )
typedef struct
{
BYTE bWidth; // Width, in pixels, of the image
BYTE bHeight; // Height, in pixels, of the image
BYTE bColorCount; // Number of colors in image (0 if >=8bpp)
BYTE bReserved; // Reserved
WORD wPlanes; // Color Planes
WORD wBitCount; // Bits per pixel
DWORD dwBytesInRes; // how many bytes in this resource?
WORD nID; // the ID
} GRPICONDIRENTRY, *LPGRPICONDIRENTRY;
#pragma pack( pop )
The dwBytesInRes member indicates the total size of the RT_ICON resource referenced by the nID member. nID is the RT_ICON identifier that can be passed to FindResource, LoadResource and LockResource to obtain a pointer to the ICONIMAGE structure (defined above) for this image.
The following is an incomplete code fragment for reading icons from a .DLL or .EXE file:
// Load the DLL/EXE without executing its code
hLib = LoadLibraryEx( szFileName, NULL, LOAD_LIBRARY_AS_DATAFILE );
// Find the group resource which lists its images
hRsrc = FindResource( hLib, MAKEINTRESOURCE( nId ), RT_GROUP_ICON );
// Load and Lock to get a pointer to a GRPICONDIR
hGlobal = LoadResource( hLib, hRsrc );
lpGrpIconDir = LockResource( hGlobal );
// Using an ID from the group, Find, Load and Lock the RT_ICON
hRsrc = FindResource( hLib, MAKEINTRESOURCE( lpGrpIconDir->idEntries[0].nID ), RT_ICON );
hGlobal = LoadResource( hLib, hRsrc );
lpIconImage = LockResource( hGlobal );
// Here, lpIconImage points to an ICONIMAGE structure
Complete code can be found in the Icons.C module of IconPro, in a function named ReadIconFromEXEFile.
In Memory
When dealing with icon resources in memory, the format is identical to the format used in .EXE and .DLL files. APIs such as CreateIconFromResource expect to be passed an ICONIMAGE structure. This is very convenient since FindResource, LoadResource and LockResource can be used to load the RT_ICON resource in that format.
An HICON handle is a handle to a single icon image, or RT_ICON resource. In previous versions of Windows, the size of an HICON image could be determined by calling GetSystemMetrics with the SM_CYICON and SM_CXICON flags. It is now possible, however, to have HICON handles for icons with non-standard sizes. HICON icons always have the same color format as the display device. See the discussion of APIs below for more details on how to handle icons of different sizes and color depths using HICON handles.
When in Windows
In Windows, the system maintains the concept of two sizes of icons, small and large. Further, the shell also has a concept of small and large icons. This means that in total, Windows is aware of four different icon sizes—System Small, System Large, Shell Small, and Shell Large.
The System Small size is derived from the size of window captions. The caption size can be adjusted from the "Appearance" tab in the Display Properties dialog. Adjustments made to the caption size are immediately reflected in the System Small icon size. The System Small size can be queried by calling GetSystemMetrics with the SM_CXSMICON and SM_CYSMICON parameters.
The System Large size is defined by the video driver and therefore cannot be changed dynamically. The System Large size can be queried by calling GetSystemMetrics with the SM_CXICON and SM_CYICON parameters.
The Shell Small size is defined by Windows, and currently Windows does not support changing this value, nor is there currently a direct way to query this value.
The Shell Large size is stored in the registry under the following key:
HKEY_CURRENT_USER\Control Panel\desktop\WindowMetrics\Shell Icon Size
The Shell Large size can be changed by modifying the registry or from the "Appearance" tab in the Display Properties dialog, which allows values from 16 to 72. Following is an example of code that can be used to change the Shell Large icon size by accessing the registry:
DWORD SetShellLargeIconSize( DWORD dwNewSize )
{
#define MAX_LENGTH 512
DWORD dwOldSize, dwLength = MAX_LENGTH, dwType = REG_SZ;
TCHAR szBuffer[MAX_LENGTH];
HKEY hKey;
// Get the Key
RegOpenKey( HKEY_CURRENT_USER, "Control Panel\\desktop\\WindowMetrics", &hKey);
// Save the last size
RegQueryValueEx( hKey, "Shell Icon Size", NULL, &dwType, szBuffer, &dwLength );
dwOldSize = atol( szBuffer );
// We will allow only values >=16 and <=72
if( (dwNewSize>=16) || (dwNewSize<=72) )
{
wsprintf( szBuffer, "%d", dwNewSize );
RegSetValueEx( hKey, "Shell Icon Size", 0, REG_SZ, szBuffer, lstrlen(szBuffer) + 1 );
}
// Clean up
RegCloseKey( hKey );
// Let everyone know that things changed
SendMessage( HWND_BROADCAST, WM_SETTINGCHANGE, SPI_SETICONMETRICS,
(LPARAM)("WindowMetrics") );
return dwOldSize;
#undef MAX_LENGTH
}
Choosing an Icon
When Windows prepares to display an icon, a desktop shortcut for example, it must parse the .EXE or .DLL file and extract the appropriate icon image. This selection is a two step process starting with the selection of the appropriate RT_GROUP_ICON resource, and ending with the selection of the proper RT_ICON image from that RT_GROUP_ICON.
Which Icon?
If an .EXE or .DLL file has only one RT_GROUP_ICON resource, the first step is trivial; Windows simply uses that resource. However, if more than one such group resource exists in the file, Windows must decide which one to use. Windows NT simply chooses the first resource listed in the application's RC script. On the other hand, Windows 95's algorithm is to choose the alphabetically first named group icon if one exists. If one such group resource does not exist, Windows chooses the icon with the numerically lowest identifier. So, to be sure that a particular icon is used for an application, the developer should insure that both of the following criteria are met:
The icon is placed before all other icons in the RC file.
If the icon is named, its name is alphabetically before any other named icon, otherwise its resource identifier is numerically smaller than any other icon.
Which Image?
Once an RT_GROUP_ICON is chosen, the individual icon image, or RT_ICON resource, must be selected and extracted. Again, if there exists only one RT_ICON resource for the group in question, the choice is trivial. However, if multiple images are present in the group, the following selection rules are applied:
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 none exactly match the color depth of the display, Windows chooses the image with the greatest color depth without exceeding the color depth of the display.
If all the size-matched images exceed the color depth of the display, the one with the lowest color depth is chosen.
Windows treats all color depths of 8 or more bpp as equal. For example, it is pointless to have a 16x16 256 color image and a 16x16 16bpp image in the same resource—Windows will simply choose the first one it encounters.
When the display is in 8bpp mode, Windows will prefer a 16 color icon over a 256 color icon, and will display all icons using the system default palette.
APIs
When dealing with icons, the developer can choose to manipulate the raw resource bytes, or let Windows handle the low level details and simply use HICON handles. The advantage of handling the raw resource bytes is a gain in control, while the advantage of using the HICON handles is that of simplicity. For most purposes, the HICON interface is sufficient—it is likely that handling the raw resource bytes will be necessary only in the development of an icon handling program.
Raw Resource Bytes
The standard Windows API functions for manipulating resources—FindResource, LoadResource and LockResource—can, of course, be used to handle icon resources.
EnumResourceNames can be used, passing in RT_GROUP_ICON, to find the available group icon resources. Once the appropriate group resource is chosen, it can be loaded using FindResource, LoadResource and LockResource. This will yield a pointer to a GRPICONDIR structure.
The idEntries array is the searched for a match on the desired color depth and size. The nID member of that array element is then used as an argument to FindResource, passing in RT_ICON. LoadResource and LockResource then yield a pointer to an ICONIMAGE structure for that icon image.
To allow Windows to perform the color depth and size selection, the GRPICONDIR structure can be passed to LookUpIconIdFromDirectory or LookUpIconIdFromDirectoryEx. Both of these functions return an id that can be used with RT_ICON and FindResource, the latter providing a way to specify a desired size to match against.
The ICONIMAGE structure contains pointers to the DIB bits for the masks. These pointers can be used in DIB functions for direct manipulation. The ICONIMAGE structure is also conveniently suitable to be passed to CreateIconFromResource or CreateIconFromResourceEx to yield an HICON handle. The former of the two functions creates an icon that is System Large size. The latter provides a way to specify a desired size, and Windows performs the appropriate conversions.
HICON Handles
An HICON handle is a handle to a single icon image. This is analogous to a single RT_ICON resource. The image is stored internally using device dependent bitmaps (DDBs). This implies that all HICON icons have the same color format as the display device. The size of the icon depends on its origin and the system defined icon sizes.
The available icon handling functions can be thought of in two groups—those that handle System Large size icons and those that handle any size icons. The functions that handle only System Large size icons are typically left over from 16 bit days, when the system defined only one icon size. The newer functions, those that handle any size icon, accept as a parameter the desired size of the icon.
One Size Fits All
The original icon handling functions were designed for a system that defined only one icon size. Therefore, most of those functions are unaware of the possibility of more than one icon size and assume all icons are System Large size.
LoadIcon, ExtractIcon and DrawIcon fall into this category. LoadIcon and ExtractIcon always search for a match for System Large size. If an exact match cannot be found, these two functions stretch the closest match to that size. They always return an icon of System Large size. Similarly, DrawIcon always draws the icon at System Large size. If a different size icon is passed to DrawIcon, it is stretched and displayed at System Large size.
CreateIconFromResource also exhibits this behavior. It returns a handle to a System Large size icon, stretching the RT_ICON resource it was passed as necessary.
To Each Their Own
Now that Windows has the ability to handle different sized icons, new API functions were added to handle them. In some cases, old functions were expanded and "Ex" was added to their name. In other cases, whole new functions were added. The net result is that there is now full support for different sized icons in the Windows API.
An Icon file, which usually has the ICO extension, contains one icon resource. Given that an icon resource can contain multiple images, it is no surprise that the file begins with an icon directory:
typedef struct
{
WORD idReserved; // Reserved (must be 0)
WORD idType; // Resource Type (1 for icons)
WORD idCount; // How many images?
ICONDIRENTRY idEntries[1]; // An entry for each image (idCount of 'em)
} ICONDIR, *LPICONDIR;
The idCount member indicates how many images are present in the icon resource. The size of the idEntries array is determined by idCount. There exists one ICONDIRENTRY for each icon image in the file, providing details about its location in the file, size and color depth. The ICONDIRENTRY structure is defined as:
typedef struct
{
BYTE bWidth; // Width, in pixels, of the image
BYTE bHeight; // Height, in pixels, of the image
BYTE bColorCount; // Number of colors in image (0 if >=8bpp)
BYTE bReserved; // Reserved ( must be 0)
WORD wPlanes; // Color Planes
WORD wBitCount; // Bits per pixel
DWORD dwBytesInRes; // How many bytes in this resource?
DWORD dwImageOffset; // Where in the file is this image?
} ICONDIRENTRY, *LPICONDIRENTRY;
For each ICONDIRENTRY, the file contains an icon image. The dwBytesInRes member indicates the size of the image data. This image data can be found dwImageOffset bytes from the beginning of the file, and is stored in the following format:
typdef struct
{
BITMAPINFOHEADER icHeader; // DIB header
RGBQUAD icColors[1]; // Color table
BYTE icXOR[1]; // DIB bits for XOR mask
BYTE icAND[1]; // DIB bits for AND mask
} ICONIMAGE, *LPICONIMAGE;
The icHeader member has the form of a DIB BITMAPINFOHEADER. Only the following members are used: biSize, biWidth, biHeight, biPlanes, biBitCount, biSizeImage. All other members must be 0. The biHeight member specifies the combined height of the XOR and AND masks. The members of icHeader define the contents and sizes of the other elements of the ICONIMAGE structure in the same way that the BITMAPINFOHEADER structure defines a CF_DIB format DIB.
The icColors member is an array of RGBQUADs. The number of elements in this array is determined by examining the icHeader member.
The icXOR member contains the DIB bits for the XOR mask of the image. The number of bytes in this array is determined by examining the icHeader member. The XOR mask is the color portion of the image and is applied to the destination using the XOR operation after the application of the AND mask.
The icAND member contains the bits for the monochrome AND mask. The number of bytes in this array is determined by examining the icHeader member, and assuming 1bpp. The dimensions of this bitmap must be the same as the dimensions of the XOR mask. The AND mask is applied to the destination using the AND operation, to preserve or remove destination pixels before applying the XOR mask.
Note The biHeight member of the icHeader structure represents the combined height of the XOR and AND masks. Remember to divide this number by two before using it to perform calculations for either of the XOR or AND masks. Also remember that the AND mask is a monochrome DIB, with a color depth of 1 bpp.
The following is an incomplete code fragment for reading an .ICO file:
// We need an ICONDIR to hold the data
pIconDir = malloc( sizeof( ICONDIR ) );
// Read the Reserved word
ReadFile( hFile, &(pIconDir->idReserved), sizeof( WORD ), &dwBytesRead, NULL );
// Read the Type word - make sure it is 1 for icons
ReadFile( hFile, &(pIconDir->idType), sizeof( WORD ), &dwBytesRead, NULL );
// Read the count - how many images in this file?
ReadFile( hFile, &(pIconDir->idCount), sizeof( WORD ), &dwBytesRead, NULL );
// Reallocate IconDir so that idEntries has enough room for idCount elements
pIconDir = realloc( pIconDir, ( sizeof( WORD ) * 3 ) +
( sizeof( ICONDIRENTRY ) * pIconDir->idCount ) );
// Read the ICONDIRENTRY elements
ReadFile( hFile, pIconDir->idEntries, pIconDir->idCount * sizeof(ICONDIRENTRY),
&dwBytesRead, NULL );
// Loop through and read in each image
for(i=0;i<pIconDir->idCount;i++)
{
// Allocate memory to hold the image
pIconImage = malloc( pIconDir->idEntries
// Seek to the location in the file that has the image
SetFilePointer( hFile, pIconDir->idEntries
NULL, FILE_BEGIN );
// Read the image data
ReadFile( hFile, pIconImage, pIconDir->idEntries
&dwBytesRead, NULL );
// Here, pIconImage is an ICONIMAGE structure. Party on it :)
// Then, free the associated memory
free( pIconImage );
}
// Clean up the ICONDIR memory
free( pIconDir );
Complete code can be found in the Icons.C module of IconPro, in a function named ReadIconFromICOFile.
DLL and EXE Files
Icons can also be stored in .DLL and .EXE files. The structures used to store icon images in .EXE and .DLL files differ only slightly from those used in .ICO files.
Analogous to the ICONDIR data in the ICO file is the RT_GROUP_ICON resource. In fact, one RT_GROUP_ICON resource is created for each ICO file bound to the EXE or DLL with the resource compiler/linker. The RT_GROUP_ICON resource is simply a GRPICONDIR structure:
// #pragmas are used here to insure that the structure's
// packing in memory matches the packing of the EXE or DLL.
#pragma pack( push )
#pragma pack( 2 )
typedef struct
{
WORD idReserved; // Reserved (must be 0)
WORD idType; // Resource type (1 for icons)
WORD idCount; // How many images?
GRPICONDIRENTRY idEntries[1]; // The entries for each image
} GRPICONDIR, *LPGRPICONDIR;
#pragma pack( pop )
The idCount member indicates how many images are present in the icon resource. The size of the idEntries array is determined by idCount. There exists one GRPICONDIRENTRY for each icon image in the resource, providing details about its size and color depth. The GRPICONDIRENTRY structure is defined as:
#pragma pack( push )
#pragma pack( 2 )
typedef struct
{
BYTE bWidth; // Width, in pixels, of the image
BYTE bHeight; // Height, in pixels, of the image
BYTE bColorCount; // Number of colors in image (0 if >=8bpp)
BYTE bReserved; // Reserved
WORD wPlanes; // Color Planes
WORD wBitCount; // Bits per pixel
DWORD dwBytesInRes; // how many bytes in this resource?
WORD nID; // the ID
} GRPICONDIRENTRY, *LPGRPICONDIRENTRY;
#pragma pack( pop )
The dwBytesInRes member indicates the total size of the RT_ICON resource referenced by the nID member. nID is the RT_ICON identifier that can be passed to FindResource, LoadResource and LockResource to obtain a pointer to the ICONIMAGE structure (defined above) for this image.
The following is an incomplete code fragment for reading icons from a .DLL or .EXE file:
// Load the DLL/EXE without executing its code
hLib = LoadLibraryEx( szFileName, NULL, LOAD_LIBRARY_AS_DATAFILE );
// Find the group resource which lists its images
hRsrc = FindResource( hLib, MAKEINTRESOURCE( nId ), RT_GROUP_ICON );
// Load and Lock to get a pointer to a GRPICONDIR
hGlobal = LoadResource( hLib, hRsrc );
lpGrpIconDir = LockResource( hGlobal );
// Using an ID from the group, Find, Load and Lock the RT_ICON
hRsrc = FindResource( hLib, MAKEINTRESOURCE( lpGrpIconDir->idEntries[0].nID ), RT_ICON );
hGlobal = LoadResource( hLib, hRsrc );
lpIconImage = LockResource( hGlobal );
// Here, lpIconImage points to an ICONIMAGE structure
Complete code can be found in the Icons.C module of IconPro, in a function named ReadIconFromEXEFile.
In Memory
When dealing with icon resources in memory, the format is identical to the format used in .EXE and .DLL files. APIs such as CreateIconFromResource expect to be passed an ICONIMAGE structure. This is very convenient since FindResource, LoadResource and LockResource can be used to load the RT_ICON resource in that format.
An HICON handle is a handle to a single icon image, or RT_ICON resource. In previous versions of Windows, the size of an HICON image could be determined by calling GetSystemMetrics with the SM_CYICON and SM_CXICON flags. It is now possible, however, to have HICON handles for icons with non-standard sizes. HICON icons always have the same color format as the display device. See the discussion of APIs below for more details on how to handle icons of different sizes and color depths using HICON handles.
When in Windows
In Windows, the system maintains the concept of two sizes of icons, small and large. Further, the shell also has a concept of small and large icons. This means that in total, Windows is aware of four different icon sizes—System Small, System Large, Shell Small, and Shell Large.
The System Small size is derived from the size of window captions. The caption size can be adjusted from the "Appearance" tab in the Display Properties dialog. Adjustments made to the caption size are immediately reflected in the System Small icon size. The System Small size can be queried by calling GetSystemMetrics with the SM_CXSMICON and SM_CYSMICON parameters.
The System Large size is defined by the video driver and therefore cannot be changed dynamically. The System Large size can be queried by calling GetSystemMetrics with the SM_CXICON and SM_CYICON parameters.
The Shell Small size is defined by Windows, and currently Windows does not support changing this value, nor is there currently a direct way to query this value.
The Shell Large size is stored in the registry under the following key:
HKEY_CURRENT_USER\Control Panel\desktop\WindowMetrics\Shell Icon Size
The Shell Large size can be changed by modifying the registry or from the "Appearance" tab in the Display Properties dialog, which allows values from 16 to 72. Following is an example of code that can be used to change the Shell Large icon size by accessing the registry:
DWORD SetShellLargeIconSize( DWORD dwNewSize )
{
#define MAX_LENGTH 512
DWORD dwOldSize, dwLength = MAX_LENGTH, dwType = REG_SZ;
TCHAR szBuffer[MAX_LENGTH];
HKEY hKey;
// Get the Key
RegOpenKey( HKEY_CURRENT_USER, "Control Panel\\desktop\\WindowMetrics", &hKey);
// Save the last size
RegQueryValueEx( hKey, "Shell Icon Size", NULL, &dwType, szBuffer, &dwLength );
dwOldSize = atol( szBuffer );
// We will allow only values >=16 and <=72
if( (dwNewSize>=16) || (dwNewSize<=72) )
{
wsprintf( szBuffer, "%d", dwNewSize );
RegSetValueEx( hKey, "Shell Icon Size", 0, REG_SZ, szBuffer, lstrlen(szBuffer) + 1 );
}
// Clean up
RegCloseKey( hKey );
// Let everyone know that things changed
SendMessage( HWND_BROADCAST, WM_SETTINGCHANGE, SPI_SETICONMETRICS,
(LPARAM)("WindowMetrics") );
return dwOldSize;
#undef MAX_LENGTH
}
Choosing an Icon
When Windows prepares to display an icon, a desktop shortcut for example, it must parse the .EXE or .DLL file and extract the appropriate icon image. This selection is a two step process starting with the selection of the appropriate RT_GROUP_ICON resource, and ending with the selection of the proper RT_ICON image from that RT_GROUP_ICON.
Which Icon?
If an .EXE or .DLL file has only one RT_GROUP_ICON resource, the first step is trivial; Windows simply uses that resource. However, if more than one such group resource exists in the file, Windows must decide which one to use. Windows NT simply chooses the first resource listed in the application's RC script. On the other hand, Windows 95's algorithm is to choose the alphabetically first named group icon if one exists. If one such group resource does not exist, Windows chooses the icon with the numerically lowest identifier. So, to be sure that a particular icon is used for an application, the developer should insure that both of the following criteria are met:
The icon is placed before all other icons in the RC file.
If the icon is named, its name is alphabetically before any other named icon, otherwise its resource identifier is numerically smaller than any other icon.
Which Image?
Once an RT_GROUP_ICON is chosen, the individual icon image, or RT_ICON resource, must be selected and extracted. Again, if there exists only one RT_ICON resource for the group in question, the choice is trivial. However, if multiple images are present in the group, the following selection rules are applied:
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 none exactly match the color depth of the display, Windows chooses the image with the greatest color depth without exceeding the color depth of the display.
If all the size-matched images exceed the color depth of the display, the one with the lowest color depth is chosen.
Windows treats all color depths of 8 or more bpp as equal. For example, it is pointless to have a 16x16 256 color image and a 16x16 16bpp image in the same resource—Windows will simply choose the first one it encounters.
When the display is in 8bpp mode, Windows will prefer a 16 color icon over a 256 color icon, and will display all icons using the system default palette.
APIs
When dealing with icons, the developer can choose to manipulate the raw resource bytes, or let Windows handle the low level details and simply use HICON handles. The advantage of handling the raw resource bytes is a gain in control, while the advantage of using the HICON handles is that of simplicity. For most purposes, the HICON interface is sufficient—it is likely that handling the raw resource bytes will be necessary only in the development of an icon handling program.
Raw Resource Bytes
The standard Windows API functions for manipulating resources—FindResource, LoadResource and LockResource—can, of course, be used to handle icon resources.
EnumResourceNames can be used, passing in RT_GROUP_ICON, to find the available group icon resources. Once the appropriate group resource is chosen, it can be loaded using FindResource, LoadResource and LockResource. This will yield a pointer to a GRPICONDIR structure.
The idEntries array is the searched for a match on the desired color depth and size. The nID member of that array element is then used as an argument to FindResource, passing in RT_ICON. LoadResource and LockResource then yield a pointer to an ICONIMAGE structure for that icon image.
To allow Windows to perform the color depth and size selection, the GRPICONDIR structure can be passed to LookUpIconIdFromDirectory or LookUpIconIdFromDirectoryEx. Both of these functions return an id that can be used with RT_ICON and FindResource, the latter providing a way to specify a desired size to match against.
The ICONIMAGE structure contains pointers to the DIB bits for the masks. These pointers can be used in DIB functions for direct manipulation. The ICONIMAGE structure is also conveniently suitable to be passed to CreateIconFromResource or CreateIconFromResourceEx to yield an HICON handle. The former of the two functions creates an icon that is System Large size. The latter provides a way to specify a desired size, and Windows performs the appropriate conversions.
HICON Handles
An HICON handle is a handle to a single icon image. This is analogous to a single RT_ICON resource. The image is stored internally using device dependent bitmaps (DDBs). This implies that all HICON icons have the same color format as the display device. The size of the icon depends on its origin and the system defined icon sizes.
The available icon handling functions can be thought of in two groups—those that handle System Large size icons and those that handle any size icons. The functions that handle only System Large size icons are typically left over from 16 bit days, when the system defined only one icon size. The newer functions, those that handle any size icon, accept as a parameter the desired size of the icon.
One Size Fits All
The original icon handling functions were designed for a system that defined only one icon size. Therefore, most of those functions are unaware of the possibility of more than one icon size and assume all icons are System Large size.
LoadIcon, ExtractIcon and DrawIcon fall into this category. LoadIcon and ExtractIcon always search for a match for System Large size. If an exact match cannot be found, these two functions stretch the closest match to that size. They always return an icon of System Large size. Similarly, DrawIcon always draws the icon at System Large size. If a different size icon is passed to DrawIcon, it is stretched and displayed at System Large size.
CreateIconFromResource also exhibits this behavior. It returns a handle to a System Large size icon, stretching the RT_ICON resource it was passed as necessary.
To Each Their Own
Now that Windows has the ability to handle different sized icons, new API functions were added to handle them. In some cases, old functions were expanded and "Ex" was added to their name. In other cases, whole new functions were added. The net result is that there is now full support for different sized icons in the Windows API.
