wIconImage

    Dark Mode

This class encapsulates a Windows icon image. Unlike wImage, wBitmap, wIcon, wCursor, etc., wIconImage doesn't store any Windows resource handle, but only an icon image in binary format. In addition to the binary image data, wIconImage also stores the hotspot for cursor if the icon image is created from a cursor resource.

A wIconImage object can be created from Windows PE files (.exe or .dll) or icon files (.ico or .cur). It also can be created by wImage, wBitmap, wIcon, or wCursor. Furthermore, wIconImage can be converted to wImage, wBitmap, wIcon, wCursor, or .ico/.cur files. In summary, it is easy to deal with Windows' image-like resource and image files by wIconImage.

The wIconImage class use the same binary format as an image inside the icon files. So there are two possible format of wIconImage object: BMP or PNG. Since Windows XP don't support PNG format icon files, it is recommend to use toBmp() before saving a wIconImage object to icon file if the icon file will be used under Windows XP.

Seealso:wImage wBitmap wIcon wCursor

Types

wIconImageError = object of wError
An error raised when wIconImage creation or operation failure.

Procs

proc init(self: wIconImage; icon: wIcon) {...}{.raises: [wNilAccess, wIconImageError],
                                      tags: [].}
Initializes an icon image from a wIcon object. 
proc IconImage(icon: wIcon): wIconImage {...}{.inline,
                                      raises: [wNilAccess, wIconImageError],
                                      tags: [].}
Constructor. 
proc init(self: wIconImage; cursor: wCursor) {...}{.raises: [wNilAccess, wIconImageError],
    tags: [].}
Initializes an icon image from a wCursor object. 
proc IconImage(cursor: wCursor): wIconImage {...}{.inline,
    raises: [wNilAccess, wIconImageError], tags: [].}
Constructor. 
proc init(self: wIconImage; bmp: wBitmap) {...}{.raises: [wNilAccess, wIconImageError],
                                       tags: [].}
Initializes an icon image from a wBitmap object. 
proc IconImage(bmp: wBitmap): wIconImage {...}{.inline, discardable,
                                       raises: [wNilAccess, wIconImageError],
                                       tags: [].}
Constructor. 
proc init(self: wIconImage; image: wImage) {...}{.raises: [wNilAccess, wIconImageError],
                                        tags: [].}
Initializes an icon image from a wImage object. 
proc IconImage(image: wImage): wIconImage {...}{.inline, discardable,
                                        raises: [wNilAccess, wIconImageError],
                                        tags: [].}
Constructor. 
proc init(self: wIconImage; data: pointer; length: int; size = wDefaultSize) {...}{.
    raises: [wNilAccess, wIconImageError], tags: [].}

Initializes an icon image from binary data of .ico or .cur file. The extra size parameter can be used to specified the desired display size. The function uses Windows API to search and return the best fits icon, or uses the SM_CXICON/SM_CXCURSOR system metric value as default value.

Notice: The function will not resize the image, so the real size of retruned icon image may not equal to your desired size.

proc IconImage(data: pointer; length: int; size = wDefaultSize): wIconImage {...}{.inline,
    discardable, raises: [wNilAccess, wIconImageError], tags: [].}
Constructor. 
proc init(self: wIconImage; str: string; size = wDefaultSize) {...}{.
    raises: [wIconImageError], tags: [ReadIOEffect].}

Initializes an icon image from a file. The file should be in format of .ico, .cur, or Windows PE file (.exe or .dll, etc). If str is not a valid file path, it will be regarded as the binary data of .ico or .cur file.

For Windows PE file (.exe or .dll), you should use string like "shell32.dll,-10" to specifies the icon index or "shell32.dll:-1001" to to specifies the cursor index. Use zero-based index to specified the resource position, and negative value to specified the resource identifier. Empty filename (e.g. ",-1") to specified the current executable file.

If the resource is an icon/cursor group, the extra size parameter can be used to specified the desired display size. The function uses Windows API to search and return the best fits icon, or uses the SM_CXICON/SM_CXCURSOR system metric value as default value.

Notice: The function will not resize the image, so the real size of retruned icon image may not equal to your desired size.

proc IconImage(str: string; size = wDefaultSize): wIconImage {...}{.inline, discardable,
    raises: [wIconImageError], tags: [ReadIOEffect].}
Constructor. 
proc init(self: wIconImage; iconImage: wIconImage) {...}{.inline,
    raises: [wNilAccess, wIconImageError], tags: [].}
Initializes an icon image from wIconImage object, aka. copy. 
proc IconImage(iconImage: wIconImage): wIconImage {...}{.inline, discardable,
    raises: [wNilAccess, wIconImageError], tags: [].}
Constructor. 
proc isPng(self: wIconImage): bool {...}{.inline, raises: [], tags: [].}
Returns true if this is a PNG format icon image. 
proc isBmp(self: wIconImage): bool {...}{.inline, raises: [], tags: [].}
Returns true if this is a bitmap format icon image. 
proc toPng(self: wIconImage) {...}{.raises: [wNilAccess, Exception, wImageError],
                            tags: [RootEffect].}
Convert this icon image to PNG format. 
proc toBmp(self: wIconImage) {...}{.raises: [wNilAccess, Exception, wImageError],
                            tags: [RootEffect].}
Convert this icon image to bitmap format. 
proc getWidth(self: wIconImage): int {...}{.raises: [], tags: [].}
Gets the width of the icon image in pixels. 
proc getHeight(self: wIconImage): int {...}{.raises: [], tags: [].}
Gets the height of the icon image in pixels. 
proc getSize(self: wIconImage): wSize {...}{.inline, raises: [], tags: [].}
Returns the size of the icon image in pixels. 
proc getBitCount(self: wIconImage): int {...}{.raises: [], tags: [].}
Returns the bit count of the icon image. 
proc getHotspot(self: wIconImage): wPoint {...}{.raises: [], tags: [].}
Returns the cursor's hotspot. If this icon image is created from icon resource instead of cursor resource, the value is wDefaultPoint. 
proc setHotspot(self: wIconImage; hotspot: wPoint) {...}{.raises: [], tags: [].}
Set the coordinates of the cursor's hotspot. 
proc IconImages(data: pointer; length: int): seq[wIconImage] {...}{.raises: [], tags: [].}
Similar to IconImage() for binary data, but this function loads all image in the group and returns a seq. 
proc IconImages(str: string): seq[wIconImage] {...}{.raises: [], tags: [ReadIOEffect].}
Similar to IconImage(), but this function loads all image in the group and returns a seq. 
proc save(icons: openArray[wIconImage]; isIcon = true): string {...}{.raises: [], tags: [].}
Stores multiple icon images to a .ico or .cur format data depends on isIcon. 
proc save(self: wIconImage; isIcon = true): string {...}{.raises: [], tags: [].}
Stores single icon image to a .ico or .cur format data depends on isIcon. 
proc save(icons: openArray[wIconImage]; filename: string; isIcon = true) {...}{.
    raises: [IOError], tags: [WriteIOEffect].}
Stores multiple icon images to a .ico or .cur format file depends on isIcon. 
proc save(self: wIconImage; filename: string; isIcon = true) {...}{.raises: [IOError],
    tags: [WriteIOEffect].}
Stores single icon image to a .ico or .cur format file depends on isIcon.

Made with Nim.