Name
CreateIcon -- create an icon (V8.0)
Synopsis
[id] = CreateIcon(id, table)
Function
This function can be used to create an icon from a collection of individual image files or brushes. You have to pass the desired identifier for the new icon in the id parameter. If you specify Nil in the id argument, CreateIcon() will automatically choose a vacant identifier for this icon and return it to you.

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.

On top of the identifier for the new icon that is to be passed in id, you also have to pass a table in the table parameter to CreateIcon(). This table must contain a number of subtables, one for each image size you wish to add to the icon.

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 #BRUSH. Note that that default is different to the default used by the @ICON preprocessor command, which is #FILE.

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. 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. Also note that in every icon, each image size must only be used once, i.e. it is not possible to add two 48x48 images to a single icon. There can only be one image for each size 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 CreateIcon().

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.

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 default. 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 default. See Loaders and adapters for details. Obviously, this tag is only used when Type is set to #FILE.

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

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

Inputs
id
identifier for the icon or Nil for auto id selection
table
table containing the individual images to be added to the icon (see above)
Example
CreateIcon(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"}})
The code above creates icon 1 from a set of external images in different sizes ranging from 16x16 pixels to 1024x1024 pixels.


CreateIcon(1, {{Image = "icon.svg"}})
The code above creates icon 1 and uses just a single image because the image is in a vector graphics format (SVG) and in that case only a single image must be specified (see above).

Show TOC