CopyImage function (winuser.h)

  • Article

Creates a new image (icon, cursor, or bitmap) and copies the attributes of the specified image to the new one. If necessary, the function stretches the bits to fit the desired size of the new image.

Syntax

HANDLE CopyImage(
  [in] HANDLE h,
  [in] UINT   type,
  [in] int    cx,
  [in] int    cy,
  [in] UINT   flags
);

Parameters

[in] h

Type: HANDLE

A handle to the image to be copied.

[in] type

Type: UINT

The type of image to be copied. This parameter can be one of the following values.

Value Meaning
IMAGE_BITMAP
0
 Copies a bitmap.
IMAGE_CURSOR
2
 Copies a cursor.
IMAGE_ICON
1
 Copies an icon.

[in] cx

Type: int

The desired width, in pixels, of the image. If this is zero, then the returned image will have the same width as the original hImage.

[in] cy

Type: int

The desired height, in pixels, of the image. If this is zero, then the returned image will have the same height as the original hImage.

[in] flags

Type: UINT

This parameter can be one or more of the following values.

Value Meaning
LR_COPYDELETEORG
0x00000008
 Deletes the original image after creating the copy.
LR_COPYFROMRESOURCE
0x00004000
 Tries to reload an icon or cursor resource from the original resource file rather than simply copying the current image. This is useful for creating a different-sized copy when the resource file contains multiple sizes of the resource. Without this flag, CopyImage stretches the original image to the new size. If this flag is set, CopyImage uses the size in the resource file closest to the desired size. This will succeed only if hImage was loaded by LoadIcon or LoadCursor, or by LoadImage with the LR_SHARED flag.
LR_COPYRETURNORG
0x00000004
 Returns the original hImage if it satisfies the criteria for the copy—that is, correct dimensions and color depth—in which case the LR_COPYDELETEORG flag is ignored. If this flag is not specified, a new object is always created.
LR_CREATEDIBSECTION
0x00002000
 If this is set and a new bitmap is created, the bitmap is created as a DIB section. Otherwise, the bitmap image is created as a device-dependent bitmap. This flag is only valid if uType is IMAGE_BITMAP.
LR_DEFAULTCOLOR
0x00000000
 Uses the default color format.
LR_DEFAULTSIZE
0x00000040
 Uses the width or height specified by the system metric values for cursors or icons, if the cxDesired or cyDesired values are set to zero. If this flag is not specified and cxDesired and cyDesired are set to zero, the function uses the actual resource size. If the resource contains multiple images, the function uses the size of the first image.
LR_MONOCHROME
0x00000001
 Creates a new monochrome image.

Return value

Type: HANDLE

If the function succeeds, the return value is the handle to the newly created image.

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

Remarks

When you are finished using the resource, you can release its associated memory by calling one of the functions in the following table.

Resource Release function
Bitmap DeleteObject
Cursor DestroyCursor
Icon DestroyIcon
 

The system automatically deletes the resource when its process terminates, however, calling the appropriate function saves memory and decreases the size of the process's working set.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header winuser.h (include Windows.h)
Library User32.lib
DLL User32.dll
API set ext-ms-win-ntuser-gui-l1-3-0 (introduced in Windows 10, version 10.0.10240)

See also

Conceptual

LoadImage

Reference

Resources