Porting to Qt 3.x

Qt 3.0.5

previous page next page
Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions

Porting to Qt 3.x

This document describes porting applications from Qt 2.x to Qt 3.x.

If you haven't yet made the decision about porting, or are unsure about whether it is worth it, take a look at the key features offered by Qt 3.x.

The Qt 3.x series is not binary compatible with the 2.x series. This means programs compiled for Qt 2.x must be recompiled to work with Qt 3.x. Qt 3.x is also not completely source compatible with 2.x, however all points of incompatibility cause compiler errors or run-time messages (rather than mysterious results). Qt 3.x includes many additional features and discards obsolete functionality. Porting from Qt 2.x to Qt 3.x is straightforward, and once completed makes the considerable additional power and flexibility of Qt 3.x available for use in your applications.

To port code from Qt 2.x to Qt 3.x:

  1. Briefly read the porting notes below to get an idea of what to expect.
  2. Be sure your code compiles and runs well on all your target platforms with Qt 2.x.
  3. Recompile with Qt 3.x. For each error, search below for related identifiers (e.g. function names, class names). This document mentions all relevant identifiers to help you get the information you need at the cost of being a little verbose.
  4. If you get stuck, ask on the qt-interest mailing list, or Trolltech Technical Support if you're a registered licensee.

Table of contents:

Link errors on Windows

On Windows, originally in Qt 2.x, the default configuration of the Qt library is static. If you just use the default configuration you don't need to set certain preprocessor defines. In Qt 3.0, the default configuration of the Qt library is to build it as a shared library, therefore the preprocessor define QT_DLL is needed.

If you use tmake with Qt 2.x, and now use qmake with Qt 3.x, then the cause of the problem is with the project file. In the project file, there is usually line that looks like:

CONFIG = ...

this should be changed to

CONFIG += ...

so that qmake can look at the configuration that Qt was built with and set any relevant preprocessor defines in the makefile.

Header file inclusion changes

Qt 3.x remove some unnecessary nested #include directives from header files. This speeds up compilation when you don't need those nested header files. But in some cases you will find you need to add an extra #include to your files.

For example, if you get a message about QStringList or its functions not being defined, then add #include <qstringlist.h> at the top of the file giving the error.

Header files that you might need to add #include directives for include:

  • <qcursor.h>
  • <qpainter.h>
  • <qpen.h>
  • <qstringlist.h>
  • <qregexp.h>
  • <qstrlist.h>
  • <qstyle.h>
  • <qvaluelist.h>

Namespace

Qt 3.x is namespace clean. A few global identifiers that had been left in Qt 2.x have been discarded.

Enumeration Qt::CursorShape and its values are now part of the special Qt class defined in qnamespace.h. If you get compilation errors about these being missing (unlikely, since most of your code will be in classes that inherit from the Qt namespace class), then apply the following changes:

The names of some debugging macro variables have been changed. We have tried not to break source compatibility as much as possible. If you observe error messages on the UNIX console or the Windows debugging stream that were previously disabled, please check these macro variables:

  • DEBUG becomes QT_DEBUG
  • NO_DEBUG becomes QT_NO_DEBUG
  • NO_CHECK becomes QT_NO_CHECK
  • CHECK_STATE becomes QT_CHECK_STATE
  • CHECK_RANGE becomes QT_CHECK_RANGE
  • CHECK_NULL becomes QT_CHECK_NULL
  • CHECK_MATH becomes QT_CHECK_MATH

The name of some debugging macro functions has been changed as well but source compatibility should not be affected if the macro variable QT_CLEAN_NAMESPACE is not defined:

  • ASSERT becomes Q_ASSERT
  • CHECK_PTR becomes Q_CHECK_PTR

For the record, undocumented macro variables that are not part of the API have been changed:

  • _OS_*_ becomes Q_OS_*
  • _WS_*_ becomes Q_WS_*
  • _CC_*_ becomes Q_CC_*

Removed Functions

All these functions have been removed in Qt 3.x:

  • QFont::charSet()
  • QFont::setCharSet()
  • QMenuBar::setActItem()
  • QMenuBar::setWindowsAltMode()
  • QPainter::drawQuadBezier()
  • QPointArray::quadBezier()
  • QRegExp::find()
  • QSpinBox::downButton()
  • QSpinBox::upButton()
  • QString::basicDirection()
  • QString::visual()
  • QStyle::set...() functions
  • QWidget::setFontPropagation()
  • QWidget::setPalettePropagation()

Also, to avoid conflicts with <iostream>, the following three global functions have been renamed:

  • setw() (renamed qSetW())
  • setfill() (renamed qSetFill())
  • setprecision() (renamed qSetPrecision())

Obsoleted Functions

The following functions have been obsoleted in Qt 3.0. The documentation of each of these functions should explain how to replace them in Qt 3.0.

Warning: It is best to consult http://doc.trolltech.com/3.0/ rather than the documentation supplied with Qt to obtain the latest information regarding obsolete functions and how to replace them in new code.

Additionally, these preprocessor directives have been removed:

  • #define strlen qstrlen
  • #define strcpy qstrcpy
  • #define strcmp qstrcmp
  • #define strncmp qstrncmp
  • #define stricmp qstricmp
  • #define strnicmp qstrnicmp

See the changes-3.0.0 document for an explanation of why this had to be done. You might have been relying on the non-portable and unpredictable behavior resulting from these directives. We strongly recommend that you either make use of the safe qstr* variants directly or ensure that no 0 pointer is passed to the standard C functions in your code base.

Collection Class Renaming

The classes QArray, QCollection, QList, QListIterator, QQueue, QStack and QVector have been renamed. To ease porting, the old names and the old header-file names are still supported.

Old Name New Name New Header File
QArray QMemArray <qmemarray.h>
QCollection QPtrCollection <qptrcollection.h>
QList QPtrList <qptrlist.h>
QListIterator QPtrListIterator <qptrlist.h>
QQueue QPtrQueue <qptrqueue.h>
QStack QPtrStack <qptrstack.h>
QVector QPtrVector <qptrvector.h>

QButtonGroup

In Qt 2.x, the function QButtonGroup::selected() returns the selected radio button (QRadioButton). In Qt 3.0, it returns the selected toggle button (QButton::toggleButton), a more general concept. This might affect programs that use QButtonGroups that contain a mixture of radio buttons and non-radio (e.g. QCheckBox) toggle buttons.

QDate

Two QDate member functions that were virtual in Qt 2.0 are not virtual in Qt 3.0. This is only relevant if you subclassed QDate and reimplemented these functions:

In addition to no longer being virtual, QDate::monthName() and QDate::dayName() have been renamed QDate::shortMonthName() and QDate::shortDayName() and have been made static (as they should had been in the first place). The old names are still provided for source compatibility.

QFont

The internals of QFont have changed significantly between Qt 2.2 and Qt 3.0, to give better Unicode support and to make developing internationalized applications easier. The original API has been preserved with minimal changes. The CharSet enum and its related functions have disappeared. This is because Qt now handles all charset related issues internally, and removes this burden from the developer.

If you used the CharSet enum or its related functions, e.g QFont::charSet() or QFont::setCharSet(), just remove them from your code. There are a few functions that took a QFont::CharSet as a parameter; in these cases simply remove the charset from the parameter list.

QInputDialog

The two static getText(...) methods in QInputDialog have been merged. The echo parameter is the third parameter and defaults to QLineEdit::Normal.

If you used calls to QInputDialog::getText(...) that provided more than the first two required parameters you will must add a value for the echo parameter.

QLayout and Other Abstract Layout Classes

The definitions of QGLayoutIterator, QLayout, QLayoutItem, QLayoutIterator, QSpacerItem and QWidgetItem have been moved from <qabstractlayout.h> to <qlayout.h>. The header <qabstractlayout.h> now includes <qlayout.h> for compatibility. It might be removed in a future version.

QMultiLineEdit

The QMultiLineEdit was a simple editor widget in previous Qt versions. Since Qt 3.0 includes a new richtext engine, which also supports editing, QMultiLineEdit is obsolete. For the sake of compatibility QMultiLineEdit is still provided. It is now a subclass of QTextEdit which wraps the old QMultiLineEdit so that it is mostly source compatible to keep old applications working.

For new applications and when maintaining existing applications we recommend that you use QTextEdit instead of QMultiLineEdit wherever possible.

Although most of the old QMultiLineEdit API is still available, there is one important difference. The old QMultiLineEdit operated in terms of lines, whereas QTextEdit operates in terms of paragraphs. This is because lines change all the time during wordwrap, whereas paragraphs remain paragraphs. The consequence of this change is that functions which previously operated on lines, e.g. numLines(), textLine(), etc., now work on paragraphs.

Also the function getString() has been removed since it published the internal data structure.

In most cases, applications that used QMultiLineEdit will continue to work without problems. Applications that worked in terms of lines may require some porting.

The source code for the old 2.x version of QMultiLineEdit can be found in $QTDIR/src/attic/qtmultilineedit.h/cpp. Note that the class has been renamed to QtMultiLineEdit to avoid name clashes. If you really need to keep compatibility with the old QMultiLineEdit, simply include this class in your project and rename QMultiLineEdit to QtMultiLineEdit throughout.

QPrinter

QPrinter has undergone some changes, to make it more flexible and to ensure it has the same runtime behaviour on both Unix and Windows. In 2.x, QPrinter behaved differently on Windows and Unix, when using view transformations on the QPainter. This has changed now, and QPrinter behaves consistently across all platforms. A compatibilty mode has been added that forces the old behaviour, to ease porting from Qt 2.x to Qt 3.x. This compatibilty mode can be enabled by passing the QPrinter::Compatible flag to the QPrinter constructor.

On X11, QPrinter used to generate encapsulated postscript when fullPage() was TRUE and only one page was printed. This does not happen by default anymore, providing a more consistent printing output.

QRegExp

The QRegExp class has been rewritten to support many of the features of Perl regular expressions. Both the regular expression syntax and the QRegExp interface have been modified.

Be also aware that <qregexp.h> is no longer included automatically when you include <qstringlist.h>. See above for details.

New special characters

There are five new special characters: (, ), {, | and } (parentheses, braces and pipe). When porting old regular expressions, you must add \ (backslash) in front of any of these (actually, \\ in C++ strings), unless it is already there.

Example: Old code like 

    QRegExp rx( "([0-9|]*\\)" );        // works in Qt 2.x
should be converted into 
    QRegExp rx( "\\([0-9\\|]*\\)" );      // works in Qt 2.x and 3.x
(Within character classes, the backslash is not necessary in front of certain characters, e.g. |, but it doesn't hurt.)

Wildcard patterns need no conversion. Here are two examples: 

    QRegExp wild( "(*.*)" );
    wild.setWildcard( TRUE );

    // TRUE as third argument means wildcard
    QRegExp wild( "(*.*)", FALSE, TRUE );
However, when they are used, make sure to use QRegExp::exactMatch() rather than the obsolete QRegExp::match(). QRegExp::match(), like QRegExp::find(), tries to find a match somewhere in the target string, while QRegExp::exactMatch() tries to match the whole target string.

QRegExp::operator=()

This function has been replaced by QRegExp::setPattern() in Qt 2.2. Old code such as 

    QRegExp rx( "alpha" );
    rx.setCaseSensitive( FALSE );
    rx.setWildcard( TRUE );
    rx = "beta";
still compiles with Qt 3, but produces a different result (the case sensitivity and wildcard options are forgotten). This way, 
    rx = "beta";
is the same as 
    rx = QRegExp( "beta" );
which is what one expects.

QRegExp::match()

The following function is now obsolete, as it has an unwieldy parameter list and was poorly named:

  • bool QRegExp::match( const QString & str, int index = 0, int * len = 0, bool indexIsStart = TRUE ) const
It will be removed in a future version of Qt. Its documentation explains how to replace it.

QRegExp::find()

This function was removed, after a brief appearance in Qt 2.2. Its name clashed with QString::find(). Use QRegExp::search() or QString::find() instead.

QString::findRev() and QString::contains()

QString::findRev()'s and QString::contains()'s semantics have changed between 2.0 and 3.0 to be more consistent with the other overloads.

For example, 

    QString( "" ).contains( QRegExp("") )
returns 1 in Qt 2.0; it returns 0 in Qt 3.0. Also, "^" now really means start of input, so 
    QString( "Heisan Hoppsan" ).contains( QRegExp("^.*$") )
returns 1, not 13 or 14.

This change affect very few existing programs.

QString::replace()

With Qt 1.0 and 2.0, a QString is converted implicitly into a QRegExp as the first argument to QString::replace(): 

    QString text = fetch_it_from_somewhere();
    text.replace( QString("[A-Z]+"), "" );
With Qt 3.0, the compiler gives an error. The solution is to use a QRegExp cast: 
    text.replace( QRegExp("[A-Z]+"), "" );
This change makes it possible to introduce a QString::replace(QString, QString) overload in a future version of Qt without breaking source compatibility.

QSemiModal

The QSemiModal class is now obsolete. You should call show() on a modal dialog instead.

QSortedList

The QSortedList class is now obsolete. Consider using a QDict, a QMap or a plain QPtrList instead.

QTableView

The QTableView class has been obsoleted and is no longer a part of the Qt API. Either use the powerful QTable class or the simplistic QGridView in any new code you create. If you really need the old table view for compatibility you can find it in $QTDIR/src/attic/qttableview.{cpp,h}. Note that the class has been renamed from QTableView to QtTableView to avoid name clashes. To use it, simply include it in your project and rename QTableView to QtTableView throughout.

QToolButton

The QToolButton class used to distinguish between "on" and "off" icons. In 3.0, this mechanism was moved into the QIconSet class (see QIconSet::State).

The old QToolButton::onIconSet and QToolButton::offIconSet properties are still provided so that old source will compile, but their semantics have changed: they are now synonyms for QToolButton::iconSet. If you used that distinction in Qt 2.x, you will need to adjust your code to use the QIconSet On/Off mechanism.

Likewise, the on parameter of these two functions is now ignored:

  • void QToolButton::setIconSet ( const QIconSet & set, bool on )
  • QIconSet QToolButton::iconSet ( bool on ) const

These functions are only provided for ease of porting. New code should use the following instead:

Finally, this function is no longer virtual:

  • void QToolButton::setIconSet( const QIconSet & set, bool on )

If you have a class that inherits QToolButton and that reimplements QToolButton::setIconSet(), you should make the signature of the reimplementation agree with the new QToolButton::setIconSet(), a virtual function.

QTextStream

The global QTextStream manipulators setw(), setfill() and setprecison() were renamed to qSetW(), qSetFill() and qSetPrecision() to avoid conflicts with <iostream.h>. If you used them, you must rename the occurrences to the new names.

QTranslator

The QTranslator class was extended in Qt 2.2, and these extensions lead to a new interface. This interface is used mainly by translation tools (for example, Qt Linguist). For source compatibility, no member function was effectively removed. The QTranslator documentation points out which functions are obsolete.

This function is no longer virtual:

If you have a class that inherits QTranslator and which reimplements QTranslator::find(), you should reimplement QTranslator::findMessage() instead. In fact, find() is now defined in terms of findMessage(). By doing the conversion, you will also gain support for translator comments and for any future extensions.

QWidget

QWidget::backgroundColor(), QWidget::setBackgroundColor(), QWidget::backgroundPixmap() and QWidget::setBackgroundPixmap() have often been the source of much confusion in previous releases. Qt 3.0 addresses this by obsoleting these functions and by remplacing them with eight new functions: QWidget::eraseColor(), QWidget::setEraseColor(), QWidget::erasePixmap(), QWidget::setErasePixmap(), QWidget::paletteBackgroundColor(), QWidget::setPaletteBackgroundColor(), QWidget::paletteBackgroundPixmap() and QWidget::setPaletteBackgroundPixmap(). See their documentation for details.

QXml Classes

QXmlInputSource

The semantics of QXmlInputSource has changed slightly. This change only affects code that parses the same data from the same input source multiple times. In such cases you must call QXmlInputSource::reset() before the second call to QXmlSimpleReader::parse().

So code like 

    QXmlInputSource source( &xmlFile );
    QXmlSimpleReader reader;
    ...
    reader.parse( source );
    ...
    reader.parse( source );
must be changed to 
    QXmlInputSource source( &xmlFile );
    QXmlSimpleReader reader;
    ...
    reader.parse( source );
    ...
    source.reset();
    reader.parse( source );

QXmlLocator

Due to some internal changes, it was necessary to clean-up the semantics of QXmlLocator: this class is now an abstract class. This shouldn't cause any problems, since programmers usually used the QXmlLocator that was reported by QXmlContentHandler::setDocumentLocator(). If you used this class in some other way, you must adjust your code to use the QXmlLocator that is reported by the QXmlContentHandler::setDocumentLocator() function.

Asynchronous I/O Classes

QASyncIO, QDataSink, QDataSource, QIODeviceSource and QDataPump were used internally in previous versions of Qt, but are not used anymore. They are now obsolete.

Transparent widgets

In Qt 2.x, the AutoMask property was used to obtain a transparent-looking widget. In general, this approach is slow and processor hungry. Qt 3.0 uses the BackgroundOrigin which provides vastly improved performance and more flexibility in most cases. The few classes for which the AutoMask property is still the best approach are QCheckBox, QComboBox, QPushButton, QRadioButton and QTabWidget.

Bezier Curves

The function names for Bezier curves in QPainter and QPointArray have been corrected. They now properly reflect their cubic form instead of a quadratic one. If you have been using either QPainter::drawQuadBezier() or QPointArray::quadBezier() you must replace these calls with

respectively. Neither the arguments nor the resulting curve have changed.

Locale-aware String Comparisons in QIconView, QListBox, QListView and QTable

In Qt 2.x, QString only provided string comparisons using the Unicode values of the characters of a string. This is efficient and reliable, but it is not the appropriate order for most languages. For example, French users expect 'é' (e acute) to be treated essentially as 'e' and not put after 'z'.

In Qt 3.0, QString::localeAwareCompare() implements locale aware string comparisions on certain platforms. The classes QIconView, QListBox, QListView and QTable now use QString::localeAwareCompare() instead of QString::compare(). If you want to control the behaviour yourself you can always reimplement QIconViewItem::compare(), QListBox::text(), QListViewItem::compare() or QTableItem::key() as appropriate.

Copyright © 2002 TrolltechTrademarks
Qt version 3.0.5

previous page start next page