Layered Menus¶

The LayeredMenuAPI allows users to define and register custom menus for the Node Graph tab that appear and behave in the same way as the built-in node creation menu that is shown when pressing the Tab key. These custom menus are named layered menus, as they appear in a menu layer on top of the nodes that make up the node graph of a Katana project.

The entries that are shown for a layered menu can be customized with an arbitrary text and a color per entry. When entering text while a layered menu is shown, its entries are filtered based on the entered text, just like entries of the node creation menu are filtered when entering the name of a node type.

When an entry from a layered menu is chosen, custom Python code can be executed. One common use case for layered menus is the ability to create and configure nodes of certain types based on a pre-defined or dynamic list of menu entries for the user to choose from.

Layered menus can be registered from UIPlugins scripts using this API.

LayeredMenuAPI.GetLayeredMenu(layeredMenuID)¶

Return type:	`LayeredMenu` or `None`
Parameters:	layeredMenuID (`str`) – The ID that uniquely identifies the layered menu to return.
Returns:	The layered menu with the given ID, or `None` if no layered menu with the given ID has been registered.

LayeredMenuAPI.GetLayeredMenuIDs()¶

Return type:	`list` of `str`
Returns:	A list of unique IDs of layered menus that have been registered using `RegisterLayeredMenu`.

class LayeredMenuAPI.LayeredMenu(populateCallback, actionCallback, keyboardShortcut, alwaysPopulate=False, onlyMatchWordStart=True)¶

Bases: object

Class implementing a layered menu that contains layered menu entries.

__dict__ = dict_proxy({'__module__': 'UI4.Tabs.LayeredMenuAPI', 'onlyMatchWordStart': <function onlyMatchWordStart at 0x7f3460ec25f0>, 'getKeyboardShortcut': <function getKeyboardShortcut at 0x7f3460ec2500>, 'alwaysPopulate': <function alwaysPopulate at 0x7f3460ec2578>, '__weakref__': <attribute '__weakref__' of 'LayeredMenu' objects>, 'clear': <function clear at 0x7f3460ec27d0>, 'isPopulated': <function isPopulated at 0x7f3460ec26e0>, '__dict__': <attribute '__dict__' of 'LayeredMenu' objects>, 'onEntryChosen': <function onEntryChosen at 0x7f3460ec2938>, 'addEntry': <function addEntry at 0x7f3460ec2848>, 'populate': <function populate at 0x7f3460ec28c0>, 'getChosenValue': <function getChosenValue at 0x7f3460ec2758>, 'getEntries': <function getEntries at 0x7f3460ec2668>, '__doc__': '\n Class implementing a layered menu that contains layered menu entries.\n ', '__init__': <function __init__ at 0x7f3460ec2488>})¶

__init__(populateCallback, actionCallback, keyboardShortcut, alwaysPopulate=False, onlyMatchWordStart=True)¶

Initializes an instance of the class.

Parameters:

populateCallback (callable) – The callback to call in order to populate the menu with entries. The callback will receive an instance of the LayeredMenu class representing the menu to add entries to. In order to populate the corresponding menu with entries, the addEntry method can be called on the given instance.
actionCallback (callable) – The callback to call when the user has chosen an entry from the menu. The callback will receive an arbitrary object that was given when the chosen entry was added using the addEntry method. The callback can return a node which is then added to the node graph.
keyboardShortcut (str) – The keyboard shortcut to use for showing the menu, for example "M" or "Alt+P".
alwaysPopulate (bool) – Flag that controls whether the given populate callback is called every time before the menu is shown (True), or only the first time (False), in which case its entries are cached by the LayeredMenu instance.
onlyMatchWordStart (bool) – Flag that controls whether an entered word should be matched against the beginning of an entry’s text (True), or if it should be matched against any part of an entry’s text (False).

Raises:

ValueError – If one of the given callbacks is not callable.

__module__ = 'UI4.Tabs.LayeredMenuAPI'¶

__weakref__¶: list of weak references to the object (if defined)

addEntry(value, text=None, color=None, size=None)¶

Adds an entry to the menu to represent the given value, optionally with the given text, color, and size.

Parameters:

value (object) – An arbitrary object that the added menu entry represents, which is passed to the callback that is called when the entry has been chosen by the user.
text (str or None) – The text to use for the entry in the menu, or None to use the given value converted using str().
color (3-tuple of float or None) – The color to use for the entry in the menu, or None to use a default color for the entry.
size (2-tuple of float or None) – The width and height in pixels of the entry, or None to calculate the entry’s size automatically based on its text.

alwaysPopulate()¶

Return type:	`bool`
Returns:	`True` if the populate callback is to be called every time before the menu is shown, or `False` if it is to be called only the first time.

clear()¶: Clears the cache of menu entries and resets the flag that indicates whether the menu has been populated (see isPopulated.

getChosenValue()¶

Return type:	`object` or `None`
Returns:	The arbitrary object that the chosen menu entry represents, or `None` if no entry has been chosen yet.

getEntries()¶

Return type:	`list` of `LayeredMenuEntry`
Returns:	The list of entries that make up this menu.

getKeyboardShortcut()¶

Return type:	`str`
Returns:	The keyboard shortcut to use for showing the menu, for example `"M"` or `"Alt+P"`.

isPopulated()¶

Return type:	`bool`
Returns:	`True` if this menu has been populated with entries already, otherwise `False`.
Note:	Calling `clear` resets the cache of menu entries and the flag that indicates whether the menu has been populated.

onEntryChosen(value)¶

Calls the action callback with the given value when the user has chosen an entry from the menu.

Return type:	`object` or `None`
Parameters:	value (`object`) – The arbitrary object of the menu entry that was chosen, which is passed as an argument to the action callback.
Returns:	The result of the action callback, or `None` if the action callback could not be called.

onlyMatchWordStart()¶

Return type:	`bool`
Returns:	`True` if an entered word should be matched against the beginning of an entry’s text, or `False` if it should be matched against any part of an entry’s text.

populate()¶

Clears the cache of menu entries (see clear), and calls the callback that was set for populating the layered menu with entries.

Return type:	`bool`
Returns:	`True` if the menu has been populated with menu entries, otherwise `False`.

class LayeredMenuAPI.LayeredMenuEntry(value, text=None, color=None, size=None)¶

Bases: object

Class implementing an entry in a layered menu.

Stores the value, and optionally a text, color, and size for a menu entry.

__dict__ = dict_proxy({'__module__': 'UI4.Tabs.LayeredMenuAPI', 'getColor': <function getColor at 0x7f3460ec2320>, 'getText': <function getText at 0x7f3460ec22a8>, 'getValue': <function getValue at 0x7f3460ec2230>, 'getSize': <function getSize at 0x7f3460ec2398>, '__repr__': <function __repr__ at 0x7f3460ec2410>, '__dict__': <attribute '__dict__' of 'LayeredMenuEntry' objects>, '__weakref__': <attribute '__weakref__' of 'LayeredMenuEntry' objects>, '__doc__': '\n Class implementing an entry in a layered menu.\n\n Stores the value, and optionally a text, color, and size for a menu entry.\n ', '__init__': <function __init__ at 0x7f3460ec21b8>})¶

__init__(value, text=None, color=None, size=None)¶

Initializes an instance of the class.

Parameters:

value (object) – An arbitrary object that the menu entry represents, which is passed to the callback that is called when this entry has been chosen by the user.
text (str or None) – The text to use for the entry in the menu, or None to use the given value converted using str().
color (3-tuple of float or None) – The color to use for the entry in the menu, or None to use a default color for the entry.
size (2-tuple of float or None) – The width and height in pixels of the entry, or None to calculate the entry’s size automatically based on its text.

__module__ = 'UI4.Tabs.LayeredMenuAPI'¶

__repr__()¶

Return type:	`str`
Returns:	A textual representation of this instance.

__weakref__¶: list of weak references to the object (if defined)

getColor()¶

Return type:	3-`tuple` of `float` or `None`
Returns:	The color to be rendered for the menu entry.

getSize()¶

Return type:	2-`tuple` of `float` or `None`
Returns:	The width and height of the entry in pixels.

getText()¶

Return type:	`str`
Returns:	The text to be rendered for the menu entry.

getValue()¶

Return type:	`object`
Returns:	An arbitrary object that the menu entry represents, which is passed to the callback that is called when this entry has been chosen by the user.

LayeredMenuAPI.RegisterLayeredMenu(layeredMenu, layeredMenuID)¶

Registers the given layered menu under the given ID.

Parameters:	layeredMenu (`LayeredMenu`) – The layered menu to register. layeredMenuID (`str`) – The ID that uniquely identifies the layered menu.