Callbacks and Events¶
Registering a Callback¶
- Callbacks.addCallback(callbackType, callbackFcn, callbackObjectHash=None)¶
- Callbacks.delCallback(callbackType, callbackFcn, callbackObjectHash=None)¶
Registering an Event Handler¶
A queue for passing and handling events.
Events are a combination of a string eventType and an eventID. The eventID is almost always an integer value, but special event types could use other hashable objects.
Handlers can filter on the eventType and/or eventID. Handlers
for all queued events are called when ProcessEvents
is called.
The callback handlers are held with weak references. If they are attached to an object that is destroyed, the callback will not be made.
Handlers can be registered to eventType None
and eventID None
which will be called for every event that is sent.
- Utils.EventModule.QueueEvent(eventType, eventID, priority=0, **kwargs)¶
Adds the description of an event to the event queue, based on the given arguments.
- Parameters
eventType (
str
) – The type of event to add to the event queue, e.g.'node_create'
.eventID (
hashable
) – A hashable object that can be checked in event handlers to filter event handling.priority (
int
) – The level of importance of the event to add, in relation to other events in the event queue: -priority < 0
- low priority -priority = 0
- normal priority -priority > 0
- high prioritykwargs (
dict
) – A dictionary of keyword arguments that provides information about or data associated with the event to add.
- Utils.EventModule.QueuePriorityEvent(eventType, eventID, **kwargs)¶
Adds the description of some important event to the event queue, based on the given arguments, indicating that is should be handled as soon as possible.
- Parameters
eventType (
str
) – The type of event to add to the event queue, e.g.'node_create'
.eventID (
hashable
) – A hashable object that can be checked in event handlers to filter event handling.kwargs (
dict
) – A dictionary of keyword arguments that provides information about or data associated with the event to add.
- Utils.EventModule.ProcessEvents()¶
Processes all events that are currently in the event queue, by calling any event handlers that were registered against combinations of event type and event ID.
- Return type
bool
- Returns
True
if more events are still to be processed, as events were added to the event queue while processing events, otherwiseFalse
.- See
- Utils.EventModule.ProcessAllEvents()¶
Processes events until the event queue is empty.
Some handlers will add new events of their own. When this happens, a single
ProcessEvents()
call will not clear the queue completely, but a call ofProcessAllEvents()
will.- See
- Utils.EventModule.RegisterEventFilter(eventFilter)¶
Registers a new event filter.
Filters are callbacks that happen when all events are placed on the queue, not at
ProcessEvents
time.If the filter callback returns False, the event is blocked from getting onto the queue, and never reaches the handlers.
The filter should not raise an exception. A raised exception will block other Filters and abort the new event.
- Utils.EventModule.IsEventFilterRegistered(eventFilter)¶
- Return type
bool
- Parameters
eventFilter (
callable
) – The callback to check.- Returns
True
if the given callback is registered as an event filter callback, otherwiseFalse
.
- Utils.EventModule.UnregisterEventFilter(eventFilter)¶
Un-registers an existing event filter.
Filters are callbacks that happen when all events are placed on the queue, not at
ProcessEvents()
time.- Parameters
eventFilter (
function
) – The event filter function to un-register.
- Utils.EventModule.RegisterEventHandler(handler, eventType=None, eventID=None, enabled=True)¶
Registers a handler to be called when events are processed. By supplying specific eventType and eventID arguments, you can limit which events actually call the handler. Setting enabled to False unregisters the handler. Event handlers are protected from exceptions.
This will raise a ValueError exception if a duplicate handler is registered for the same eventType and eventID.
- Raises
ValueError – duplicate handler found
- Utils.EventModule.UnregisterEventHandler(handler, eventType=None, eventID=None)¶
Unregisters a handler from processing events. This is the same as calling RegisterEventHandler(…, enabled=False)
This will raise a ValueError exception if an existing handler for this eventType and eventID is not registered.
- Raises
ValueError – handler not found
- Utils.EventModule.RegisterCollapsedHandler(handler, eventType=None, eventID=None, enabled=True)¶
Registers a handler to be called when events are processed.
This handler will be called at most one time per ProcessEvents. It will be passed a sequence of argument values that would have been passed to a normally registered event handler.
This will raise a ValueError exception if a duplicate handler is registered for the same eventType and eventID.
- Raises
ValueError – duplicate handler found
- Utils.EventModule.UnregisterCollapsedHandler(handler, eventType=None, eventID=None)¶
Unregisters a collapsed handler from processing events. This is the same as calling RegisterCollapsedHandler(…, enabled=False)
This will raise a ValueError exception if an existing handler for this eventType and eventID is not registered.
- Raises
ValueError – handler not found
- Utils.EventModule.RegisterDebugEventHandler()¶
This registers a simplistic event debugger. The debug handler logs every event as it is processed. Note that this ignores the ‘event_idle’ which happens on every process.
- Utils.EventModule.Initialize()¶
Initializes the processing of events.
- Utils.EventModule.IsCollapsedHandlerRegisteredAfterEventLoop(handler, eventType, eventID)¶
Determines if the specified handler is already registered and still will be once the event loop is over.
I.e. takes into account whether
UnregisterEventHandler
has been called from within the event loop.
- Utils.EventModule.IsCollapsedRegistered(handler, eventType=None, eventID=None)¶
Determines if the specified collapsed handler is already registered.
This corresponds with whether or not RegisterEventHandler / UnregisterEventHandler will raise ValueError exception.
- Utils.EventModule.IsHandlerRegistered(handler, eventType=None, eventID=None)¶
Determines if the specified handler is already registered. This corresponds with whether or not RegisterEventHandler / UnregisterEventHandler will raise ValueError exception.
- Utils.EventModule.IsHandlerRegisteredAfterEventLoop(handler, eventType, eventID)¶
Determines if the specified handler is already registered and still will be once the event loop is over.
I.e. takes into account whether
UnregisterEventHandler
has been called from within the event loop.
- Utils.EventModule.IsHandlerRegisteredForEventType(eventType, checkEventID=True)¶
For the specified eventType, are any handlers (both collapsed or individual) registered?
If checkEventID is False, this will only look for handlers that are register using the ‘None’ eventID. If checkEventID is True, this will also check for those callbacks.
- Utils.EventModule.GetAllRegisteredEventTypes()¶
Get all of the event types that have been registered. (both collapsed and individual)
- Utils.EventModule.GetNumRegisteredHandlersForEventType(eventType)¶
Get the number of handlers that have been registered for the specified eventType (both collapsed and individual).
- Utils.EventModule.SynchronousEventProcessingScope()¶
Context manager that forces all events that are queued through a call to
QueueEvent
to be processed synchronously, as soon as they are queued.- Deprecated
No longer supported since Katana 3.1v1.
- Utils.EventModule.SetRegistrationCallbackForType(cls, callback)¶
Sets a callback to be called when an event handler is registered that operates on an instance of a class derived from the given class.
- Parameters
cls (
type
) – The class to use when checking instances of event handler objects.callback (
callable
) – The callback to call when an event handler is registered.
- Raises
ValueError – If the given callback object is not callable.
- Utils.EventModule.UnregisterObjectEventHandlers(objectID)¶
Unregisters all event handlers, both regular and collapsed, that are currently registered to operate on the event handler object with the given ID.
- Parameters
objectID (
int
) – The ID of the event handler object whose event handlers to unregister.
- Utils.EventModule.PumpIdleQueue()¶
Schedules the processing of events that indicate that the application is idle, triggering event handlers that were registered for
'event_idle'
events.
Callback Types¶
To see a list of callback types:
from Katana import Callbacks
print(dir(Callbacks.Type))
Event Types¶
To see a list of event types:
from Katana import Utils
print(sorted(Utils.EventModule.GetAllRegisteredEventTypes()))
- node_create¶
A node is created
- Parameters
eventID –
hash(Node)
node – the created node
nodeType – the type used to create the node
nodeName – the name of the node created
- See
- node_setName¶
Node name changed
- Parameters
eventID –
hash(Node)
node – the node renamed
oldName – previous node name
newName – current node name
- See
- node_setParent¶
Indicates a change of parent node for a particular node.
- Parameters
eventID –
hash(Node)
node – node parented
nodeName – name of the node parented
oldParent – old parent node
oldParentName – old parent node name
newParent – new parent node
newParentName – new parent node name
- See
- node_setLocked¶
Node locked or unlocked
- Parameters
eventID –
hash(Node)
node – node locked
locked – boolean state of node lock
- See
- node_setBypassed¶
Node ignored
- Parameters
eventID –
hash(Node)
node – node locked
bypassed – boolean state of node bypass
- See
- node_setFloating¶
Node floating state changed
- Parameters
eventID –
hash(Node)
node – node floated
- See
- node_setHidden¶
Node hidden state changed
- Parameters
eventID –
hash(Node)
node – node hidden
- See
- node_setEdited¶
Node edit state changed
- Parameters
eventID –
hash(Node)
node – node edited
- See
- node_setViewed¶
Node view state changed
- Parameters
eventID –
hash(Node)
node – node viewed
- See
- node_setSelected¶
Node selection state changed
- Parameters
eventID –
hash(Node)
node – node selected
- See
- node_attributeEditorSetActive¶
AttributeEditor node active state changed
- Parameters
eventID –
hash(Node)
node – AttributeEditor node changed
- See
NodegraphAPI.SetAttributeEditorNodeActive()
- node_setPosition¶
Node moved in graph view
- Parameters
eventID –
hash(Node)
node – node moved
nodeName – name of the node moved
oldPosition – previous (x,y) position
newPosition – current (x,y) position
- See
- node_delete¶
Node destroyed
- Parameters
eventID –
hash(Node)
node – node in a zombie state
oldName – name of the node before death
- See
- node_addInputPort¶
Node input port added
- Parameters
eventID –
hash(Node)
node – node modified
nodeName – name of node modified
port – port object added
portName – name of new port
- See
- node_addOutputPort¶
Node output port added
- Parameters
eventID –
hash(Node)
node – node modified
nodeName – name of node modified
port – port object added
portName – name of new port
- See
- node_renameInputPort¶
Node input port renamed
- Parameters
eventID –
hash(Node)
node – node modified
nodeName – name of node modified
oldPortName – old name of renamed input port
newPortName – new name of renamed input port
- See
- node_renameOutputPort¶
Node output port renamed
- Parameters
eventID –
hash(Node)
node – node modified
nodeName – name of node modified
oldPortName – old name of renamed output port
newPortName – new name of renamed output port
- See
- node_removeInputPort¶
Node input port removed
- Parameters
eventID –
hash(Node)
node – node modified
nodeName – name of node modified
port – port object removed
portName – name of removed port
- See
- node_removeOutputPort¶
Node output port removed
- Parameters
eventID –
hash(Node)
node – node modified
nodeName – name of node modified
port – port object removed
portName – name of removed port
- See
- node_tagFlavor¶
Node flavor changed
- Parameters
eventID –
0
flavor – the flavor that was added, removed, or cleared
- See
NodegraphAPI.AddNodeFlavor()
,NodegraphAPI.RemoveNodeFlavor()
,NodegraphAPI.ClearFlavorNodes()
- parameter_setValue¶
Parameter’s value changed (during continuous manipulation)
- Parameters
eventID –
hash(Node)
param – parameter changed
node – parameter node
- See
- parameter_finalizeValue¶
Parameter’s value changed (on pen up)
- Parameters
eventID –
hash(Node)
param – parameter changed
node – parameter node
- See
- parameter_setKey¶
Key about to be added to parameter curve
- Parameters
eventID –
hash(Node)
param – parameter changed
keyTime – time of keyframe added
node – parameter node
- See
- parameter_removeKey¶
Key about to be removed from parameter curve
- Parameters
eventID –
hash(Node)
param – parameter changed
keyTime – time of keyframe changed
node – parameter node
- See
- parameter_removeKeys¶
Keys about to be removed from parameter curve
- Parameters
eventID –
hash(Node)
param – parameter changed
node – parameter node
- See
- parameter_moveKeys¶
Keys about to be moved on parameter curve
- Parameters
eventID –
hash(Node)
param – parameter changed
node – parameter node
- See
- parameter_createChild¶
Child parameter created
- Parameters
eventID –
hash(Node)
param – the parent parameter under which a child parameter has been created
paramName – the full name of the parent parameter
node – the node that contains the parent parameter and its new child
childParam – the child parameter that has been created
element – a PyXmlIO element representing the new child parameter
index – the index of the child parameter within its parent parameter
- See
NodegraphAPI.Parameter.createChildGroup()
,NodegraphAPI.Parameter.createChildNumber()
,NodegraphAPI.Parameter.createChildNumberArray()
,NodegraphAPI.Parameter.createChildString()
,NodegraphAPI.Parameter.createChildStringArray()
,NodegraphAPI.Parameter.createChildXmlIO()
,
- parameter_deleteChild¶
Child parameter deleted
- Parameters
eventID –
hash(Node)
param – the parent parameter under which a child parameter has been deleted
paramName – the full name of the parent parameter
node – the node that contains the parent parameter
childParam – the child parameter that has been deleted
element – a PyXmlIO element representing the deleted child parameter
childName – the name of the deleted child parameter
index – the previous index of the child parameter within its parent parameter
- See
- parameter_replaceXML¶
Parameter hierarchy changed
- Parameters
eventID –
hash(Node)
param – root parameter changed
paramName – root parameter name
oldXML – previous XML representation
newXML – current XML representation
node – parameter node
- See
NodegraphAPI.Parameter.replaceXML()
,NodegraphAPI.Parameter.replaceXmlIO()
- parameter_setAutoKeyAll¶
Global auto-key state changed
- Parameters
eventID –
0
- See
- port_connect¶
Ports of nodes have been connected
- Parameters
eventID –
hash(Port)
portA – The output port that was connected to an input port.
nodeNameA – The name of the node that contains the output port.
portNameA – The name of the output port that was connected.
portB – The input port that was connected to the output port.
nodeNameB – The name of the node that contains the input port.
portNameB – The name of the input port that was connected.
oldSourceNode – The name of a node that contained the output port that was previously connected to the input port, if any.
oldSourcePort – The name of an output port that was previously connected to the input port, if any.
- See
- port_disconnect¶
Ports of nodes have been disconnected
- Parameters
eventID –
hash(Port)
portA – The output port that was connected to an input port.
nodeNameA – The name of the node that contains the output port.
portNameA – The name of the output port that was connected.
portB – The input port that was connected to the output port.
nodeNameB – The name of the node that contains the input port.
portNameB – The name of the input port that was connected.
isPortASendPort – True if the upstream port A is a send port on the inside of a GroupNode, otherwise False.
isPortBReturnPort – True if the downstream port B is a return port on the inside of a GroupNode, otherwise False.
nodeAShapeAttrs – The node shape attributes of the node on which port A belongs.
nodeBShapeAttrs – The node shape attributes of the node on which port B belongs.
- See
- nodegraph_changed¶
Called once per idle when any action has changed the node graph.
- Parameters
eventID –
0
- nodegraph_setRootNode¶
A new root node has been set
- Parameters
eventID –
0
- See
- nodegraph_loadBegin¶
About to load nodes from a node graph document.
- Parameters
eventID –
0
- See
NodegraphAPI.ParseNodegraphXmlIO()
,NodegraphAPI.ParseNodesXmlIO()
- nodegraph_loadEnd¶
Finished loading nodes from a node graph document.
- Parameters
eventID –
0
- See
NodegraphAPI.ParseNodegraphXmlIO()
,NodegraphAPI.ParseNodesXmlIO()
- nodegraph_setCurrentTime¶
Current frame changed.
- Parameters
eventID –
0
currentTime – current frame
- See
- nodegraph_setTimeRange¶
inTime and outTime frames changed.
- Parameters
eventID –
0
- See
- nodegraph_setWorkingTimeRange¶
workingInTime and workingOutTime frames changed.
- Parameters
eventID –
0
- See
NodegraphAPI.SetWorkingInTime()
,NodegraphAPI.SetWorkingOutTime()
- nodegraph_setTimeIncrement¶
Time increment changed.
- Parameters
eventID –
0
- See
- nodegraph_registerType¶
New node type registered
- Parameters
eventID –
0
type – Name of the newly registered type
- See
NodegraphAPI.RegisterPythonNodeFactory()
,NodegraphAPI.RegisterPythonNodeType()
,`NodegraphAPI.RegisterPythonGroupType()
,`
- event_idle¶
Sent when each call to
Utils.EventModule.ProcessEvents()
is finished.