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 a QT4Widgets.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 a QScrollArea-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