This article explains how to register callbacks or event handlers in Katana, and gives details about where to find information about the available callback and event types and expected input arguments for their callback functions.Documentation for callbacks and events can also be found in the Katana Developer Guide. The article below gives some practical examples for how they are implemented.

MORE INFORMATION

A callback is a piece of Python code added to the Katana environment that runs automatically when various events (such as creating a node or loading a script) happen in Katana.

An event is an action that occurs as a result of a user action or another source, such as a mouse being clicked, or a key being pressed. An event handler is a routine that is used to deal with the event, allowing a programmer to write code that will be executed when the event occurs (definitions from https://www.computerhope.com/jargon.htm).

Callbacks are triggered by Katana in certain situations (e.g. just before saving a file) and the calling code waits for a callback to be executed before continuing, allowing the user for example to modify the project before it's saved.

Conversely, events are queued up and processed "later" by Katana's event system. This means that callbacks are more immediate, but should also typically be very fast or they risk freezing the UI while they work.

Both callbacks and event handlers are useful in many situations, for example to change project settings when creating a new Katana project or to react to value changes of certain node parameters.

Callbacks

In Katana, callbacks are available for different situations, such as the software being launched, a Katana project being loaded or a node being created. To see a full list of available callbacks, please run the following code in the Python tab:

from Katana import Callbacks
print dir(Callbacks.Type)

To find out which keyword arguments are passed to each callback type, you can register the following callback that will print the input arguments when called:

def Hello(**kwargs):
for i in kwargs.keys():
print i

These arguments can be accessed within the callback function, for example as follows:

To find which input arguments are present for each event type, you can register the following handler for a particular event. When the event is triggered, the handler will print out the arguments:

def eventHandler(eventType, eventID, **kwargs):
for i in kwargs.keys():
print i

Once the input arguments are known, they can be used within the event handler function. The following is an example event handler which can be registered to listen for changes in the user preferences, and which will print out the name of the preference and its new value:

If an event handler function should, for example, react to the change of a particular node parameter only, it can be registered to listen for the ‘parameter_finalizeValue’ event. The name of the changed parameter can be checked within the handler function to determine if it is the relevant one:

Event handlers aren't necessarily executed immediately after the event has been queued. If any code relies on a certain event having been processed and event handlers executed, calling the following may be necessary:

Rename the file to init.py and make sure file extensions are shown in your file browser when you do this, to verify that the file extension is .py and not .txt or different.

Place the file either in the .katana folder or in a Startup folder under a path defined in the $KATANA_RESOURCES environment variable.

For more information on KATANA_RESOURCES, please see the corresponding topic in the Katana Online Help.

Next time Katana is launched, the callback function will be executed when the specified action occurs and the event handler function will be executed when the relevant event is queued and processed. In the example case above, when a preference is changed or Katana project is loaded, the new preference value or project file path respectively are printed out to the terminal.

FURTHER HELP

If you are encountering any issues in setting up your callbacks or event handlers, then please open a Support ticket and let us know about the issue and the troubleshooting steps you have taken so far.