Class IColorManager
See Also: Class FPStaticInterface Class Point3, COLORREF, List of Standard Color IDs, Generate a Class_ID, Class GUP, Getting and Setting User Preferences.
class IColorManager : public FPStaticInterface
Description:
This class is available in release 4.0 and later only.
This class is an interface to the Color Manager. Within 3ds max using the Customize pull down menu / Customize User Interface choice / Colors tab a user is able to alter the colors used for various UI elements. They can change the saturation, value and transparency of elements, and load and save color schemes.
Using the methods of this class developers can do the same (the 3ds max color manager uses this class internally). Developers can add their own named custom colors. Developers wanting to do this need to pick a random 32-bit ColorId to identify it. (Note: typedef DWORD ColorId;). The Class_ID generator may be used for this where only one of the two DWORDS is used. See Class Class_ID for more details. The low integer ColorIds are reserved for 3ds max internal use. These colors should be registered on startup, so a Global Utility Plug-In (GUP) is the best way to handle this. See Class GUP for details. Methods that are marked as internal should not be used.
The following global functions are not part of this class but are available for use:
Function:
IColorManager* GetColorManager();
Remarks:
This global function is available in release 4.0 and later only.
Returns a pointer to the color manager with which you can call the methods of this class.
Note the following #define which may be used to simplify coding a bit:
#define ColorMan() (GetColorManager())
Methods:
public:
Prototype:
virtual bool UseStandardWindowsColors() = 0;
Remarks:
Returns true if the standard windows colors are used and false if custom colors are used.
Prototype:
virtual void SetUseStandardWindowsColors(bool useStandardColors) = 0;
Remarks:
Sets whether standard windows colors are used or not. This allows the developer to tell the system to use standard windows colors, instead of the custom colors. This only affects calls to CustSysColor() and not GetColor().
Parameters:
bool useStandardColors
Pass true to use the standard windows color and false to use the custom colors.
Prototype:
virtual bool RegisterColor(ColorId id, TCHAR* pName, TCHAR* pCategory, COLORREF defaultValue) = 0;
Remarks:
This method registers a new color with the system. For plug-in developers this should be done at startup using a Global Utility Plug-in which calls this method. See the Description section above for details. If developers want to add a color of their own, they need to pick a random 32-bit integer ColorId to identify it.
Parameters:
ColorId id
The ID of the color to register. This should be generated by the developer using a single DWORD from the output of the Class_ID program. See Class Class_ID for more details.
TCHAR* pName
The name for the color.
TCHAR* pCategory
The category for the color. If the name passed matches one of the existing 3ds max categories the color will be place in there, otherwise a new one will be created.
COLORREF defaultValue
The default value for the color. This is the value that the color will be reset to when a 3ds max user presses "Reset" in the color customization dialog. See COLORREF.
Return Value:
Returns false if the color is already registered; otherwise true.
Prototype:
virtual BOOL LoadColorFile(TCHAR* pFileName) = 0;
Remarks:
This method will load the specified color file from the current UI directory.
Parameters:
TCHAR* pFileName
The filename of the color file to load.
Return Value:
TRUE if the load was successful, otherwise FALSE.
Prototype:
virtual BOOL SaveColorFile(TCHAR* pFileName) = 0;
Remarks:
This method will save the specified color file from the current UI directory.
Parameters:
TCHAR* pFileName
The filename of the color file to save.
Return Value:
TRUE if the save process was successful, otherwise FALSE.
Prototype:
virtual TCHAR* GetColorFile() = 0;
Remarks:
This method returns the file name of the current color file.
Prototype:
virtual bool SetColor(ColorId id, COLORREF color) = 0;
Remarks:
Sets the color value of the previously registered color whose ID is passed.
Parameters:
ColorId id
Specifies which color to set.
COLORREF color
The color value to set. See COLORREF.
Return Value:
Returns true if the color was set and false if the id passed could not be found.
Prototype:
virtual COLORREF GetColor(ColorId id) = 0;
Remarks:
Returns the color value of the color whose ID is passed.
Parameters:
ColorId id
Specifies which color to get.
Return Value:
The color is returned or black (RGB(0,0,0)) if the ColorId passed was not found.
Prototype:
virtual Point3 GetColorAsPoint3(ColorId id) = 0;
Remarks:
This method returns the color associated with a specified color ID as a Point3.
Parameters:
ColorId id
The ID of the color you wish to get.
Prototype:
virtual HBRUSH GetBrush(ColorId id) = 0;;
Remarks:
Returns a handle to the brush for the color whose id is specified. NULL is returned if the id passed is not found. Note that the color manager does resource management for brushes, so the value returned should not be deleted.
Parameters:
ColorId id
The color whose brush handle is returned.
Prototype:
virtual TCHAR* GetName(ColorId id) = 0;
Remarks:
Returns the name of the color whose ID is passed.
Parameters:
ColorId id
The ID of the color.
Prototype:
virtual TCHAR* GetCategory(ColorId id) = 0;
Remarks:
Returns the category string of the color whose ID is passed.
Parameters:
ColorId id
The ID of the color.
Prototype:
virtual COLORREF CustSysColor(int which) = 0;
Remarks:
This method takes the specified windows color definition (for example COLOR_BTNHILIGHT) and returns the 3ds max customized version of that color. Anyone writing a plug-in with custom windows code should use this call (and CustSysColorBrush() below) instead of the Win32 GetSysColor() and GetSysColorBrush() if they want to participate in the 3ds max custom color scheme.
Note the following #define which may be used to simplify coding:
#define GetCustSysColor(which) (ColorMan()->CustSysColor(which))
Parameters:
int which
Specifies the windows color definition. See List of Standard Color IDs. For a full list of windows color definitions, please refer to the Win32 API, in particular the methods GetSysColor() and SetSysColor().
Prototype:
virtual HBRUSH CustSysColorBrush(int which) = 0;
Remarks:
This method returns a handle identifying a logical brush that corresponds to the specified color index. Note that the color manager does resource management for brushes, so the value returned should not be deleted.
Parameters:
int which
Specifies the windows color definition. See List of Standard Color IDs. For a full list of windows color definitions, please refer to the Win32 API, in particular the methods GetSysColor() and SetSysColor().
Note the following #define which may be used to simplify coding a bit:
#define GetCustSysColorBrush(which) (ColorMan()->CustSysColorBrush(which))
Prototype:
virtual Point3 GetOldUIColor(int which) = 0;
Remarks:
Returns the specified color value for drawing various items in the viewports. This is the same as the previous GetUIColor() function.
Parameters:
int which
Specifies which color to retrieve. See List of Viewport Drawing Color Indices.
Return Value:
The color as a Point3.
Prototype:
virtual COLORREF GetOldUIColorCOLORREF(int which) = 0;
Remarks:
This method returns the color associated with a user interface color as a COLORREF.
Parameters:
int which
The UI color index (see gfx.h).
Prototype:
virtual void SetOldUIColor(int which, Point3 *clr) = 0;
Remarks:
Sets the specified color value for drawing various items in the viewports. This is the same as the previous SetUIColor() function.
Parameters:
int which
Specifies which color to retrieve. See List of Viewport Drawing Color Indices.
Point3 *clr
Points to the color value to set.
Prototype:
virtual Point3 GetOldDefaultUIColor(int which) = 0;
Remarks:
Returns the default color used for drawing various items in the 3ds max user interface. The values returned are not affected by the user's color selections or those set by SetUIColor(). This is the same as the previous GetDefaultUIColor() function.
Parameters:
int which
Specifies which color to retrieve. See List of Viewport Drawing Color Indices.
Prototype:
virtual float GetIconColorScale(IconType type, IconColorScale which) = 0;
Remarks:
Returns a floating point value (in the range 0.0f to 1.0f) that is one of the scale factors applied to the specified icon type. These scale values used to do image processing on the icons at start-up time.
Parameters:
IconType type
The icon type. One of the following values:
kDisabledIcon
The disabled icons.
kEnabledIcon
The enabled icons.
IconColorScale which
The icon color scale. One of the following values:
kSaturationScale
The saturation scale.
kValueScale
The value scale.
kAlphaScale
The alpha scale.
Prototype:
virtual void SetIconColorScale(IconType type, IconColorScale which, float value) = 0;
Remarks:
Sets the specified scale factor for the icon type passed. The color manager maintains the values for the 3ds max icon image processing system. Developers can set values to scale the saturation, value and transparency for enabled and disabled icon images using this method.
Parameters:
IconType type
The icon type. One of the following values:
kDisabledIcon
The disabled icons.
kEnabledIcon
The enabled icons.
IconColorScale which
The icon color scale. One of the following values:
kSaturationScale
The saturation scale.
kValueScale
The value scale.
kAlphaScale
The alpha scale.
float value
The value to set (in the range 0.0f to 1.0f).
Prototype:
virtual bool GetIconColorInvert(IconType type) = 0;
Remarks:
Returns true if the invert flag is set for the specified icon type and false if not set.
Parameters:
IconType type
The icon type. One of the following values:
kDisabledIcon
The disabled icons.
kEnabledIcon
The enabled icons.
Prototype:
virtual void SetIconColorInvert(IconType type, bool value) = 0;
Remarks:
Sets the invert flag for the specified icon type to on or off.
Parameters:
IconType type
The icon type. One of the following values:
kDisabledIcon
The disabled icons.
kEnabledIcon
The enabled icons.
bool value
Pass true for inverted; false for not inverted.
Prototype:
virtual BOOL SetIconFolder(TCHAR* pFolder) = 0;
Remarks:
This method takes the name of a folder that must be in 3ds max "UI" folder. If the folder exists, then it sets 3ds max icon folder to point to it, and redraws the UI with those new icons.Warning: All of the 3ds max standard icon BMP files must exist in that folder. If any of the standard files are missing, icons will appear blank in the UI. All the icons files needed live in the UI\Icons folder, which is the default icon folder.
Parameters:
TCHAR* pFolder
The icon folder to set.
Prototype:
virtual void InitSystemColors() = 0;
Remarks:
This method is used internally to initialize the colors used by the system to their default values. This should not be called by third party developers.
Prototype:
virtual IColorManager* Copy() = 0;
Remarks:
This method is used internally. It makes a copy of the color database that the UI changes, and then it copies it back to the original to commit the changes. Third party developers won't need to call this.
Prototype:
virtual TCHAR* GetFileName() = 0;
Remarks:
Returns the file name of the currently loaded color file.
Prototype:
virtual COLORREF GetDefaultColor(ColorId id) = 0;
Remarks:
Returns the default color for the specified ID. The default color is the value passed as defaultValue in RegisterColor(), regardless if a SetColor() has been done subsequently. This is used by the UI when the user presses "Reset" to reset a color to its default value.
Parameters:
ColorId id
The ID of the color.
Prototype:
virtual COLORREF GetOldUIColorCOLORREF(int which) = 0;
Remarks:
Returns the specified color value for drawing various items in the viewports as a COLORREF.
Parameters:
int which
Specifies which color to retrieve. See List of Viewport Drawing Color Indices.
Prototype:
virtual void RepaintUI(RepaintType type) = 0;
Remarks:
This method allows you to issue a repaint of the user interface.
Parameters:
RepaintType type
The type of repaint you wish to issue; kRepaintAll, kRepaintTrackBar, kRepaintTimeBar.
The following global functions are used internally and should not be called by plug-in developers
IColorManager* CreateColorManager(TCHAR* pDefaultColorFile);
void DeleteColorManager(IColorManager* pColorMan);
void SaveColors();