SUMMARY
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.
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:
def Hello(**kwargs):
print(kwargs.get('filename'))
from Katana import Callbacks
Callbacks.addCallback(Callbacks.Type.onSceneLoad, Hello)
Event Handlers
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:
from Katana import Utils print(sorted(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. The following is an example which prints the input arguments for the "node_create" event type:
def node_CreateCallback(eventType, eventID, **kwargs):
for i in kwargs.keys():
print(i)
Utils.EventModule.RegisterEventHandler(node_CreateCallback, 'node_create')
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:
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 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:
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))
Utils.EventModule.RegisterEventHandler(myParamCallback, "parameter_finalizeValue")
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:
Utils.EventModule.ProcessAllEvents()
For more information on callbacks and event handlers, please also see the Callbacks and Events section of our Katana Developer Guide.
Registering callbacks or event handlers on Katana startup
Callbacks or event handlers can be automatically registered when Katana starts up as follows:
- Define all the actions you want your callback or event handler function to perform in a single Python function and register this as demonstrated in the example code below:
from Katana import Utils, Callbacks
def PrefChangedCallback(eventType, eventID, prefKey, prefValue):
print(prefKey, "preference changed to:", prefValue)
Utils.EventModule.RegisterEventHandler(PrefChangedCallback, 'pref_changed')
def Hello(**kwargs):
print(kwargs.get('filename'))
Callbacks.addCallback(Callbacks.Type.onSceneLoad, Hello)
- 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, this is 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 Install Guide.
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
For further information about callbacks and event handlers, please see the Callbacks and Events section of the Katana Developer Guide.
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.
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