Note: Icon loading and handling has changed significantly in 3ds Max 2017 to support multi-resolution icons for high-DPI/4K displays.
Your plug-ins can use icons in their user interfaces (e.g. command panels or menus). Icons are images that can be loaded from a pre-compiled RCC file, or from a PNG file on disk. In either case, you should supply multiple sizes that the system can select for optimum display depending on the display scaling. 3ds Max generally supplies icons in these sizes:
The naming convention is to specify the size after the icon name, such as Angle_24.png for the 24x24 version.
In code, this icon would be specified to MaxBmpFileIcon() simply as
myIcon = new MaxBmpFileIcon(_T("<path>/Angle"));
Here <path> is either a relative path to the file system or to a location in an RCC file registered with the system. If it's a path, the path is relative to the MaxRoot\UI_ln\Icons\[Light|Dark]\ directory. If it's a directory path (specified by starting with a colon, ':'), the RCC file must be registered before calling this method by using QResource::registerResource(). For more information, see MaxBmpFileIcon(). For an example of loading custom multi-resolution icons in a plug-in, using both file-based icons and a compiled RCC resource, see the sample project in maxsdk\\howto\\ui\\menudemo\\.
3ds Max loads icons from the compiled resources UI_ln/Icons[Dark|Light].rcc, depending on the active theme. Using an RCC file is the recommended method for plug-ins to distribute and load multi-resolution icons. For more information about the Qt Resource Compiler, see this link.
In UI_ln/Resources you will find .png versions of the current icon set. These are the same icons compiled into UI_ln/Icons[Light|Dark].rcc.
Note: This section describes the legacy method of loading and using icons.
3ds Max still supports the legacy icon loading method, and legacy icons are located in a couple of different places:
These icons are alpha-composited background icons and reside as *.bmp files in the \UI_ln\Icons folder. It is also possible for developers to integrate one or more resource based icons in their plug-in DLL file. In this case, those resource based icons will need to be converted to external icons and be stored as 24-bit image files with associated 24-bit alpha mask image files. The name of these files follow a fairly standard naming convention. As an example, the material editor icons and image files will be used for the following outline. The icon image files for this example can be found in the \UI\Icons folder as:
MeditImages_a.bmp* //The 24-bit icon alpha mask
MeditImages_i.bmp* //The 24-bit icon images
One difference with ordinary icon formats is that these use an alpha mask instead of an XOR mask. An XOR mask needs to be inverted in order to create a proper alpha mask out of it. The process for this is fairly straightforward; copy the images directly to a file (i.e. myicons_i.bmp ), invert the mask file and storing that in the associated file (i.e. myicons_a.bmp ). This process will result in icons which are identical to the XOR masked versions. Of course, you can also tweak the alpha mask to give it fuzzy edges and other effects you might like for your icons to help composite with the background color in a seamless and smooth way.
In the plugin code you will need to create image lists for the icons. Once again, taking the material editor as an example, you can create the image list in the following manner:
hMeditImages = ImageList_Create(BUTW, BUTH, ILC_COLOR24 | ILC_MASK, 5, 0);
LoadMAXFileIcon("MeditImages", hMeditImages, kBackground, FALSE);
The first thing we do is to create an image list with 24-bit images and a mask. Next, we need to call LoadMAXFileIcon()to load the images into the image list. See below for more information on this function.
If you want your icons to respond when the user customizes colors, you will need to implement a color change callback to reload the icons. This is not required, but it does enable your UI to integrate well with the color customization system. You need to create a callback as outlined below:
staticvoidColorChangeNotifyProc(void* param, NotifyInfo* pInfo) { ImageList_RemoveAll(hMeditImages); LoadMAXFileIcon("MeditImages", hMeditImages, kBackground, FALSE); }
Then you will need to register it after you load the icons for the first time:
RegisterNotification (ColorChangeNotifyProc, NULL, NOTIFY_COLOR_CHANGE);
This way your buttons will always look correct when the user starts customizing colors.
When using the dark color scheme for the icons, 3ds Max automatically darkens the bitmap based icons. This might result in poor readability of the icons. In order to increase the readability of the icons in such case, a set of dark icons optimized for the dark color scheme are provided in an icon folder called <3dsMax_Root>\UI\IconsDark . 3ds Max looks into this folder for dark icons first, and falls back to <3dsMax_Root>\UI\Icons if it can't find any dark icons in the former location.
This change may impact the way that your plug-in icons are displayed when 3ds Max uses the dark color theme. The following scenarios illustrate some types of problems you may encounter, and the corresponding solutions.
Make sure your plug-in always loads the icons from <3dsMax_Root>\UI_ln\Icons using class MaxBmpFileIcon and install your icons (the same set) in both <3dsMax_Root>\UI_ln\Icons and <3dsMax_Root>\UI_ln\IconsDark . This class will look for icons in the folder that corresponds to the current color theme used by 3ds Max.
Install a set of icons optimized for the dark color scheme into <3dsMax_Root>\UI_ln\IconsDark and make sure your plug-in uses class MaxBmpFileIcon to retrieve the right set of icons, or load the icons from the location supplied by theIColorManager::GetIconFolder() method.
In some cases plug-ins manage icons as Window resources and manually handle the loading of icons instead of using the MaxBmpFileIcon class. To make sure your plug-in starts up with the correct icons (matching Max's color theme) you can call AppFrameColorTheme IColorManager::GetAppFrameColorTheme(). The plug-in can also subscribe to the NOTIFY_APP_FRAME_THEME_CHANGED notification (see maxsdk\\include\\notify.h) in order to react to changes in the 3ds Max color theme.