Creating Icon Bitmap Files

An icon bitmap file can have any number of individual icons, which are lined up side-by-side in the file.

Note: This topic describes a legacy icon format. See Defining Macro Scripts for a description of the newer method that supports multi-resolution icons.

If you are creating icon bitmap files, these files must meet the following requirements:

Icon bitmap files must be .bmp files.
The icon bitmap files are actually groups of files. For each icon bitmap file group there needs to be at least two image files: one containing 16x15 pixel images ending in _16i.bmp, and another containing 24x24 pixel images ending in _24i.bmp. For example, these files would be myicons_16i.bmp and myicons_24i.bmp .

Note:

The 16x15 size requirement is not a typo, the small icons are actually displayed as 15 pixels high. Some shipping icon files have been created with a height of 16 pixels - in such cases, the last pixel row will be clipped. It is suggested that you set the height of your icon files to 15 pixels to make sure the complete image is visible.

All icon images in an icon bitmap file must be the same size, as defined by the file name suffix.
Each icon bitmap file group must contain similar icon images in the same order. This allows a single index to locate the desired bitmap, independent of which button size option the user has chosen.
If monochrome, Windows-compatible masks are available, they need to be stored in files ending in _16m.bmp and _24m.bmp. For example, these files would be myicons_16m.bmp and myicons_24m.bmp .
If 8-bit alpha channel data is available, it needs to be stored in _XXa.bmp files if the alpha is not premultiplied, and in _XXp.bmp files if the alpha is premultiplied, where XX is either 16 or 24. For example, these files would be myicons_16a.bmp and myicons_24a.bmp .
If the mask channel bitmap files are present, they are used. If the mask channel bitmap files are not present, then the alpha channel bitmap files are used. If neither the mask nor alpha channel data bitmap files are present, then the color of the upper-left pixel is deemed the transparent color, and a mask is generated automatically for the image bitmaps.

If you wish to generate icons via calls to render() in MAXScript, make sure you use the naming conventions previously described and place the .bmp files in the current 3ds Max user-interface directory. You can get the current user-interface directory path with the function:

local ui_dir = cui.getDir ()

In 3ds Max 9 and higher, CUI icon files (*_16i.bmp, *_16a.bmp, *_24i.bmp, *_24a.bmp) are loaded first from the user icon directory, then the max system icon directory, and then <3dsmax.exe>\ui\icons. If a file set is present in multiple directories, the version in the first directory is used.

In 3ds Max 9 and higher, the icon filename specified as an argument to loadPicture, the filename in images arrays for UI items, and the filename for the bitmap UI item no longer needs to specify a path to the icon folder. The icon filename will be searched for in the following directories (in order):

The directory associated with the current mzp package, if any.

The directory associated with the calling script

The user icon directory

The max system icon directory

< 3dsmax.exe >\ui\icons

The user startup scripts directory

The user scripts directory

The max system startup scripts directory

The max system scripts directory

The map path directories

The image directory

The 3DS executable main directory

The Windows NT 32-bit system directory (system32)

The Windows 16-bit system directory (system)

The Windows directory

The directories that are listed in the PATH environment variable

The following methods are useful when working with custom icons files:

colorman.reInitIcons()

Reloads all CUI icons from the icon files. This can be used to refresh the UI after adding new or editing existing icon bitmap files.

Available in 3ds Max 9 and higher.

<boolean>colorman.resolveIconFolder <filename>filename <&string>path
       path is Out parameter

This method resolves the filename using the user icon path, then the system icon path, and then <3dsmax.exe>\ui\icons. If the file is found, fully qualified filename is placed in full filename and the method returns true. If not found, the method returns false.

Available in 3ds Max 9 and higher.