@ICON id, filename$[, table]
@ICON id, table

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. 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.

Furthermore, images inside Hollywood icons can also be specifically designed for different color depths. For example, you can provide 24x24 images in various color depths, e.g. in 256 colors (8 bits) and in true color with alpha channel (32 bits). Thus, it is possible to have images of the same size inside an icon as long as they differ in their color depth. This once again gives Hollywood the advantage of choosing the best image from an icon for a certain screen resolution and color depth.

Finally, 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.

This preprocessor command can be used in two different ways: You can either specify a single file in filename$ to be loaded as a Hollywood icon or you can specify a table to create a Hollywood icon from individual images which may be specified as either brushes or external files.

In case you use the first syntax, i.e. you pass a single file in filename$, @ICON expects the file to be in Hollywood's custom PNG icon format and @ICON does the same as the LoadIcon() command in that case, except that the icon is preloaded and will be linked to the applet or executable on compiling. See LoadIcon for details.

The first syntax also accepts a table argument that follows the filename$ parameter. The following fields in the table can be set in case you use the first syntax:

Link:

Set this field to False if you do not want to have this icon linked to your executable/applet when you compile your script. This field defaults to True which means that the icon is linked to your executable/applet when Hollywood is in compile mode.

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)

Alternatively, you can use the second syntax which allows you to create an icon from a set of source images which may either be external files or Hollywood brushes. In that case, you have to specify a single table argument which must contain a number of subtables, one for each image size you wish to add to the icon. This is similar to the way the CreateIcon() command works. See CreateIcon for details.

The individual subtables can use the following tags:

Type:

This tag allows you to set the source type of the image you wish to add to the icon. This can be #BRUSH if you want to add a brush, or #FILE if you would like to add an image from an external file source. The default is #FILE. Note that that default is different to the default used by CreateIcon() and AddIconImage(), which is #BRUSH.

Image:

This tag specifies the actual image source and must be set in every subtable. If Type has been set to #BRUSH, you have to set this tag to the identifier of a brush you want to add to the icon. The brush can be an RGB or palette brush. Otherwise, Image needs to be set to the path of an image file that should be added to the icon. The image file may be in any of the image file formats supported by Hollywood. Note that if the image file specified here has an alpha channel, the alpha channel data is loaded automatically. If it is a palette image and the LoadPalette tag is set to True (see below), the image's transparent pen will also be loaded automatically. Also note that in every icon, each image size must only be used once for each color depth, i.e. it is not possible to add two 48x48 images that use the same color depth to a single icon. There can only be one image for each size and color depth in every icon. Note that if the image you specify here is in a vector graphics format, i.e. either a vector brush or a file in a vector image format, you mustn't pass any other images because in the case of vector graphics, one image is used for all sizes and Hollywood will automatically render it to all sizes it needs. So if you use vector instead of raster graphics, there must only be one subtable in the table you pass to @ICON.

SelImage:

This tag allows you to include an additional image that should be used as a selected version of the image specified in Image. This tag is optional. If you set it, the image specified here must be of exactly the same size as the one specified in Image. Besides that, SelImage is used in the very same way as Image, i.e. it depends on the image type set in Type what you have to pass here, either a brush identifier or a path to an external image file.

Standard:

This tag allows you to set the image specified in this subtable as the standard size for the icon. Setting a standard size is important in some contexts, so that Hollywood knows which image to pick for higher resolutions, e.g. if you designate a 64x64 image inside an icon as the standard size, Hollywood knows to pick the 128x128 image in case the monitor's resolution uses a DPI setting that is twice as high as the normal setting. Obviously, there can be only one standard image inside every icon, so setting this tag to True twice will result in an error. Also note that it is not necessary to declare a standard icon size, but for many use cases it is recommended to do it.

Link:

Set this field to False if you do not want to have the image files specified in Image and SelImage linked to your executable/applet when you compile your script. This field defaults to True which means that the image files specified in Image and SelImage will be linked to your executable/applet when Hollywood is in compile mode. Obviously, this tag is only used when Type is set to #FILE.

Loader:

This tag allows you to specify one or more format loaders that should be asked to load the image files specified in Image and SelImage. If specified, 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. Obviously, this tag is only used when Type is set to #FILE.

Adapter:

This tag allows you to specify one or more file adapters that should be asked to open the files specified in Image and SelImage. If specified, 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. Obviously, this tag is only used when Type is set to #FILE.

LoadPalette:

If this tag is set to True and Type is set to #FILE, Hollywood will try to load the image's palette and store the image as a palette image within the icon. If the image has a transparent pen, that transparent pen will be loaded automatically. (V9.0)

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)

To load or create icons at runtime, take a look at the LoadIcon() and CreateIcon() commands.

To add and remove individual images from an icon, use the AddIconImage() and RemoveIconImage() functions.

id

a value that is used to identify this icon later in the code

filename$

optional: the icon file you want to load (see above)

table

optional or mandatory, depending on which syntax you use (see above for a discussion)

@ICON 1, "MyIcon.png"

@ICON 1, {
    {Image = "ic16x16.png"},
    {Image = "ic24x24.png"},
    {Image = "ic32x32.png"},
    {Image = "ic48x48.png"},
    {Image = "ic64x64.png"},
    {Image = "ic96x96.png"},
    {Image = "ic128x128.png"},
    {Image = "ic256x256.png"},
    {Image = "ic512x512.png"},
    {Image = "ic1024x1024.png"}}

@ICON 1, {{Image = "icon.svg"}}