Base Node

Module containing the BaseNode class.

class PackageSuperToolAPI.BaseNode.BaseNode(version=None)

Bases: SuperTool

Base class for a PackageSuperToolAPI-based node type. Should be extended by the respective SuperTool’s Node class.

This is responsible for setting up all the standard network of nodes in these types of SuperTool.

VERSION = 1

__init__(version=None)

Initializes an instance of the class.

Derived classes should call this method in their initializer, as well as creating any nodes required by the respective SuperTool which do not belong to an individual package.

Parameters:: version (int) – The version of the node, to be used by the upgrade system.

adoptLocationForEditing(locationPath, locationAttributes=None)

Adopts the scene graph location with the given path for editing within the SuperTool node.

Parameters:

locationPath (str) – The path of the scene graph location to adopt.
locationAttributes (FnAttribute.GroupAttribute) – The attribute data at the given scene graph location. If not provided, it will be determined. Providing the attribute data is simply for performance.

Raises:

ValueError – If no scene graph attributes could be found for the given location path.

adoptLocationsForEditing(locationPaths, locationAttributes=None)

Adopts the scene graph locations with the given paths for editing within the SuperTool.

Parameters:

locationPaths (list of str) – The paths of the scene graph locations to adopt.
locationAttributes (list of FnAttribute.GroupAttribute) – An optional list providing attribute data for each location in locationPaths. If provided, the length of this list must match the length of locationPaths.

Raises:

ValueError – If the given lists of location paths and location attributes are of different lengths.

canAdoptLocationForEditing(location)

Returns a flag indicating whether or not the scene graph location with the given path can be adopted for editing by the SuperTool.

Return type:: bool
Parameters:: location (str) – The path of the scene graph location to query whether it can be adopted by the SuperTOol.
Returns:: True if the scene graph location with the given path can be adopted for editing by the SuperTool, otherwise False.

canAdoptLocationsForEditing(locations)

Return type:: bool
Parameters:: locations (list of str) – The scene graph locations to query whether they can all be adopted by the SuperTool.
Returns:: True if all of the given scene graph locations can be adopted for editing by the SuperTool, otherwise False.

getAPIVersion()

Return type:: int
Returns:: The version of the API used to construct the SuperTool.

classmethod getDefaultRootLocation()

Abstract function that allows the subclasses to specify the default location under which the package locations will be created.

Return type:: str
Returns:: The default path of the scene graph location to use as the root of the scene graph hierarchy created by this SuperTool.
Raises:: NotImplementedError – If not implemented by a subclass.

classmethod getItemListAttributeName()

Allows subclasses to specify the name of the string attribute under ‘globals.itemLists’ in /root/world where the name of the SuperTool instances will be added as values. The default implementation returns None, which means that no entry will be added under ‘globals.itemLists’.

Return type:: str or None
Returns:: The name of the string attribute under ‘globals.itemLists’ at /root/world where the names of instances of the SuperTool will be added, or None to indicate that the SuperTool should not add to the global item list.

getLocationAttributes(locationPath)

Return type:: FnAttribute.GroupAttribute or None
Parameters:: locationPath (str) – The path of the location for which to return attributes.
Returns:: The attributes at the location with the given path, or None if no such location could be found.

getPackageForPath(locationPath, raiseOnMissing=True, locationAttributes=None, includeEditPackages=True, createDummyOnMissing=False)

Return type:

Package or None

Parameters:

locationPath (str) – The location to return a corresponding Package instance for.
raiseOnMissing (bool) – If True and no Package is found for the given locationPath, a KeyError will be thrown. If False and no Package is found, None will be returned and no exception will be raised.
locationAttributes (FnAttribute or None) – Optionally provide the attributes at the location specified by locationPath. If this is not given (default) they will be queried from the scene graph.
includeEditPackages (bool) – Flag that controls whether edit packages (those that subclass EditPackage) should be considered.
createDummyOnMissing (bool) – When True, if no explicit local package is found at the given location, if the type of the location in the incoming scene is recognised as a valid ‘group’-like type, a dummy stand-in package will be created that represents the location.

Returns:

The Package that corresponds to the given location path, or None if no such package was found and raiseOnMissing is False.

Raises:

KeyError – If no package was found for the given path, and raiseOnMissing is True and createDummyOnMissing is False.

getRegisteredDisplayPackageClasses()

Return type:: list of Package
Returns:: A list of package classes that have been registered for the SuperTool and are inteded for display in a UI.

getRegisteredPackageClasses()

Return type:: list of tuple of (str, type)
Returns:: A list of (name, class) tuples for the registered package classes for the SuperTool. The name element is the name of the package class. To access the display name (if the package class supports it), query the DISPLAY_NAME attribute (if it exists) on the class.

getRootLocation()

Return type:: str
Returns:: The path of the root location of the SuperTool under which the package locations are created.

getRootPackage()

Return type:: Package
Returns:: The root package for the SuperTool.

getShowIncomingScene()

Return type:: bool
Returns:: True if the incoming scene should be shown in the SceneGraphView widget for the SuperTool, otherwise False.

classmethod getSuperToolName()

Abstract function to be implemented by the subclass. Returns the name of the SuperTool. This name will be used, for example, in the registration of the keyboard shortcut actions.

Return type:: str
Returns:: The name of the SuperTool.
Raises:: NotImplementedError – If not implemented by a subclass.

getSyncSelection()

Return type:: int
Returns:: The sync selection state for the SuperTool, which will be one of SYNC_SELECTION_OFF, SYNC_SELECTION_OUT or SYNC_SELECTION_IN_OUT. This determines whether and how selection is kept in sync between the SuperTool and the Scene Graph tab.
See:: setSyncSelection()

getVersion()

Return type:: int
Returns:: The version of the SuperTool.

isLocationAdopted(locationPath)

Return type:: bool
Parameters:: locationPath (str) – The path of the scene graph location to query whether it is adopted by the SuperTool.
Returns:: True if the scene graph location with the given path has been adopted by the SuperTool, otherwise False.

setRootLocation(locationPath)

Sets the path of the root location of the SuperTool, under which the package locations will be created.

Parameters:: locationPath (str) – The path of the root location for the SuperTool.

setShowIncomingScene(state)

Sets if the incoming scene should be shown in the SceneGraphView widget for the SuperTool.

Parameters:: state (bool) – A flag indicating whether the incoming scene should be shown in the SceneGraphView widget.

setSyncSelection(syncSelection)

Sets the sync selection state for the SuperTool. This determines whether and how selection is kept in sync between the SuperTool and the Scene Graph tab.

Parameters:: syncSelection (int) – The sync selection state for the SuperTool. Should be one of: SYNC_SELECTION_OFF, SYNC_SELECTION_OUT or SYNC_SELECTION_IN_OUT.
See:: getSyncSelection()

setVersion(version)

Sets the version of the SuperTool to the given version.

Parameters:: version (int) – The version of the SuperTool.

classmethod superToolRegistered()

A method which can be implemented in derived classes to perform any actions required after registration of the SuperTool.

The default implementation does nothing.

upgrade(rootPackage)

Upgrades the internal node network of the SuperTool node with the given root package to the latest version of that SuperTool.

Is called from the initializer of the RootPackage base class when a class derived from RootPackage is instantiated and the base class initializer is called.

Can be re-implemented in derived classes by comparing the result of getVersion() with the value of a VERSION class variable, in order to determine whether an upgrade is necessary, and which changes to make.

The default implementation iterates over packages and calls Package.upgradeToVersion() for each intermediate version between the SuperTool’s saved version and the latest version of the SuperTool’s definition.

Parameters:: rootPackage (RootPackage) – The root package of the SuperTool node to upgrade.

PackageSuperToolAPI.BaseNode.RegisterTagAdoptedNodeType(): Registers the “_GafferTagAdopted” node type.