Q100385: Callbacks and event handlers in Katana
This article explains how to register a callback or event handler in Katana, as well as where to find information about the available callback and event types, and the 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.
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).
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.
Whether you need to register a Callback or Event Handler depends on the type of event you would like to react to. Please read the sections below to find out how to see a list of available callbacks and event types.
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:
def Hello(**kwargs): print(kwargs.get('filename'))
from Katana import Callbacks Callbacks.addCallback(Callbacks.Type.onSceneLoad, Hello)
There are many different event types in Katana that registered handlers can listen for. To see a list of all available event types, please run the following in the Python tab:
import Utils.EventModule print Utils.EventModule.GetAllRegisteredEventTypes()
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 callback 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:
def PrefChangedCallback(eventType, eventID, prefKey, prefValue): print prefKey, "preference changed to:", prefValue Utils.EventModule.RegisterEventHandler(PrefChangedCallback, 'pref_changed')
Event handler for node parameter changes
If a callback function should, for example, react to the change of a particular node parameter only, an event handler can be registered to listen for the ‘parameter_finalizeValue’ event. The name of the changed parameter can be checked within the callback function to determine if it is the relevant one:
def myParamCallback(eventType, eventID, node, param): if (node.getName() == "CameraCreate") and (param.getName() == 'fov'): print("FOV for the following camera changed to " + repr(param.getValue(0)) + ": " + node.getParameter('name').getValue(0))
For more information on Callbacks and Event Handlers, please also see the Callbacks and Events section of our Katana Developer Guide.
Registering Callbacks on Katana startup
Callbacks can be automatically registered when Katana starts up as follows:
- Define all the actions you want your callback to perform in a single Python function and add this function as a callback or event handler, as demonstrated in the example code below:
from Katana import Utils, Callbacks def PrefChangedCallback(eventType, eventID, prefKey, prefValue): print prefKey, "preference changed to:", prefValue
def Hello(**kwargs): print(kwargs.get('filename'))
- Copy and paste this into a text editor, and save the file.
- 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 will be executed when the specified event occurs. 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.
If you are encountering any issues in setting up your callbacks, then please open a Support ticket and let us know the issue you are encountering and the troubleshooting steps you have taken so far.
For more information on how to open a Support ticket, please refer to Q100064: How to raise a support ticket
We're sorry to hear that!Please tell us why.