[id] = LoadIcon(id, filename$[, table])

In Hollywood, an icon is a collection of the same image in different sizes. By using individually designed images for each size instead of just scaling one and the same image to each size, a better quality is achieved, especially when it comes to smaller image sizes, which look much better when they are specifically designed for their resolution. Additionally, each image inside an icon set can have two different states: normal and selected. Normally, you only ever need the normal state, but on AmigaOS and compatibles the selected state is sometimes used as well. Typical sizes for the individual images within an icon are 16x16, 24x24, 32x32, 48x48, 64x64, 96x96, 128x128, 256x256, and 512x512, but they can also be completely arbitrary. The advantage of having the same image in different sizes in an icon is that Hollywood can choose an appropriate size depending on the screen resolution.

The icon passed in filename$ must be in Hollywood's custom PNG icon format. You can use SaveIcon() to create such icons. Note that although Hollywood icons are normal PNG images, they contain additional metadata which is why you mustn't edit them with your favourite image manipulation tool because that might lead to the loss of said metadata. Hollywood icons should only ever be created by using the SaveIcon() function.

If you don't want to use Hollywood's custom icon format, you can also create icons from brushes or normal images using the CreateIcon() function or the @ICON preprocessor command. Those commands also have the advantage that you can use vector brushes, which can be losslessly scaled to any size, leading to a perfectly crisp look in all kinds of different resolutions.

The third argument is optional. It is a table that can be used to set further options for the loading operation. The following fields of the table can be used:

Loader:

This tag allows you to specify one or more format loaders that should be asked to load this icon. This must be set to a string containing the name(s) of one or more loader(s). Defaults to the loader set using SetDefaultLoader(). See Loaders and adapters for details.

Adapter:

This tag allows you to specify one or more file adapters that should be asked to open the specified file. This must be set to a string containing the name(s) of one or more adapter(s). Defaults to the adapter set using SetDefaultAdapter(). See Loaders and adapters for details.

UserTags:

This tag can be used to specify additional data that should be passed to loaders and adapters. If you use this tag, you must set it to a table of key-value pairs that contain the additional data that should be passed to plugins. See User tags for details. (V10.0)

This command is also available from the preprocessor: Use @ICON to preload icons.

id

identifier for the icon or Nil for auto id selection

filename$

file to load

table

optional: further options (see above)

id

optional: identifier of the icon; will only be returned when you pass Nil as argument 1 (see above)

LoadIcon(1, "test.png")