<tdalign="right"valign="center"><imgsrc="logo32.png"align="right"width="64"height="32"border="0"></td></tr></table><h1align=center>Porting to Qt 3.x</h1>
<p> This document describes porting applications from Qt 2.x to Qt 3.x.
<p> 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 <em>source</em> 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.
<p> To port code from Qt 2.x to Qt 3.x:
<p><oltype=1>
<p><li> Briefly read the porting notes below to get an idea of what to expect.
<li> Be sure your code compiles and runs well on all your target platforms
with Qt 2.x.
<li> 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.
<li> If you get stuck, ask on the <ahref="http://qt-interest.trolltech.com/">qt-interest</a> mailing list, or Trolltech Technical Support if
you're a registered licensee.
<p></ol>
<p> Table of contents:
<p><!-- toc -->
<ul>
<li><ahref="#1"> Link Errors on Windows
</a>
<li><ahref="#2"> Header file inclusion changes
</a>
<li><ahref="#3"> Namespace
</a>
<li><ahref="#4"> Removed Functions
</a>
<li><ahref="#5"> Obsoleted Functions
</a>
<li><ahref="#6"> Collection Class Renaming
</a>
<li><ahref="#7"> QButtonGroup
</a>
<li><ahref="#8"> QDate
</a>
<li><ahref="#9"> QFileDialog
</a>
<li><ahref="#10"> QFont
</a>
<li><ahref="#11"> QInputDialog
</a>
<li><ahref="#12"> QLayout and Other Abstract Layout Classes
</a>
<li><ahref="#13"> QListViewItem
</a>
<li><ahref="#14"> QMoveEvent
</a>
<li><ahref="#15"> QMultiLineEdit
</a>
<li><ahref="#16"> QPrinter
</a>
<li><ahref="#17"> QRegExp
</a>
<ul>
<li><ahref="#17-1"> New special characters
</a>
<li><ahref="#17-2"> QRegExp::operator=()
</a>
<li><ahref="#17-3"> QRegExp::match()
</a>
<li><ahref="#17-4"> QRegExp::find()
</a>
<li><ahref="#17-5"> QString::findRev() and QString::contains()
</a>
<li><ahref="#17-6"> QString::replace()
</a>
</ul>
<li><ahref="#18"> QSemiModal
</a>
<li><ahref="#19"> QSortedList
</a>
<li><ahref="#20"> QTableView
</a>
<li><ahref="#21"> QToolButton
</a>
<li><ahref="#22"> QTextStream
</a>
<li><ahref="#23"> QTranslator
</a>
<li><ahref="#24"> QWidget
</a>
<li><ahref="#25"> QXml Classes
</a>
<ul>
<li><ahref="#25-1"> QXmlInputSource
</a>
<li><ahref="#25-2"> QXmlLocator
</a>
</ul>
<li><ahref="#26"> Asynchronous I/O Classes
</a>
<li><ahref="#27"> Transparent widgets
</a>
<li><ahref="#28"> Bezier Curves
</a>
<li><ahref="#29"> Locale-aware String Comparisons in QIconView, QListBox,
QListView and QTable
</a>
</ul>
<!-- endtoc -->
<p><aname="Linkerrors"></a>
<h2> Link Errors on Windows
</h2>
<aname="1"></a><p> 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 <tt>QT_DLL</tt> is needed.
<p> 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:
<p><tt>CONFIG</tt> = ...
<p> this should be changed to
<p><tt>CONFIG</tt> += ...
<p> so that qmake can look at the configuration that Qt was built with and
set any relevant preprocessor defines in the makefile.
<p><aname="Headers"></a>
<h2> Header file inclusion changes
</h2>
<aname="2"></a><p> 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.
<p> For example, if you get a message about <ahref="qstringlist.html">QStringList</a> or its functions
not being defined, then add <tt>#include <qstringlist.h></tt> at
the top of the file giving the error.
<p> Header files that you might need to add #include directives for include:
<ul>
<li><tt><qcursor.h></tt>
<li><tt><qpainter.h></tt>
<li><tt><qpen.h></tt>
<li><tt><qstringlist.h></tt>
<li><tt><qregexp.h></tt>
<li><tt><qstrlist.h></tt>
<li><tt><qstyle.h></tt>
<li><tt><qvaluelist.h></tt>
</ul>
<p><h2> Namespace
</h2>
<aname="3"></a><p> Qt 3.x is namespace clean. A few global identifiers that had been
left in Qt 2.x have been discarded.
<p> Enumeration <ahref="qt.html#CursorShape-enum">Qt::CursorShape</a> and its values are now part of the
special <ahref="qt.html">Qt</a> 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
<li><ahref="qcolorgroup.html#QColorGroup">QColorGroup::QColorGroup</a>( const <ahref="qcolor.html">QColor</a>& foreground, const QColor & background, const QColor & light, const QColor & dark, const QColor & mid, const QColor & text, const QColor & base )
<li><ahref="qfontdatabase.html#font">QFontDatabase::font</a>( const QString & familyName, const QString & style, int pointSize, const QString & )
<li><ahref="qfontdatabase.html#isBitmapScalable">QFontDatabase::isBitmapScalable</a>( const QString & family, const QString & style, const QString & ) const
<li><ahref="qfontdatabase.html#isFixedPitch">QFontDatabase::isFixedPitch</a>( const QString & family, const QString & style, const QString & ) const
<li><ahref="qfontdatabase.html#isScalable">QFontDatabase::isScalable</a>( const QString & family, const QString & style, const QString & ) const
<li><ahref="qfontdatabase.html#isSmoothlyScalable">QFontDatabase::isSmoothlyScalable</a>( const QString & family, const QString & style, const QString & ) const
<li><ahref="qfontdatabase.html#italic">QFontDatabase::italic</a>( const <ahref="qstring.html">QString</a>& family, const QString & style, const QString & ) const
<li><ahref="qfontdatabase.html#pointSizes">QFontDatabase::pointSizes</a>( const QString & family, const QString & style, const QString & )
<li><ahref="qfontdatabase.html#smoothSizes">QFontDatabase::smoothSizes</a>( const QString & family, const QString & style, const QString & )
<li><ahref="qfontdatabase.html#styles">QFontDatabase::styles</a>( const QString & family, const QString & ) const
<li><ahref="qfontdatabase.html#weight">QFontDatabase::weight</a>( const QString & family, const QString & style, const QString & ) const
<li><ahref="qstyle.html#tabbarMetrics">QStyle::tabbarMetrics</a>( const <ahref="qwidget.html">QWidget</a> *t, int & hf, int & vf, int & ov ) const
<aname="7"></a><p> In Qt 2.x, the function <ahref="qbuttongroup.html#selected">QButtonGroup::selected</a>() returns the selected
<em>radio</em> button (<ahref="qradiobutton.html">QRadioButton</a>). In Qt 3.0, it returns the selected <em>toggle</em> button (<ahref="qbutton.html#toggleButton-prop">QButton::toggleButton</a>), a more general concept.
This might affect programs that use QButtonGroups that contain a
mixture of radio buttons and non-radio (e.g. <ahref="qcheckbox.html">QCheckBox</a>) toggle buttons.
<p><h2><ahref="qdate.html">QDate</a>
</h2>
<aname="8"></a><p> 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:
<p><ul>
<li><ahref="qstring.html">QString</a><ahref="qdate.html#monthName">QDate::monthName</a>( int month ) const
<li> QString <ahref="qdate.html#dayName">QDate::dayName</a>( int weekday ) const
</ul>
<p> In addition to no longer being virtual, QDate::monthName() and
QDate::dayName() have been renamed <ahref="qdate.html#shortMonthName">QDate::shortMonthName</a>() and
<ahref="qdate.html#shortDayName">QDate::shortDayName</a>() and have been made static (as they should had
been in the first place). The old names are still provided for source
compatibility.
<p><h2><ahref="qfiledialog.html">QFileDialog</a>
</h2>
<aname="9"></a><p> If the mode was not set explicitly, and the user entered a
non-existent file, the dialog would accept this. In Qt 3.x, you must
set the mode, e.g. setMode(QFileDialog::AnyFile), to get the same
behavior.
<p><h2><ahref="qfont.html">QFont</a>
</h2>
<aname="10"></a><p> 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.
<p> 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
<aname="11"></a><p> The two static getText(...) methods in QInputDialog have been merged.
The <tt>echo</tt> parameter is the third parameter and defaults to
QLineEdit::Normal.
<p> If you used calls to <ahref="qinputdialog.html#getText">QInputDialog::getText</a>(...) that provided more
than the first two required parameters you will must add a value
for the <tt>echo</tt> parameter.
<p><h2><ahref="qlayout.html">QLayout</a> and Other Abstract Layout Classes
</h2>
<aname="12"></a><p> The definitions of <ahref="qglayoutiterator.html">QGLayoutIterator</a>, <ahref="qlayout.html">QLayout</a>, <ahref="qlayoutitem.html">QLayoutItem</a>, <ahref="qlayoutiterator.html">QLayoutIterator</a>, <ahref="qspaceritem.html">QSpacerItem</a> and <ahref="qwidgetitem.html">QWidgetItem</a> have been moved from <tt><qabstractlayout.h></tt> to <tt><qlayout.h></tt>. The header <tt><qabstractlayout.h></tt> now includes <tt><qlayout.h></tt> for compatibility. It
still compiles with Qt 3, but produces a different result (the case sensitivity
and wildcard options are forgotten). This way,
<pre>
rx = "beta";
</pre>
is the same as
<pre>
rx = QRegExp( "beta" );
</pre>
which is what one expects.
<p><h3> QRegExp::match()
</h3>
<aname="17-3"></a><p> The following function is now obsolete, as it has an unwieldy
parameter list and was poorly named:
<ul>
<li> bool <ahref="qregexp.html#match">QRegExp::match</a>( const <ahref="qstring.html">QString</a>& str, int index = 0,
int * len = 0, bool indexIsStart = TRUE ) const
</ul>
It will be removed in a future version of Qt. Its <ahref="qregexp.html#match">documentation</a> explains how to replace it.
<p><h3> QRegExp::find()
</h3>
<aname="17-4"></a><p> This function was removed, after a brief appearance in Qt 2.2. Its
name clashed with <ahref="qstring.html#find">QString::find</a>(). Use <ahref="qregexp.html#search">QRegExp::search</a>() or <ahref="qstring.html#find">QString::find</a>() instead.
<p><h3><ahref="qstring.html#findRev">QString::findRev</a>() and <ahref="qstring.html#contains">QString::contains</a>()
</h3>
<aname="17-5"></a><p><ahref="qstring.html#findRev">QString::findRev</a>()'s and <ahref="qstring.html#contains">QString::contains</a>()'s semantics have changed
between 2.0 and 3.0 to be more consistent with the other overloads.
<p> For example,
<pre>
QString( "" ).contains( QRegExp("") )
</pre>
returns 1 in Qt 2.0; it returns 0 in Qt 3.0. Also, "^" now really means
With Qt 3.0, the compiler gives an error. The solution is to use a
QRegExp cast:
<pre>
text.replace( QRegExp("[A-Z]+"), "" );
</pre>
This change makes it possible to introduce a
QString::replace(QString, QString) overload in a future version of Qt
without breaking source compatibility.
<p><h2> QSemiModal
</h2>
<aname="18"></a><p> The QSemiModal class is now obsolete. You should call show() on a
modal dialog instead.
<p><h2> QSortedList
</h2>
<aname="19"></a><p> The QSortedList class is now obsolete. Consider using a <ahref="qdict.html">QDict</a>, a <ahref="qmap.html">QMap</a>
or a plain <ahref="qptrlist.html">QPtrList</a> instead.
<p><h2> QTableView
</h2>
<aname="20"></a><p> The QTableView class has been obsoleted and is no longer a part of the
Qt API. Either use the powerful <ahref="qtable.html">QTable</a> class or the simplistic
<ahref="qgridview.html">QGridView</a> in any new code you create. If you really need the old table
view for compatibility you can find it in <tt>$QTDIR/src/attic/qttableview.{cpp,h}</tt>. 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.
<p><h2><ahref="qtoolbutton.html">QToolButton</a>
</h2>
<aname="21"></a><p> The <ahref="qtoolbutton.html">QToolButton</a> class used to distinguish between "on" and "off"
icons. In 3.0, this mechanism was moved into the <ahref="qiconset.html">QIconSet</a> class
(see <ahref="qiconset.html#State-enum">QIconSet::State</a>).
<p> The old <ahref="qtoolbutton.html#onIconSet-prop">QToolButton::onIconSet</a> and <ahref="qtoolbutton.html#offIconSet-prop">QToolButton::offIconSet</a>
properties are still provided so that old source will compile, but
their semantics have changed: they are now synonyms for <ahref="qtoolbutton.html#iconSet-prop">QToolButton::iconSet</a>. If you used that distinction in Qt 2.x, you will
need to adjust your code to use the <ahref="qiconset.html">QIconSet</a> On/Off mechanism.
<p> Likewise, the <em>on</em> parameter of these two functions is now ignored:
<p><ul>
<li> void QToolButton::setIconSet ( const QIconSet & set, bool on )
<li> QIconSet QToolButton::iconSet ( bool on ) const
</ul>
<p> These functions are only provided for ease of porting. New code
should use the following instead:
<p><ul>
<li> void <ahref="qtoolbutton.html#setIconSet">QToolButton::setIconSet</a>( const QIconSet & set )
<ahref="qwidget.html#backgroundPixmap">QWidget::backgroundPixmap</a>() and <ahref="qwidget.html#setBackgroundPixmap">QWidget::setBackgroundPixmap</a>() have
often been the source of much confusion in previous releases. Qt 3.0
addresses this by obsoleting these functions and by replacing them
with eight new functions: <ahref="qwidget.html#eraseColor">QWidget::eraseColor</a>(),
<aname="26"></a><p> QASyncIO, QDataSink, QDataSource, QIODeviceSource and QDataPump were
used internally in previous versions of Qt, but are not used anymore.
They are now obsolete.
<p><h2> Transparent widgets
</h2>
<aname="27"></a><p> 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 <ahref="qcheckbox.html">QCheckBox</a>, <ahref="qcombobox.html">QComboBox</a>, <ahref="qpushbutton.html">QPushButton</a>, <ahref="qradiobutton.html">QRadioButton</a> and <ahref="qtabwidget.html">QTabWidget</a>.
<p><h2> Bezier Curves
</h2>
<aname="28"></a><p> The function names for Bezier curves in <ahref="qpainter.html">QPainter</a> and <ahref="qpointarray.html">QPointArray</a> 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
<ul>
<li> void <ahref="qpainter.html#drawCubicBezier">QPainter::drawCubicBezier</a>( const QPointArray &, int index=0 ) and
respectively. Neither the arguments nor the resulting curve have changed.
<p><h2> Locale-aware String Comparisons in <ahref="qiconview.html">QIconView</a>, <ahref="qlistbox.html">QListBox</a>,
<ahref="qlistview.html">QListView</a> and <ahref="qtable.html">QTable</a>
</h2>
<aname="29"></a><p> In Qt 2.x, <ahref="qstring.html">QString</a> 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'.
<p> In Qt 3.0, <ahref="qstring.html#localeAwareCompare">QString::localeAwareCompare</a>() implements locale aware
string comparisions on certain platforms. The classes <ahref="qiconview.html">QIconView</a>, <ahref="qlistbox.html">QListBox</a>, <ahref="qlistview.html">QListView</a> and <ahref="qtable.html">QTable</a> now use
QString::localeAwareCompare() instead of <ahref="qstring.html#compare">QString::compare</a>(). If you
want to control the behaviour yourself you can always reimplement
