Maya ships with only that subset of the Qt libraries which it uses itself. Plug-in developers wanting to work with Qt will have to install Qt separately to gain access to the Qt header files and those libraries not included with Maya. The Linux environments (64-bit), Mac OS X environment and Windows environment (32-bit and 64-bit) sections of Maya's API Guide provide instructions on how to install the correct version of Qt on each platform supported by Maya.
If you were writing your own Qt application from scratch, you would need to create your own QCoreApplication or QApplication instance to handle your application's event loop. When writing a Maya plug-in, you must instead use Maya's own application object which can be retrieved using Qt's qApp macro. The example code below uses the qApp macro to retrieve Maya's application name:
QCoreApplication* app = qApp;
if (app) {cout << "Application name is '" << app->applicationName().toStdString() << "'" << endl;
}
Creating new windows and dialogs using Qt is done the same way as you would if you were writing a standalone Qt application. The helixQtCmd plug-in in the devkit gives a very simple example of this. The plug-in provides the helixQt command which creates a Qt-based button. Whenever the button is pressed it uses API calls to create a helical curve within Maya.
The button is a regular Qt pushButton with a createHelix() slot added to handle the creation of the curve.
class HelixButton : public QPushButton
{Q_OBJECT
public:
HelixButton(const QString& text, QWidget* parent = 0);
virtual ~HelixButton();
public slots:
void createHelix(bool checked);
};
Whenever the helixQt command is executed, it first checks to see if the button already exists. If not then it creates the button and connects its clicked signal to its createHelix slot, so that whenever the button is clicked the code to create the helix will be executed:
QPointer HelixQtCmd::button;
MStatus HelixQtCmd::doIt(const MArgList& /* args */)
{ if (button.isNull()) { button = new HelixButton("Create Helix");button->connect(button, SIGNAL(clicked(bool)), button, SLOT(createHelix(bool)));
button->show();
}
If the button already exists, then the command simply ensures that it is visible and not hidden beneath other windows:
else {button->showNormal();
button->raise();
}
return MS::kSuccess;
}
Controls created directly using Qt are not in general recognized by Maya's UI commands. The lsUI command does not list them and the commands for specific types of controls, such as button, do not recognize them. The generic control command is an exception, though. So long as the control has been given a unique name, then the control command can be used to test for its existence and perform basic operations on the control such as setting its visibility.
For example, if the createHelix method of the helixQtCmd plug-in had given the button the unique name of "myButton":
button = new HelixButton("Create Helix"); button->setObjectName("myButton");The following MEL script could then be used to hide the button:
if (`control -q -exists myButton`) {control -e -visible false myButton;
}
However, the same code using the button command would not work because button only recognizes those buttons that it created:
if (`button -q -exists myButton`) { // Will always be false.button -e -visible false myButton; // Will never be executed.
}
It may sometimes be desirable to use Qt to directly access UI elements created using Maya commands. The MQtUtil API class provides methods for retrieving the Qt object underlying a Maya control, layout, window or menu item. For example, if you have a Maya checkBox control named "myCheckBox" which was created with the following MEL script:
window;
columnLayout;
checkBox myCheckBox;
showWindow;
You can use the MQtUtil class to retrieve the checkBox's QWidget pointer, and from that determine the current state of the checkBox:
QWidget* control = MQtUtil::findControl("myCheckBox");if (control) {QCheckBox* cb = qobject_cast(control);
if (cb) { if (cb->isChecked()) { MGlobal::displayInfo("myCheckBox is checked"); } else { MGlobal::displayInfo("myCheckBox is not checked");}
}
}
The example above also serves to illustrate why you must always be careful using MQtUtil. The code will only work if Maya's checkBox command creates a QCheckBox widget or something derived from QCheckBox. While that may be the case in the current version of Maya, it could change in some future version. If you write code which uses Qt to directly access UI elements created using Maya commands, then it is up to you to ensure that your code still behaves as expected in each new release of Maya.
Layouts are an even greater minefield of potential problems:
See MQtUtil for a more in-depth discussion of these and other issues surrounding layouts.
For all of these reasons, the use of MQtUtil should be considered a last resort. It is available if necessary, but requires a lot of care and experimentation to get the right results.
The Qt libraries supplied by Maya include some customizations, so when linking a plug-in with Qt, it is important that Maya's Qt libraries appear in the link path before those in your separate Qt installation. The simplest way of doing this is to use the Makefile.qt supplied in the Maya devkit to build your plug-in from the command line. For example:
Makefile.qt uses Qt's qmake command to control the building of the plug-in. This requires the plug-in to have a qmake project file ending with the extension .pro.
helixQtCmd.pro, shown below, is the project file provided in the devkit for the helixQtCmd plug-in. It provides a good example of the straightforward nature of the majority of project files.
include(qtconfig)
TARGET = helixQtCmd
HEADERS += helixQtCmd.h
SOURCES += helixQtCmd.cpp
LIBS += -lOpenMayaUI
The TARGET setting contains the name of the plug-in, excluding its platform-specific extension.
The HEADERS setting contains a space-separated list of all the header files which are part of the plug-in.
The SOURCES setting contains a space-separated list of all the source files which are part of the plug-in.
By default, the plug-in is automatically linked to Maya's Foundation and OpenMaya libraries. If the plug-in needs other libraries, then they should be added to the LIBS setting. Library names should be preceded by '-l' while additional library directories should be specified using '-L'. For example:
LIBS += -L/usr/local/lib -lxml
For more complex needs, please refer to Qt's qmake documentation.
All of the example Qt plug-ins are built in release (that is, non-debug) mode. To build them for debug, turn on qmake's debug configuration parameter by doing the following in your .pro file:
CONFIG += debug
That should be sufficient to build your plug-in for debug on Linux and OS X. Unfortunately, on Windows, the debug configuration setting does not just compile your plug-in with debugging information, but it also forces the plug-in to link with the debug versions of the Qt libraries. That makes the plug-in incompatible with Maya, which was linked using the release versions of the Qt libraries. Depending upon which Qt classes your plug-in uses, it may or may not load into Maya, but even if it does successfully load, it is unlikely to perform correctly since it will not have access to Maya's QCoreApplication or other Qt global values.To get around this, set the debug configuration parameter described above and build the intermediate makefiles using the following command, substituting the name of your plug-in for myPlugin:
nmake /f Makefile.qt myPlugin.mak
This generates, among other things, a .mak.Debug file for your plug-in (for example, myPlugin.mak.Debug). Edit that file, find the LIBS line, and replace all of the debug Qt libraries with their non-debug versions by removing the final d from their names. For example, in helixQtCmd.mak.Debug the LIBS line would initially look like this:
LIBS = /LIBPATH:..\..\lib ..\..\lib\OpenMaya.lib ..\..\lib\Foundation.lib ..\..\lib\OpenMayaUI.lib c:\Qt\4.5.3\lib\QtGuid4.lib c:\Qt\4.5.3\lib\QtCored4.lib`
You would replace QtGuid4.lib with QtGui4.lib, and QtCored4.lib with QtCore4.lib, leaving you with this:
LIBS = /LIBPATH:..\..\lib ..\..\lib\OpenMaya.lib ..\..\lib\Foundation.lib ..\..\lib\OpenMayaUI.lib c:\Qt\4.5.3\lib\QtGui4.lib c:\Qt\4.5.3\lib\QtCore4.lib`
Now use the modified .mak.Debug file to explicitly build your plug-in:
nmake /f myPlugin.mak.Debug debug\myPlugin.mll
This still leaves one potential problem area on Windows. Qt's QList template class provides inline methods which can create and destroy Qt objects. Because those methods are inlined, if they are called by plug-in code which has been built for debug, any objects created or deleted will use the memory allocator from the debug version of Microsoft's C Runtime Library. If the methods are called within Maya, they will use the release version of the C Runtime Library. Thus it is possible to get situations where objects are allocated within Maya using the release runtime library and deleted in the plug-in using the debug runtime library, or vice-versa. Since the release and debug versions of Microsoft's C Runtime Library are incompatible with each other, this can lead to crashes.
At the moment, QList is the only Qt class we are aware of which has this potential for failure, but other Qt template classes could exhibit similar problems. To date, the only known workarounds are either to avoid the use of Qt template classes in your code, or to only build your plug-in in release mode on Windows.