Interface: colorMan

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

Note:

After making any color changes, you must call ‘colorMan.repaintUI #repaintAll’ to apply the changes, and synchronize with the customize dialog.

<boolean>useStandardWindowsColors()

Returns true if the standard windows colors are used and false if custom colors are used.

setUseStandardWindowsColors <boolean>onOff

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.

<boolean>onOff: Pass true to use the standard windows color and false to use the custom colors.

<boolean>registerColor <string>color <string>name <string>category <point3>defaultColor

This registers a new color with the system, and adds a color to the color manager database that is then accessible from the color customization UI. It returns false if the color is already registered; otherwise true.

<string>color: The ID of the color to register. Example: #myNewColor

<string>name: The name for the color. Example: "My Own Color"

<string>category: The category for the color. If the name passed matches one of the existing 3ds Max categories the color will be placed in there, otherwise a new one will be created. Example: "Fun Gaming Colors"

<point3>defaultColor: 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. Example: [1,0,0]

Example:

colorMan.registerColor #myNewColor "My Own Color" "Ugly Colors" [1,0,0]

This registers a new color, with the name #myNewColor, with a default value of red. The category in the customization UI will be "Ugly Colors" and the name will be "My Own Color".

In other scripts you can access this color using:

colorMan.getColor #myNewColor

Note:

colorMan.registerColor should be called from a script in the \stdplugs\stdscripts folder. These scripts are run when 3ds Max starts, so the color will be available in the customization UI immediately. If the user customizes this color, its value will be saved in the MaxColors.clr file.

 

<boolean>loadColorFile <filename>file

This method will load the specified color file from the current UI directory. Returns true if the load was successful, otherwise false.

<string>file: The filename of the color file to load.

Note:

The path specified must be relative to the \UI directory.

 

<boolean>saveColorFile <filename>file

This method will save the specified color file from the current UI directory. Returns true if the save process was successful, otherwise false.

<string>file: The filename of the color file to save.

Note:

The path specified must be relative to the \UI directory.

 

<filename>getColorFile()

Returns the file name of the current color file.

 

<boolean>setColor <string>color <point3>colorValue

Sets the color value of the previously registered color whose ID is passed. Returns true if the color was set and false if the id passed could not be found.

<string>color: Specifies which color to set.

<point3>colorValue: The color value to set.

Predefined colors include:

#background -- The background for all controls and buttons

#text -- The text for all controls and buttons

#activeCommand -- The color command mode buttons turn when pressed

#hilight -- The hilight color for 3d controls

#shadow -- The shadow color for 3d controls

#window -- The background color for edit boxes, list boxes and other windows

#activeCaption --

#toolTipBackground -- The background for viewport tool tips

#toolTipText -- The text color for viewport tool tips

#hilightText -- The hilight color in the stack view drop-down list

#windowText -- The color used in edit boxes, list boxes and other windows

#itemHilight --

#subObjectColor -- The color used to hilight sub-object levels in StackView

#3dDarkShadow -- the dark shadow color on 3d controls

#3dLight -- the light color on 3d controls

#appWorkspace --

#trackbarBg -- trackbar background

#trackbarBgSel -- trackbar background for selected keys

#trackbarText -- trackbar text

#trackbarTicks -- trackbar ticks

#trackbarKeys -- trackbar keys

#trackbarSelKeys -- track bar selected keys

#trackbarCursor -- track bar cursor

#pressedButton -- background color for pressed buttons, like the transform constraints

#timeSliderBg -- The background for the time slider bar.

#viewportBorder -- The viewport border color

#activeViewportBorder -- The active viewport border color

#rollupTitleFace -- Rollout title background

#rollupTitleText -- rollout title text

#rollupTitleHilight-- rollout title 3d highlight

#rollupTitleShadow -- rollout title 3d shadow

#selectionRubberBand -- the selection marquee color

#stackViewSelection -- the color of a selected item in stack view

 

<color>getColor <string>color

Returns the color value of the color whose ID is passed, or black (RGB(0,0,0)) if the Color passed was not found.

<string>color: Specifies which color to get.

 

<name>getName <string>color

Returns the name of the color whose ID is passed.

<string>color: The ID of the color.

 

<string>getCategory <string>color

Returns the category string of the color whose ID is passed.

<string>color: The ID of the color.

 

<boolean>setIconFolder <filename>folder

<string>folder - The name of the folder relative to the UI directory. Absolute pathnames are not supported.

This method sets the folder from which all icons for the UI are loaded, and immediately reloads the icons from that folder.

Note:

If a folder with no icon files is loaded, all icons in the UI become blank, and no warning is issued.

 

<filename>getIconFolder()

Returns the absolute pathname of the current icon folder. Note that getIconFolder returns an absolute path while setIconFolder accepts only relative paths.

 

<float>getIconColorScale <enum>type <enum>which

type enums: {#disabledIcon|#enabledIcon}

which enums: {#saturationScale|#valueScale|#alphaScale}

Returns a floating point value (in the range 0.0 to 1.0) 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.

<enum>type: One of the following values:

#disabledIcon: The disabled icons.

#enabledIcon: The enabled icons.

<enum>which: The icon color scale. One of the following values:

#saturationScale: The saturation scale.

#valueScale: The value scale.

#alphaScale: The alpha scale.

 

setIconColorScale <enum>type <enum>which <float>value

type enums: {#disabledIcon|#enabledIcon}

which enums: {#saturationScale|#valueScale|#alphaScale}

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.

<enum>type: The icon type. One of the following values:

#disabledIcon: The disabled icons.

#enabledIcon: The enabled icons.

<enum>which: The icon color scale. One of the following values:

#saturationScale: The saturation scale.

#valueScale: The value scale.

#alphaScale: The alpha scale.

<float>value: The value runs from 0.0 to 100.0.

getIconColorInvert <enum>type

type enums: {#disabledIcon|#enabledIcon}

Returns true if the invert flag is set for the specified icon type and false if not set.

<enum>type: The icon type. One of the following values:

#disabledIcon: The disabled icons.

#enabledIcon: The enabled icons.

 

setIconColorInvert <enum>type <boolean>value

type enums: {#disabledIcon|#enabledIcon}

Sets the invert flag for the specified icon type to on or off.

<enum>type: The icon type. One of the following values:

#disabledIcon: The disabled icons.

#enabledIcon: The enabled icons.

<boolean>value: Pass true for inverted; false for not inverted.

 

<filename>getFileName()

Returns the file name of the currently loaded color file.

Note:

This filename specifies an absolute path, even though loadColorFile and saveColorFile use relative paths.

<color>getDefaultColor <string>color

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.

<string>color: The ID of the color.

 

repaintUI <enum>type

type enums: {#repaintAll|#repaintTrackBar|#repaintTimeBar}

This method allows you to issue a repaint of the user interface. This is equivalent to the Apply Colors Now button in the Customize dialog.

<repaintType>type: The type of repaint you wish to issue; #repaintAll, #repaintTrackBar, #repaintTimeBar.

Here is a macroScript that turns the time slider and trackbar backgrounds blue:

Example:

macroScript BlueBar

category: "Color"

tooltip: "Blue Bar"

(

on execute do

(

colorMan.setColor #timeSliderBg [0, 0, .6]

colorMan.repaintUI #repaintTimeBar

colorMan.setColor #trackbarBg [0, 0, .6]

colorMan.repaintUI #repaintTrackBar

)

)

Note:

All of 3ds Max's standard icon BMP files must exist in that folder. If any of the standard files are missing, icons will appear blank in 3ds Max's UI. All the icons files needed live in the UI\Icons folder, which is the default icon folder.

The following methods were added to 3ds Max 9:

colorman.reInitIcons()

new.gif NEW in 3ds Max 9: 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.

<bool>colorman.resolveIconFolder <filename> <&fullfilename>

new.gif NEW in 3ds Max 9: 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 fullfilename and the method returns true. If not found, the method returns false.

 

 

See also Class IcolorManager, in the SDK Help file accompanying this product

 

See also

3ds Max User Interface Colors

Creating Icon Bitmap Files