Module menus

Because Sketchup's Ruby API doesn't provide any way of finding out whether a menu item already exists or not, it can be difficult to avoid adding your menu items more than once when you reload your scripts.

The menus module provides some facilities to make this easier. It remembers what menu items you've already created and avoids adding them a second time, while still allowing you to update the command and validation procedures attached to them. Furthermore, it remembers this information across calls to Py.refresh, so you can easily reload your scripts without worrying about creating duplicate menu items.

See example.py for an example of using the menus module.

Functions

get_menu(title): Returns a Menu instance representing the top-level Sketchup menu with the given title. The title must be the name of one of the built-in menus. Once you have the Menu object, you can use its methods to add items, submenus and separators.
add_context_menu_handler(handler, name = None): Installs a contextual menu handler. Whenever a contextual menu is popped up, the handler will be called with a Menu instance to which it may add items.

If a handler has already been installed under the same name, the previous handler is replaced. This allows you to reload your scripts without previous versions of your handlers piling up.

In the usual case where the handler is a Python function, a default name is constructed from the function's name and the name of the module where it is defined, so you only have to specify a name explicitly if you're using some other kind of callable object.

Class Menu

This is a Python class that represents a Sketchup menu or submenu.

Methods

add_item(label, action = None, validator = None)

Adds an item to the menu or updates an existing item. If an item with the given label does not exist, a new one is added, otherwise the action and validator functions of the existing one are updated. Returns a MenuItem instance representing the new or existing item.

The action should be a function of no arguments; it is called when the menu item is invoked by the user.

The validator should be a function of no arguments that returns an integer. It is called whenever Sketchup needs to determine the state of the menu item. The return value is a bit mask made up by adding together the following values, available as constants in the menus module:

DISABLE = 1	Disables the menu item
CHECK = 8	Causes a check mark to appear beside the item

If the validator returns None, the menu item is enabled and unchecked.

add_submenu(label)

Adds a submenu to the menu if one does not already exist with the given label. Returns a new or existing Menu instance.

add_separator()

Causes a separator to be inserted before any following items. A separator is only added if subsequent operations actually cause a new item to be added to the menu.

Class MenuItem

This is a Python class representing a menu item. You can change the action and validation functions by assigning to the following attributes.

Attributes

action: The action function associated with the menu item.
validator: The validation function associated with the menu item.