Base Editor¶

Module containing the BaseEditor class.

class PackageSuperToolAPI.BaseEditor.BaseEditor(parent, node)¶

Bases: PyQt5.QtWidgets.QWidget

Class implementing a widget for editing parameters of a PackageSuperToolAPI-based node.

Variables: AddPackageRegistry – Maps action IDs for “Add Package” actions to the package class for the package which should be added when the action is triggered.

AddPackageRegistry = {}¶

PackageMenuActionsRegistry = {}¶

SEPARATOR = '----'¶

TAB_AREA_UPDATE_INTERVAL = 100¶

__init__(parent, node)¶

Initializes an instance of the class.

Parameters

parent (QtWidgets.QWidget or None) – The widget to use as the parent of the SuperTool editor.
node (NodegraphAPI.Node) – The SuperTool node for the editor to work with.

addTab(tabName)¶

Creates a new tab in the editor with the given tab name.

Return type: QtWidgets.QWidget
Parameters: tabName (str) – The name of the tab to be created.
Returns: The newly-created tab widget.
Since: Katana 4.5v1

canSelectionBeExported()¶

Return type: bool
Returns: True if the current selection can be exported, otherwise False.

getAddPackageMenuActions()¶

Allows derived classes to add custom items to the B{Add} menu in the context menu of the SceneGraphView widget, specifying types of packages that can be added to the SuperTool. These menu items trigger actions configured in getKeyboardShortcuts(). Is called when the menu is shown.

Return type

list of tuple of (str, str, bool)

Returns

A list of tuples (one per action). Each tuple should contain:

The name of the action, as specified by the indices of the dict returned by getKeyboardShortcuts().
A string containing the text to use for the menu item.
A flag indicating whether the menu item is to be made available.

Note

The base class implementation returns an empty list.

getAttribute(locationPath, attributeName)¶

Return type

FnAttribute or None

Parameters

locationPath (str) – The location path for which we wish to fetch the attribute of the given name.
attributeName (str) – The name of an attribute to fetch for the given location.

Returns

The requested attribute at the given location, or None if no such attribute was found.

getChildrenUnder(parentPath)¶

Deprecated: This function is deprecated. Please use getSceneGraphView().getSceneGraphChildren() instead.

getDefaultAddMenuGroupName()¶

Allows derived classes to specify the name of a sub-menu under the B{Add} menu to which ungrouped packages can be added. Packages can be grouped together by specifying the ADD_MENU_GROUP_NAME class variable.

The default implementation returns an empty string, which results in ungrouped packages being added at the top level of the B{Add} menu.

Return type: str
Returns: The name of the group under the B{Add} menu to which packages should be added if they do not specify a group using the ADD_MENU_GROUP_NAME class variable.

classmethod getDefaultSceneGraphViewTerminalOpUpdates(graphState)¶

Return type: tuple of tuple of (str, FnAttribute.GroupAttribute, str)
Parameters: graphState (NodegraphAPI.GraphState) – The graph state to be queried for the “system” Op arguments, for the Ops that need it.
Returns: A tuple containing a description of a default chain of Ops whose arguments are to be updated, each in the form of a tuple of Op type name as a string, Op arguments as a FnAttribute.GroupAttribute and a key indicating which Op to update.
Note: The base class implementation returns an empty list.

classmethod getDefaultSceneGraphViewTerminalOps(graphState)¶

Return type: tuple of tuple of (str, FnAttribute.GroupAttribute) or (str, FnAttribute.GroupAttribute, str)
Parameters: graphState (NodegraphAPI.GraphState) – The graph state to be queried for the “system” Op arguments, for the Ops that make use of them.
Returns: A tuple containing a description of a chain of default Ops, each in the form of a tuple of Op type name as a string and Op arguments as a FnAttribute.GroupAttribute. Any Ops which may need to be updated later with new arguments can be supplied with a string key to identify them.
Note: The base class implementation returns an empty list.

classmethod getKeyboardShortcuts()¶

To be implemented by subclasses. Returns a dictionary of keyboard shortcuts for actions in the SuperTool UI. The format of this dictionary is the same that is passed to RegisterActions() in UI4.App.KeyboardShortcutManager. The keyboard shortcuts returned from this function will be added to the default shortcuts and registered. Is called at startup.

The keyboard shortcut information returned in the dictionary should be tuples containing:

A unique and immutable action hash, used by the keyboard shortcut manager to store the keyboard shortcut configuration.

A string describing a key combination (e.g. ‘Shift-P’).

A callback to be called when the used presses the specified key combination of the shortcut.

Return type: dict of str to tuple of (str, str, callable)
Returns: A dictionary of action names to keyboard shortcut information.
Note: The base class implementation returns an empty dictionary.

classmethod getLayoutOrientation()¶

Return type: int
Returns: The layout orientation of the SuperTool editor’s layout: either LAYOUT_VERTICAL (the default) or LAYOUT_HORIZONTAL.
Note: In vertical layout (the default), the tab area is positioned below the SceneGraphView widget. In horizontal layout, the tab area is positioned to the right of the SceneGraphView widget.

getMainNode()¶

Return type: BaseNode.BaseNode
Returns: The main node of this SuperTool.

getMainPanelWidget()¶

Return type: QtWidgets.QWidget
Returns: The main panel widget that contains the parameter tabs and the SceneGraphView widget for this SuperTool.

getMenuActions()¶

Allows derived classes to add custom items to the context menu of the SceneGraphView widget of this SuperTool. These menu items trigger actions configured in getKeyboardShortcuts(). Is called when the menu is shown.

Return type

list of tuple of (str, str, bool)

Returns

A list of tuples (one per action). Each tuple should contain:

The name of the action, as specified by the indices of the dict returned by getKeyboardShortcuts().
A string containing the text to use for the menu item.
A flag indicating whether the menu item is to be made available.

Note

The base class implementation returns an empty list.

getPackageForPath(locationPath, includeEditPackages=True, createDummyOnMissing=False)¶

Return type

Package or None

Parameters

locationPath (str) – A location path that might belong to a package.
includeEditPackages (bool) – Flag that controls whether edit packages (those that subclass EditPackage) should be considered.
createDummyOnMissing (bool) – Flag that controls whether a dummy/stub package should be created if the given locationPath doesn’t have a local package associated with it.

Returns

The package for the given location path, or None if no such package could be found.

getSceneGraphView()¶

Return type: UI4.Widgets.SceneGraphView
Returns: The SceneGraphView widget for this SuperTool.

classmethod getSceneGraphViewTerminalOpUpdates(graphState, rootLocations)¶

Allows derived classes to provide updates for terminal Ops that are used for the SceneGraphView widget of this SuperTool.

Return type

list of tuple of (str, FnAttribute.GroupAttribute, str)

Parameters

graphState (NodegraphAPI.GraphState) – The graph state to be queried for the “system” Op arguments, for Ops that make use of them.
rootLocations (tuple of str) – The paths of scene graph locations that are used as roots in the SuperTool’s SceneGraphView widget.

Returns

A list with a description of a chain of Ops whose arguments are to be updated, each in the form of a tuple of Op type name as a string, Op arguments as a FnAttribute.GroupAttribute and a key identifying the Op to update.

Note

The base class implementation returns an empty list.

See

getSceneGraphViewTerminalOps()

classmethod getSceneGraphViewTerminalOps(graphState, rootLocations)¶

Allows derived classes to add terminal Ops to the Op chain of this SuperTool’s SceneGraphView widget.

Here’s an example of adding an OpResolve Op to the Op chain (note that such an Op is added by default internally anyway, so adding it here is not required):

result = []

# OpResolve
opResolve = FnAttribute.GroupBuilder()
opResolve.set('system', graphState.getOpSystemArgs())
result.append(('OpResolve', opResolve.build(), 'opResolve'))

return result

Return type

list of tuple of (str, FnAttribute.GroupAttribute) or (str, FnAttribute.GroupAttribute, str)

Parameters

graphState (NodegraphAPI.GraphState) – The graph state to be queried for the “system” Op arguments, for Ops that make use of them.
rootLocations (tuple of str) – The paths of scene graph locations that are used as roots in the SuperTool’s SceneGraphView widget.

Returns

A list containing a description of a chain of Ops, each in the form of a tuple of Op type name as a string and Op arguments as a FnAttribute.GroupAttribute and a key for the Ops that may need to be updated with new arguments in the future.

Note

The base class implementation returns an empty list.

See

getSceneGraphViewTerminalOpUpdates()

getSelectedItems()¶

Return type: list of str
Returns: A list of locations selected in the SceneGraphView widget for this SuperTool.

getSelectedPackages(includeEditPackages=True, createDummyOnMissing=True)¶

Returns the currently selected packages in the SceneGraphView.

Return type

list of tuple

Parameters

includeEditPackages (bool) – Flag that controls whether edit packages (those that subclass EditPackage) should be considered.
createDummyOnMissing (bool) – Flag that controls whether a dummy/stub package should be created if the given locationPath doesn’t have a local package associated with it.

Returns

The selected packages in the SceneGraphView widget, as a list of tuples of the form (scene graph location path, package). If package is None, a package could not be found for the corresponding selected location. This can occur if a selected location is not managed by this SuperTool.

classmethod getSuperToolName()¶

Return type: str
Returns: The name of the SuperTool. Is used in the registration of keyboard shortcut actions for the SuperTool’s UI, and for the separator above custom menu actions that are defined in getMenuActions().
Raises: NotImplementedError – If not implemented in the subclass.

classmethod getTabNames()¶

Return type: list of str
Returns: The names of the tabs in the SuperTool’s B{Parameters} tab interface.
Note: The base class implementation returns an empty list.

getTabWidget()¶

Return type: QtWidgets.QTabWidget
Returns: The tab widget for this SuperTool.
Since: Katana 4.5v1

getTopLevelPackage(package)¶

Return type: Package
Parameters: package (Package) – The package for which the top-level package should be returned.
Returns: The top-level package under which the given package exists.

hideEvent(event)¶: Overrides the standard QWidget event handler for “hide” events.

onSelectionChanged()¶

Callback invoked when the selection of packages in the SceneGraphView widget of the SuperTool has changed.

A list of packages that are currently selected can be obtained by calling self.getSelectedPackages().

Following a call of this function, the tab area below the SceneGraphView widget is updated for the first of the selected packages.

Note: The base class implementation does nothing.

populateContextMenu(menu)¶

Populates the given context menu.

The default implementation adds the standard context menu items: package management items like B{Delete Package} or B{Duplicate Package}, the B{Add} menu and the items defined by getAddPackageMenuActions() and getMenuActions(). To include these standard items, the implementation of this function on the SuperTool’s Editor class should call its implementation in BaseEditor.

Parameters: menu (QtWidgets.QMenu) – An instance of the (still empty) context menu to be populated with new items.

classmethod registerAddPackageKeyboardShortcut(packageClass)¶

Registers a keyboard shortcut to add a package of the given class. This is called from the initializer BaseEditor, to ensure that shortcuts are registered for any user package types which have been declared since startup.

Parameters: packageClass (type) – The class of the package for which to add an “add package” keyboard shortcut.

classmethod registerKeyboardShortcuts()¶: Registers the core set of keyboard shortcuts for the Super Tool. This function is invoked once per Super Tool.

classmethod registerPackageKeyboardShortcuts(packageClass)¶

Registers keyboard shortcuts declared by the given class. This is called from the initializer BaseEditor, to ensure that shortcuts are registered for any user package types which have been declared since startup.

Parameters: packageClass (type) – The class of the package for which to add keyboard shortcuts.

removeTab(tabName)¶

Removes the tab with the given name from the editor’s tab widget.

Parameters: tabName (str) – The name of the tab to remove.
Since: Katana 4.5v1

setColumnToUpdateOnStateChange(columnName)¶: Adds the column of the given name in the SceneGraphView widget to a list of columns which will be updated when a state change takes place.

setupSceneGraphViewColumns()¶

Configures the SceneGraphView widget that is part of the widgets that are shown for a SuperTool of this type that is edited in a B{Parameters} tab.

A column can be added using C{self.getSceneGraphView().addColumn( ‘<column name>’)}. Columns have a data type which controls the appearance and possible editing of values in its cells. Columns are associated with attributes to display using the setAttributeName() function on column objects returned from addColumn().

The values in cells of a column can be made editable for the user by calling setEditable(True) on a column object. Edits are fed back to parameters on nodes within the SuperTool. See Package.getOverrideNodeAndParameter() to learn how package types specify which node parameters drive the editing of attributes that correspond to a column in a SceneGraphView widget.

Raises: NotImplementedError – If the function has not been implemented by a subclass.

setupTabWidget()¶

Configures the QTabWidget that is part of the widgets that are shown for a SuperTool of this type that is edited in a B{Parameters} tab.

Can be implemented in derived classes to provide extra functionality.

Note: The base class implementation does nothing.
Since: Katana 4.5v1

showEvent(event)¶: Overrides the standard QWidget event handler for “show” events.

class PackageSuperToolAPI.BaseEditor.GafferThreeInteractionDelegate¶

Bases: UI4.NodeMaster.NodeInteractionDelegateManager.Delegate

addToNodeSpecificShelfEnvironment(targetNode, editor, envDict)¶: Adds a variable named selectedItems to the node-specific shelf script environment for GafferThree nodes. This makes this value available for use in GafferThree shelf scripts.