Image Handles [v1.1.23+]

To use an icon or bitmap handle in place of an image filename, use the following syntax:

HBITMAP:bitmap-handle
HICON:icon-handle

Replace bitmap-handle or icon-handle with the actual handle value. For example, hicon:%handle% (or "hicon:" handle in an expression), where handle is a variable containing an icon handle.

The following commands support this syntax:

• Gui Add, Picture (and GuiControl when setting a Picture control's content).
• IL_Add
• LoadPicture
• SB_SetIcon
• ImageSearch
• Menu Tray, Icon or Menu MenuName, Icon
• SplashImage

A bitmap or icon handle is a numeric value which identifies a bitmap or icon in memory. The majority of scripts never need to deal with handles, as in most cases AutoHotkey takes care of loading the image from file and freeing it when it is no longer needed. The syntax shown above is intended for use when the script obtains an icon or bitmap handle from another source, such as by sending the WM_GETICON message to a window. It can also be used in combination with LoadPicture to avoid loading an image from file multiple times.

By default, AutoHotkey treats the handle as though it loaded the image from file - for example, a bitmap used on a Picture control is deleted when the GUI is destroyed, and an image will generally be deleted immediately if it needs to be resized. To avoid this, put an asterisk between the colon and handle. For example: hbitmap:*%handle% (or "hbitmap:*" handle in an expression). With the exception of ImageSearch, this forces the command to take a copy of the image.

Examples

; Show a menu of the first n files matching a pattern, and their icons.
pattern = %A_ScriptDir%\*
n = 15

; Allocate memory for a SHFILEINFOW struct.
VarSetCapacity(fileinfo, fisize := A_PtrSize + 688)

Loop, Files, %pattern%, FD
{
    ; Add a menu item for each file.
    Menu F, Add, %A_LoopFileName%, donothing
    
    ; Get the file's icon.
    if DllCall("shell32\SHGetFileInfoW", "wstr", A_LoopFileFullPath
        , "uint", 0, "ptr", &fileinfo, "uint", fisize, "uint", 0x100)
    {
        hicon := NumGet(fileinfo, 0, "ptr")
        ; Set the menu item's icon.
        Menu F, Icon, %A_Index%&, HICON:%hicon%
        ; Because we used ":" and not ":*", the icon will be automatically
        ; freed when the program exits or if the menu or item is deleted.
    }
}
until A_Index = n
Menu F, Show
donothing:
return

See also: LoadPicture.