DrawIconEx

The DrawIconEx function draws an icon or cursor in the client area of the window of the specified device context, performing the specified raster operations, and stretching or compressing the icon or cursor as specified.

BOOL DrawIconEx(
  HDC hdc,                    // handle to device context
  int xLeft,                  // x-coordinate of upper left corner
  int yTop,                   // y-coordinate of upper left corner
  HICON hIcon,                // handle to icon to draw
  int cxWidth,                // width of the icon
  int cyWidth,                // height of the icon
  UINT istepIfAniCur,         // index of frame in animated cursor
  HBRUSH hbrFlickerFreeDraw,  // handle to background brush
  UINT diFlags                // icon-drawing flags
);
 

Parameters

hdc

Handle to the device context for a window.

xLeft

Specifies the logical x-coordinate of the upper-left corner of the icon or cursor.

yTop

Specifies the logical y-coordinate of the upper-left corner of the icon or cursor.

hIcon

Handle to the icon or cursor to be drawn. This parameter can identify an animated cursor. The icon or cursor resource must have been previously loaded by using the LoadImage function.

cxWidth

Specifies the logical width of the icon or cursor. If this parameter is zero and the diFlags parameter is DI_DEFAULTSIZE, the function uses the SM_CXICON or SM_CXCURSOR system metric value to set the width. If this parameter is zero and DI_DEFAULTSIZE is not used, the function uses the actual resource width.

cyWidth

Specifies the logical height of the icon or cursor. If this parameter is zero and the diFlags parameter is DI_DEFAULTSIZE, the function uses the SM_CYICON or SM_CYCURSOR system metric value to set the width. If this parameter is zero and DI_DEFAULTSIZE is not used, the function uses the actual resource height.

istepIfAniCur

Specifies the index of the frame to draw, if hIcon identifies an animated cursor. This parameter is ignored if hIcon does not identify an animated cursor.

hbrFlickerFreeDraw

Handle to a brush that the system uses for flicker-free drawing. If hbrFlickerFreeDraw is a valid brush handle, the system creates an offscreen bitmap using the specified brush for the background color, draws the icon or cursor into the bitmap, and then copies the bitmap into the device context identified by hdc. If hbrFlickerFreeDraw is NULL, the system draws the icon or cursor directly into the device context.

diFlags

Specifies the drawing flags. This parameter can be one of the following values:

Value	Meaning
DI_COMPAT	Draws the icon or cursor using the system default image rather than the user-specified image.
DI_DEFAULTSIZE	Draws the icon or cursor using the width and height specified by the system metric values for cursors or icons, if the cxWidth and cyWidth parameters are set to zero. If this flag is not specified and cxWidth and cyWidth are set to zero, the function uses the actual resource size.
DI_IMAGE	Draws the icon or cursor using the image.
DI_MASK	Draws the icon or cursor using the mask.
DI_NORMAL	Combination of DI_IMAGE and DI_MASK.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The DrawIconEx function places the icon's upper-left corner at the location specified by the xLeft and yTop parameters. The location is subject to the current mapping mode of the device context.

Windows CE: The following parameter settings must be used:

• diFlags must be DI_NORMAL, DI_IMAGE, or DI_MASK. (DI_COMPAT and DI_DEFAULTSIZE are not supported.)
• cxWidth and cyHeight must be zero or the native dimensions of the icon.
• hbrFlickerFreeDraw must be NULL.
• iStepIfAniCur must be zero. Animated icons are not supported.

Windows CE does not support:

• Stretching and compressing.

  That is, the icon resolution is fixed for a given HICON, and no icon resizing is supported.

• Mapping modes.
• Using DrawIconEx to draw cursors.

The hIcon parameter cannot identify an animated cursor.

QuickInfo

  Windows NT: Requires version 3.5 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Requires version 1.0 or later.
  Header: Declared in winuser.h.
  Import Library: Use user32.lib.

See Also

Icons Overview, Icon Functions, CopyImage, DrawIcon, LoadImage