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
orNone
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.
GetLayeredMenuIDByAssociatedRenderer
(associatedRenderer)¶ Return type: str
orNone
Parameters: associatedRenderer ( str
) – The associated renderer that uniquely identifies the layered menu to return.Returns: The layered menu ID of the layered menu whose associated renderer matches the given associated renderer, or None
if no layered menu with the given associated renderer has been registered.
-
LayeredMenuAPI.
GetLayeredMenuIDs
()¶ Return type: list
ofstr
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, sortAlphabetically=True, checkAvailabilityCallback=None)¶ Bases:
object
Class implementing a layered menu that contains layered menu entries.
-
__init__
(populateCallback, actionCallback, keyboardShortcut, alwaysPopulate=False, onlyMatchWordStart=True, sortAlphabetically=True, checkAvailabilityCallback=None)¶ 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 theLayeredMenu
class representing the menu to add entries to, and the Node Graph tab object where the entry was chosen. In order to populate the corresponding menu with entries, theaddEntry
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 theaddEntry
method, and the Node Graph tab object where the entry was chosen. 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 theLayeredMenu
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
). - sortAlphabetically (
bool
) – Flag that controls whether entries should be sorted alphabetically before being displayed in the menu layer. - checkAvailabilityCallback (
callable
orNone
) – An optional callback that will be called to determine whether the menu is suitable for being displayed in a certain Node Graph tab. The callback will receive the layered menu object itself, as well as a tab object of typeNodeGraphTab.NodegraphPanel.NodegraphPanel
. The callback is expected to return eitherTrue
orFalse
.
Raises: ValueError – If one of the given callbacks is not callable.
- populateCallback (
-
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
orNone
) – The text to use for the entry in the menu, orNone
to use the given value converted usingstr()
. - color (3-
tuple
offloat
orNone
) – The color to use for the entry in the menu, orNone
to use a default color for the entry. - size (2-
tuple
offloat
orNone
) – The width and height in pixels of the entry, orNone
to calculate the entry’s size automatically based on its text.
- value (
-
alwaysPopulate
()¶ Return type: bool
Returns: True
if the populate callback is to be called every time before the menu is shown, orFalse
if it is to be called only the first time.
-
checkAvailability
(tab)¶ Checks whether the instance is available for being displayed in the given Node Graph tab object.
Return type: bool
Parameters: tab ( NodeGraphTab.NodegraphPanel.NodegraphPanel
) – The Node Graph tab where the menu is about to be displayed.Returns: True
if the menu is suitable for being displayed in the given tab (or any other arbitrary criteria).
-
clear
()¶ Clears the cache of menu entries and resets the flag that indicates whether the menu has been populated (see
isPopulated
.
-
getAssociatedRenderer
()¶ Return type: str
Returns: The associated renderer for the layered menu.
-
getChosenValue
()¶ Return type: object
orNone
Returns: The arbitrary object that the chosen menu entry represents, or None
if no entry has been chosen yet.
-
getEntries
()¶ Return type: list
ofLayeredMenuEntry
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, otherwiseFalse
.Note: Calling clear
resets the cache of menu entries and the flag that indicates whether the menu has been populated.
-
onEntryChosen
(value, tab)¶ Calls the action callback with the given value when the user has chosen an entry from the menu.
Return type: object
orNone
Parameters: - value (
object
) – The arbitrary object of the menu entry that was chosen, which is passed as an argument to the action callback. - tab (
NodeGraphTab.NodegraphPanel.NodegraphPanel
) – The Node Graph tab where the entry was chosen.
Returns: The result of the action callback, or
None
if the action callback could not be called.- value (
-
onlyMatchWordStart
()¶ Return type: bool
Returns: True
if an entered word should be matched against the beginning of an entry’s text, orFalse
if it should be matched against any part of an entry’s text.
-
populate
(tab)¶ 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
Parameters: tab ( NodeGraphTab.NodegraphPanel.NodegraphPanel
) – The Node Graph tab where the entry was chosen.Returns: True
if the menu has been populated with menu entries, otherwiseFalse
.
-
setAssociatedRenderer
(associatedRenderer)¶ Sets an associated renderer for the layered menu.
Parameters: associatedRenderer ( str
) – The associated renderer.
-
setChosenValue
(value)¶ Parameters: value ( object
orNone
) – Value to (programmatically) choose, e.g. for selecting initial item.
-
shouldSortAlphabetically
()¶ Return type: bool
Returns: True
if entries should be sorted alphabetically before being displayed in the menu layer.
-
-
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.
-
__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
orNone
) – The text to use for the entry in the menu, orNone
to use the given value converted usingstr()
. - color (3-
tuple
offloat
orNone
) – The color to use for the entry in the menu, orNone
to use a default color for the entry. - size (2-
tuple
offloat
orNone
) – The width and height in pixels of the entry, orNone
to calculate the entry’s size automatically based on its text.
- value (
-
getColor
()¶ Return type: 3- tuple
offloat
orNone
Returns: The color to be rendered for the menu entry.
-
getSize
()¶ Return type: 2- tuple
offloat
orNone
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.
- layeredMenu (