
Search is based on keyword.
Ex: "Procedures"
Do not search with natural language
Ex: "How do I write a new procedure?"
Q100476: Upgrading Qt based UI plugins for Katana 3.1v1 and above
Warning: This article contains links to external websites
SUMMARY
Python scripts or plugins that import PyQt4 modules will fail with an ImportError in Katana 3.1v1. This is because the PyQt4 Python package is no longer available in this version due to an upgrade to Katana’s Qt and PyQt library versions.
This article provides an overview of the changes between these versions and gives instructions on how to upgrade existing scripts and plugins so that they can be used in Katana 3.1v1 and above.
MORE INFORMATION
As part of the 3.1v1 release, the Qt Library version used by Katana has been updated from 4.8.5 to 5.6.1, as specified in the VFX Reference Platform CY2017.
This means that any UI plugins that utilize Qt will need to be updated before being used within Katana 3.1v1 and later.
As a result of this update from Qt 4 to Qt 5, starting with Katana 3.1v1 the modules contained in the PyQt4 Python package are no longer callable. While PyQt4’s QtCore
module has a direct equivalent in PyQt5, PyQt4’s QtGui
module has been split up into several modules including QtGui
and QtWidgets
in PyQt5.
In most cases when using the PyQt4.QtGui
module, a script or plugin can be ported to PyQt5 by replacing the following statement:
import PyQt4.QtGui
From Katana 3.1v1 this should be substituted with the following:
import PyQt5.QtGui import PyQt5.QtWidgets as QtGui
To allow Python scripts and plugins using Qt to continue working with versions of Katana below 3.1v1, try and except blocks can be used to handle any errors encountered when importing PyQt modules.
This can be set up as demonstrated in the following snippet:
try: from PyQt4 import QtGui, QtCore except ImportError: from PyQt5 import QtCore, QtGui from PyQt5 import QtWidgets as QtGui
If more than one flavor of Qt bindings for Python need to be supported in the same code base (e.g. PyQt4/5, PySide), it may be a good workflow to use the Qt.py shim. For more information please visit the following link: https://github.com/mottosso/Qt.py
In addition to the changes detailed above, the following updates should be made to UI plugins using the respective functionality:
- Any Qt widget that opted into Katana's 'key-based-dragging' protocol must be updated as follows. Previously, Katana would emit a dynamic PyQt keyBasedDragRequested signal from a widget when the user hovered the mouse over it and pressed Ctrl+B. As of Katana 3.1, your widget must instead override the customEvent() method to handle
QT4Widgets.GlobalEventFilter.KeyBasedDragEvent
Qt events. A widget should accept the event, and initiate a drag using aQT4Widgets.InteractiveDrag
object. - Any Qt widget that previously set a Python attribute of drawInteractiveHighlight to False should now set a boolean
QObject
property of the same name instead. This property allows a widget to opt out of the standard highlight effect Katana applies to a target widget of a drag-and-drop operation. - Any Qt widget that previously set a Python attribute of STOP_GLOBAL_SCROLLING or SKIP_GLOBAL_SCROLLING should now set a boolean
QObject
property of the same name instead. This property allows a widget to opt out of Katana's default 'global scrolling' behaviour, initiated by holding Alt and dragging with the middle mouse button while the cursor is over aQScrollArea
-based widget.
FURTHER READING
For information about other changes in Katana 3.1v1, please see the Katana 3.1v1 Release Notes.
For more information on which libraries relevant to the VFX Reference Platform are included in or used by Katana 3.1, please see the Katana Developer Guide.
For more information on differences between PyQt4 and PyQt5, please review the PyQt5 reference guide via the following link: PyQt5 - Differences between PyQt4 and PyQt5
For more information on which functions exist in PyQt5’s QtGui and QtWidgets modules respectively, please review the PyQt5 reference guide via the following links:
PyQt5 QtGui functions
PyQt5 QtWidgets functions
To learn more about handling Python exceptions, please see the Python documentation on exceptions at the following link: Python Documentation - Handling Exceptions
Sorry you didn't find this helpful
Why wasn't this helpful? (check all that apply)
Thanks for your feedback.
If you can't find what you're looking for or you have a workflow question, please try Foundry Support.
If you have any thoughts on how we can improve our learning content, please email the Documentation team using the button below.
Thanks for taking time to give us feedback.