Windows API Guide - Reference - Volume 1: Version 3.0 For the MS-DOS and PC-DOS Operating Systems

2017-07-07 02:10:07

Declare Function ExtractIcon Lib "shell32.dll" Alias "ExtractIconA" (ByVal hInst as Long, ByVal lpszExeFileName As String, ByVal nIconIndex As Long) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.1 or later.
Windows 2000: Supported.
Windows CE: Not Supported.

Description & Usage

ExtractIcon extracts a single icon from a file. This file can be an executable (.exe) file, a dynamic link library (.dll), or an icon file (.ico). Alternately, this function can also determine how many icons are stored in such a file. The icon generated by this function must be destroyed using DestroyIcon after the program has finished using it.

Return Value

If the function failed because the specified file was not found, the function returns 1. If the function failed because the icon requested by the function did not exist, the function returns 0. If the function succeeded and the number of icons in the file was requested, the function returns the number of icons stored in the file. If the function succeeded and an icon was specified, the function returns a handle to the extracted icon.

Visual Basic-Specific Issues

None.

Parameters

hInst: A handle to the instance of the application calling the function.
lpszExeFileName: The name of an .exe, .dll, or .ico to extract an icon from.
nIconIndex: If this is -1, the function returns the number of icons stored in the specified file. If this is a non-negative number, the function extracts the icon using this value as the zero-based index (an index of 0 identifies the first icon, etc.). Windows 95, 98, NT 4.0 or later, 2000: If this is negative and not -1, the function extracts the icon whose resource identifier equals the absolute value of this parameter. (To extract an icon with a resource identifier of 1, ExtractIconEx must be used instead.)

Example

' This code is licensed according to the terms and conditions listed here. ' Display the first icon (index 0) stored in the executable file ' C:\MyApp\Prog.exe on window Form1. The icon must be destroyed after the ' program finishes using it. Dim hIcon As Long ' handle to the function gotten from the executable file Dim retval As Long ' return value ' Extract the first icon stored in the aforementioned executable file. hIcon = ExtractIcon(App.hInstance, "C:\MyApp\Prog.exe", 0) ' Only attempt to display the icon if we successfully extracted it. If hIcon = 0 Then Debug.Print "Failed to extract the icon -- aborting." End ' terminate the program Else ' Display the icon at coordinates (100, 75) on window Form1. retval = DrawIcon(Form1.hDC, 100, 75, hIcon) ' Although the icon's image is still visible, the icon itself is not in use. ' Therefore we destroy it to free up resources. retval = DestroyIcon(hIcon) End If