MAXScript has full access to the menu manager and menu creation system.
Anyone using this API should make a copy of the "..\UI\MaxStartUI.mnu" file before running any of the scripts. If anything messes up, just copy the backup version back on to MaxMenu.mnu.
There are 4 exposed interfaces to MAXScript: the menu manager, menu objects, quad menu objects and menu items.
A menu item can be a separator, an action that invokes a macroScript or a sub-menu that pops up a cascading menu.
This loads a new menu file with the given name. It looks in the current "UI" directory for the file. It return true if successful, and false if not.
This saves a new menu file with the given name. It saves it in the current "UI" directory.
Returns the full path to the current menu file.
This updates the main menu bar with any changes that have been made. This MUST be called after changing anything on the main menu bar.
This call is used to register menu extensions. The "contextId" is a random 32-bit integer. It can be generated using the "genclassid()". This function registers an extension with the menu manager that is remembered permanently. It returns true the first time the extension is registered, and false every time thereafter. This is saved in the MaxMenu.mnu file, so it is sticky from session to session. This is used so that scripts can add items and sub-menus MAX's main menu bar and quad menus. See the sample scripts below for the proper usage.
This function returns the menu with the given name. It returns "undefined" if no menu exists in the menu manager with the given name. This requires the full name of the menu, including and "&" characters that might be in the name.
This method works like "findMenu" but it gets quad menus instead of menus.
This method removes a menu from the menu manager.
WARNING! USE EXTREME CAUTION WHEN USING THIS METHOD! |
If you unregister a menu that is used as a sub-menu, or in a quad menu, or the main menu bar, you will corrupt your 3ds Max installation. |
This method works like "unregisterMenu" but for quad menus.
This method creates a new, empty menu with the given name.
This method creates a new, empty quad menu. It contains, 4 empty menus, one for each quad.
This method creates a new sub-menu item that can be added to a menu. It uses the given "name" and it displays the given sub-menu.
This method creates a new menu separator that can be added to a menu.
This method creates a new menu item that can be added to a menu. The item is an action that executes the macro script with the given name and category. This returns "undefined" if there is no macroScript with the given name and category.
This method sets the viewport right click menu to be the given quad menu. The value of "which" can be one of the following:
#nonePressed #shiftPressed #altPressed #controlPressed #shiftAndAltPressed #shiftAndControlPressed #controlAndAltPressed #shiftAndAltAndControlPressed
The following example sets the default (no keys pressed) quad menu the "Modeling 2". The menu name must be a quad menu that is listed in the "Quads" customization dialog, and the name must match exactly, including capitalization. menuMan.SetViewportRightClickMenu returns FALSE if you try to set the viewport right-click menu to a menu that is not allowed.
Retrieves the quad menu used for right-clicking in the viewport. The "which" parameter can be one of the following:
#nonePressed #shiftPressed #altPressed #controlPressed #shiftAndAltPressed #shiftAndControlPressed #controlAndAltPressed #shiftAndAltAndControlPressed menuMan.getMainMenuBar()
Returns the menu being used as MAX's main menu bar.
Sets the menu being used as MAX's main menu bar. You must call "menuMan.updateMenuBar()" in order to see the result.
Gets the "show all quads" setting for the given quad menu.
This sets the "show all quads" flag for the given quad menu. "value" can be true or false .
This returns the name of the given quad menu.
This sets the name of the give quad menu.
Returns the total number of menus in registered with the menu manager.
Retrieves the "index"th menu in the menu manager. This is a 1-based index.
Returns the total number of quad menus registered with the menu manager.
Retrieves the "index"th quad menu in the menu manager. This is a 1-based index.
Quad menu objects have the following functions available:
Retrieves the menu object associated with the 4 quads of the menu. "quadIndex" can take the value 0, 1, 2, or 3. Quad 0 is the lower-right, and they are numbered counter-clockwise from there.
This displays the quad menu. If "showAllQuads" is true, then all 4 quads are shows at once. It is displayed at the current cursor position.
Menus are containers for menu items, and have the following functions:
Sets the title of the menu to the give string.
Returns the current title of the menu.
Returns the number of items the menu holds.
Retrieves the menu item at the given index.
This inserts an item in the menu at the given position, which is 0-based. If the position is -1, then the item is appended to the end of the menu.
This removes the item at the given position.
This removes the given item from the menu, if it is in the menu.
A menu item can be a separator, a sub-menu or an action that is connected to a macroScript. The following functions are available for menuItems:
Sets the name associated with the item.
Returns the name associated with the item.
When value is true, this tells an item that is associated with a macroScript to use the item title when displaying the menu. Otherwise it will use the name of the macro or the "buttontext" of the macroScript.
Returns the current value of the custom title flag.
This is for sub-menu items. When value is true, it tells the menu to display the sub-menu in-line, rather than as a cascading sub-menu.
Returns the current value for the "display flat" flag.
Return true if the item is a separator, and false otherwise.
If the item is a sub-menu item, this returns the menu associated with the sub-menu.
Included below is a script that shows how to use the menuMan interface to register menu extensions. This script should go in the "stdplugs\stdscripts" folder.
EXAMPLE: |
-- This example adds a new entry to MAX's main "Help" menu. -- Register a menu context. This returns true the first time it -- is registered, and we can add things to the menu. If -- it returns false, then the context is already registered, -- and the items are already in the menu. -- The number 0x246c6dbe is random, and can be generated -- using the genClassID() function. if menuMan.registerMenuContext 0x246c6dbe then ( -- Get the main menu bar local mainMenuBar = menuMan.getMainMenuBar() -- The help menu is always the last menu. local helpMenuIndex = mainMenuBar.numItems() -- Get the menu item that holds the help menu local helpMenuItem = mainMenuBar.getItem(helpMenuIndex) -- Get the menu from the item local helpMenu = helpMenuItem.getSubMenu() -- create a menu separator item local sepItem = menuMan.createSeparatorItem() -- create a menu items that calls the sample macroScript local testItem = menuMan.createActionItem "MyTest" "Menu Test" -- Add the separator to the end of the help menu. -- the position of -1 means add it to the end. helpMenu.addItem sepItem -1 -- Add the action item to the end of the help menu. helpMenu.addItem testItem -1 -- redraw the menu bar with the new item menuMan.updateMenuBar() ) |
Here are two macroScripts that set and reset two of the right-click menus: