Icon in Res

[Vanja]

Icons in Win32
John Hornick
Microsoft Corporation

Created: September 29, 1995

John is a Support Engineer in Product Support Services, Windows Developer
Support.

Click to open or copy the files in the IconPro sample application for this
technical article.

Abstract
This article describes, in detail, the format and use of icons in 32-bit
Windows. The following topics are covered; the format of icon resources in
ICO, DLL and EXE files, the format of icon images in memory, Windows' use of
icons, Windows' selection of an icon image from an icon resource, and the
APIs provided to manipulate icon images. To follow the discussion, the
reader should be familiar with Device Independent Bitmaps (DIBs) and their
format. For more information about DIBs, please refer to the following
sources:

a.. Win32 SDK On-line help for the BITMAPINFO structure

b.. Knowledge Base article Q81498 SAMPLE: DIBs and Their Uses

c.. Knowledge Base article Q94326 SAMPLE: 16 and 32 Bits-Per-Pel Bitmap
Formats
Sample code dealing with some of the topics in this article is available in
the Win32 SDK sample tree in the IconPro project.

Disclaimer Internal details discussed in this article are subject to
change without notice in future versions of Windows.

Introduction
Icons are a varied lot-they come in many sizes and color depths. A single
icon resource-an ICO file, or an icon resource in an EXE or DLL file-can
contain multiple icon images, each with a different size and/or color depth.
Windows 95 and future versions of Windows NT (collectively referred to as
"Windows" from here on) extract the appropriate size/color depth image from
the resource depending on the context of the icon's use. Windows also
provides a collection of APIs for accessing and displaying icons and icon
images.

What's in an Icon?
An icon resource can contain multiple icon images. For example, one icon
resource-in this case, a single .ICO file-can contain images in several
sizes and color depths:

16 x 16 16 colors 32 x 32 16 colors 72 x 72 256 colors

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[i].dwBytesInRes );
// Seek to the location in the file that has the image
SetFilePointer( hFile, pIconDir->idEntries[i].dwImageOffset,
NULL, FILE_BEGIN );
// Read the image data
ReadFile( hFile, pIconImage, pIconDir->idEntries[i].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
}

Table 1. Where Windows Uses Different Sized Icons

Location Icon Size
Desktop Shell Large
TitleBar of Windows System Small
<Alt><Tab> Dialog System Large
Start Menu Shell Small / Shell Large

While Windows imposes no restrictions on the sizes of icons, common sizes
include 16, 32, and 48 pixels square. For this reason, developers are
encouraged to include a minimum of the following sizes and color depths in
their icon resources:

16 x 16 16 colors
32 x 32 16 colors
48 x 48 256 colors

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:

1.. The icon is placed before all other icons in the RC file.

2.. 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:

1.. The image closest in size to the requested size is chosen.

2.. If two or more images of that size are present, the one that matches
the color depth of the display is chosen.

3.. 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.

4.. If all the size-matched images exceed the color depth of the display,
the one with the lowest color depth is chosen.

5.. 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.

6.. 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.

Several different functions are available to get an HICON handle to a
different sized icon. LoadImage() can be used to extract an icon from an EXE
or DLL file without the hassle of manually loading the resource bytes.
CreateIconFromResourceEx() is available if the resource bytes have been
loaded.

CreateIcon() and CreateIconIndirect(), even though they have their roots in
16-bit land, do facilitate creating icons of different sizes. CreateIcon()
accept a desired width and height as parameters, while CreateIconIndirect()
creates an icon based on the bitmaps in the ICONINFO parameter. Note that
both of these functions work with DDBs, not DIBs.

SHGetFileInfo() can also be used to get icons from files, providing the icon
that the shell would display for the file. SHGetFileInfo() works on any type
of file, and can extract any of the four icons sizes, as shown below:

// Load a System Large icon image
SHGetFileInfo( szFileName, 0, &shfi, sizeof( SHFILEINFO ),
SHGFI_ICON | SHGFI_LARGEICON);

// Load a System Small icon image
SHGetFileInfo( szFileName, 0, &shfi, sizeof( SHFILEINFO ),
SHGFI_ICON | SHGFI_SMALLICON);

// Load a Shell Large icon image
SHGetFileInfo( szFileName, 0, &shfi, sizeof( SHFILEINFO ),
SHGFI_ICON | SHGFI_SHELLICONSIZE);

// Load a Shell Small icon image
SHGetFileInfo( szFileName, 0, &shfi, sizeof( SHFILEINFO ),
SHGFI_ICON | SHGFI_SHELLICONSIZE | SHGFI_SMALLICON);

Given an HICON handle, DrawIconEx() can be used to display it-at its normal
size, at the System Large size, or at any other size:

// Draw it at its native size
DrawIconEx( hDC, nLeft, nTop, hIcon, 0, 0, 0, NULL, DI_NORMAL );

// Draw it at the System Large size
DrawIconEx( hDC, nLeft, nTop, hIcon, 0, 0, 0,
NULL, DI_DEFAULTSIZE | DI_NORMAL );

// Draw it at some other size (40x40 in this example)
DrawIconEx( hDC, nLeft, nTop, hIcon, 40, 40, 0, NULL, DI_NORMAL );

Note that DrawIconEx() will stretch the icon as necessary to make it fit the
desired output size.

What's in There?
The Win32 API provides a function for determining the characteristics of an
icon, given its HICON handle. This function is GetIconInfo(). GetIconInfo()
fills out an ICONINFO structure with the information pertaining to the
HICON. The ICONINFO structure contains the following information:

typedef struct _ICONINFO { // ii

BOOL fIcon; // TRUE for icon, FALSE for cursor
DWORD xHotspot; // the x hotspot coordinate for cursor
DWORD yHotspot; // the y hotspot coordinate for cursor
HBITMAP hbmMask; // handle to monochrome AND mask bitmap
HBITMAP hbmColor; // handle to device dependent XOR mask bitmap
} ICONINFO;

Given this information, an application can calculate the information needed
to write the icon to a file. The AND mask and XOR mask DIB bits can be
obtained with calls to GetDIBits() on the two bitmaps in this structure.

A Word on Cursors
Cursors, in Win32, are very similar to icons. In fact, by changing only one
line in the source code for IconPro, that sample can read .CUR files.
IconPro currently tests the idType member of the ICONDIR structure to make
sure the file is an icon file. This check can be relaxed to allow the type
for cursors (2) as well. Also, HCURSOR handles can be used interchangeably
with HICON handles in most Win32 icon APIs.

Conclusion
Although the icon specification has long been able to handle icons of odd
sizes and color depths, only recently has Windows responded with inherent
support for such images. Developers now have the option of dealing directly
with the bits of an icon, or allowing Windows to handle all the details.
Windows even provides API support for loading and displaying icons of
non-standard sizes and different color depths.

© 1999 Microsoft Corporation. All rights reserved. Terms of use.