path: root/doc/porting3.doc

/****************************************************************************
**
** Help with porting from Qt 2.x to Qt 3.x
**
** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
**
** This file is part of the Qt GUI Toolkit.
**
** This file may be used under the terms of the GNU General
** Public License versions 2.0 or 3.0 as published by the Free
** Software Foundation and appearing in the files LICENSE.GPL2
** and LICENSE.GPL3 included in the packaging of this file.
** Alternatively you may (at your option) use any later version
** of the GNU General Public License if such license has been
** publicly approved by Trolltech ASA (or its successors, if any)
** and the KDE Free Qt Foundation.
**
** Please review the following information to ensure GNU General
** Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/.
** If you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** This file may be used under the terms of the Q Public License as
** defined by Trolltech ASA and appearing in the file LICENSE.QPL
** included in the packaging of this file.  Licensees holding valid Qt
** Commercial licenses may use this file in accordance with the Qt
** Commercial License Agreement provided with the Software.
**
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
** herein.
**
**********************************************************************/

/*!
\page porting.html

\title Porting to Qt 3.x

This document describes porting applications from Qt 2.x to 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 \e 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:

\list 1

\i Briefly read the porting notes below to get an idea of what to expect.
\i Be sure your code compiles and runs well on all your target platforms
   with Qt 2.x.
\i 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.
\i If you get stuck, ask on the \link http://qt-interest.trolltech.com/
   qt-interest \endlink mailing list, or Trolltech Technical Support if
   you're a registered licensee.

\endlist

Table of contents:

\tableofcontents

\target Linkerrors
\section1 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 \c 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:

\c CONFIG = ...

this should be changed to 

\c CONFIG += ...

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

\target Headers
\section1 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 \c {#include <qstringlist.h>} at
the top of the file giving the error.

Header files that you might need to add #include directives for include:
\list
\i \c <qcursor.h>
\i \c <qpainter.h>
\i \c <qpen.h>
\i \c <qstringlist.h>
\i \c <qregexp.h>
\i \c <qstrlist.h>
\i \c <qstyle.h>
\i \c <qvaluelist.h>
\endlist

\section1 Namespace

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

Enumeration \l Qt::CursorShape and its values are now part of the
special \c 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:

\list
\i \c QCursorShape becomes \c Qt::CursorShape
\i \c ArrowCursor becomes \c Qt::ArrowCursor
\i \c UpArrowCursor becomes \c Qt::UpArrowCursor
\i \c CrossCursor becomes \c Qt::CrossCursor
\i \c WaitCursor becomes \c Qt::WaitCursor
\i \c IbeamCursor becomes \c Qt::IbeamCursor
\i \c SizeVerCursor becomes \c Qt::SizeVerCursor
\i \c SizeHorCursor becomes \c Qt::SizeHorCursor
\i \c SizeBDiagCursor becomes \c Qt::SizeBDiagCursor
\i \c SizeFDiagCursor becomes \c Qt::SizeFDiagCursor
\i \c SizeAllCursor becomes \c Qt::SizeAllCursor
\i \c BlankCursor becomes \c Qt::BlankCursor
\i \c SplitVCursor becomes \c Qt::SplitVCursor
\i \c SplitHCursor becomes \c Qt::SplitHCursor
\i \c PointingHandCursor becomes \c Qt::PointingHandCursor
\i \c BitmapCursor becomes \c Qt::BitmapCursor
\endlist

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:

\list
\i \c DEBUG becomes \c QT_DEBUG
\i \c NO_DEBUG becomes \c QT_NO_DEBUG
\i \c NO_CHECK becomes \c QT_NO_CHECK
\i \c CHECK_STATE becomes \c QT_CHECK_STATE
\i \c CHECK_RANGE becomes \c QT_CHECK_RANGE
\i \c CHECK_NULL becomes \c QT_CHECK_NULL
\i \c CHECK_MATH becomes \c QT_CHECK_MATH
\endlist

The name of some debugging macro functions has been changed:

\list
\i \c ASSERT becomes \c Q_ASSERT
\i \c CHECK_PTR becomes \c Q_CHECK_PTR
\endlist

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

\list
\i \c _OS_*_ becomes \c Q_OS_*
\i \c _WS_*_ becomes \c Q_WS_*
\i \c _CC_*_ becomes \c Q_CC_*
\endlist

\section1 Removed Functions

All these functions have been removed in Qt 3.x:
\list
\i QFont::charSet()
\i QFont::setCharSet()
\i QMenuBar::setActItem()
\i QMenuBar::setWindowsAltMode()
\i QObject::initMetaObject()
\i QPainter::drawQuadBezier()
\i QPointArray::quadBezier()
\i QRegExp::find()
\i QSpinBox::downButton()
\i QSpinBox::upButton()
\i QString::basicDirection()
\i QString::visual()
\i QStyle::set...() functions
\i QStyle::drawArrow()
\i QWidget::setFontPropagation()
\i QWidget::setPalettePropagation()
\endlist

Also, to avoid conflicts with \c <iostream>, the following three
global functions have been renamed:
\list
\i setw() (renamed qSetW())
\i setfill() (renamed qSetFill())
\i setprecision() (renamed qSetPrecision())
\endlist

\section1 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 \l 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.

\list
\i QAccel::keyToString( QKeySequence k )
\i QAccel::stringToKey( const QString \& s )
\i QActionGroup::insert( QAction *a )
\i QButton::autoResize() const
\i QButton::setAutoResize( bool )
\i QCanvasItem::active() const
\i QCanvasItem::enabled() const
\i QCanvasItem::selected() const
\i QCanvasItem::visible() const
\i QCanvasPixmapArray::QCanvasPixmapArray( QPtrList\<QPixmap\> list, QPtrList\<QPoint\> hotspots )
\i QCanvasPixmapArray::operator!()
\i QColorGroup::QColorGroup( const QColor \& foreground, const QColor \& background, const QColor \& light, const QColor \& dark, const QColor \& mid, const QColor \& text, const QColor \& base )
\i QComboBox::autoResize() const
\i QComboBox::setAutoResize( bool )
\i QDate::dayName( int weekday )
\i QDate::monthName( int month )
\i QDir::encodedEntryList( const QString \& nameFilter, int filterSpec = DefaultFilter, int sortSpec = DefaultSort ) const
\i QDir::encodedEntryList( int filterSpec = DefaultFilter, int sortSpec = DefaultSort ) const
\i QDockWindow::isHorizontalStretchable() const
\i QDockWindow::isVerticalStretchable() const
\i QDockWindow::setHorizontalStretchable( bool b )
\i QDockWindow::setVerticalStretchable( bool b )
\i QFont::defaultFont()
\i QFont::setDefaultFont( const QFont \& f )
\i QFont::setPixelSizeFloat( float pixelSize )
\i QFontDatabase::bold( const QString \& family, const QString \& style, const QString \& ) const
\i QFontDatabase::families( bool ) const
\i QFontDatabase::font( const QString \& familyName, const QString \& style, int pointSize, const QString \& )
\i QFontDatabase::isBitmapScalable( const QString \& family, const QString \& style, const QString \& ) const
\i QFontDatabase::isFixedPitch( const QString \& family, const QString \& style, const QString \& ) const
\i QFontDatabase::isScalable( const QString \& family, const QString \& style, const QString \& ) const
\i QFontDatabase::isSmoothlyScalable( const QString \& family, const QString \& style, const QString \& ) const
\i QFontDatabase::italic( const QString \& family, const QString \& style, const QString \& ) const
\i QFontDatabase::pointSizes( const QString \& family, const QString \& style, const QString \& )
\i QFontDatabase::smoothSizes( const QString \& family, const QString \& style, const QString \& )
\i QFontDatabase::styles( const QString \& family, const QString \& ) const
\i QFontDatabase::weight( const QString \& family, const QString \& style, const QString \& ) const
\i QLabel::autoResize() const
\i QLabel::setAutoResize( bool enable )
\i QLineEdit::cursorLeft( bool mark, int steps = 1 )
\i QLineEdit::cursorRight( bool mark, int steps = 1 )
\i QLineEdit::hasMarkedText() const
\i QLineEdit::markedText() const
\i QLineEdit::repaintArea( int, int )
\i QListBox::cellHeight( int i ) const
\i QListBox::cellHeight() const
\i QListBox::cellWidth() const
\i QListBox::findItem( int yPos ) const
\i QListBox::inSort( const QListBoxItem *lbi )
\i QListBox::inSort( const QString \& text )
\i QListBox::itemYPos( int index, int *yPos ) const
\i QListBox::numCols() const
\i QListBox::totalHeight() const
\i QListBox::totalWidth() const
\i QListBoxItem::current() const
\i QListBoxItem::selected() const
\i QListView::removeItem( QListViewItem *item )
\i QListViewItem::removeItem( QListViewItem *item )
\i QMainWindow::addToolBar( QDockWindow *, Dock = DockTop, bool newLine = FALSE )
\i QMainWindow::addToolBar( QDockWindow *, const QString \& label, Dock = DockTop, bool newLine = FALSE )
\i QMainWindow::lineUpToolBars( bool keepNewLines = FALSE )
\i QMainWindow::moveToolBar( QDockWindow *, Dock = DockTop )
\i QMainWindow::moveToolBar( QDockWindow *, Dock, bool nl, int index, int extraOffset = -1 )
\i QMainWindow::removeToolBar( QDockWindow *)
\i QMainWindow::setToolBarsMovable( bool )
\i QMainWindow::toolBarPositionChanged( QToolBar *)
\i QMainWindow::toolBarsMovable() const
\i QMessageBox::message( const QString \& caption, const QString \& text, const QString \& buttonText = QString::null, QWidget *parent = 0, const char *= 0 )
\i QMessageBox::query( const QString \& caption, const QString \& text, const QString \& yesButtonText = QString::null, const QString \& noButtonText = QString::null, QWidget *parent = 0, const char *= 0 )
\i QMessageBox::standardIcon( Icon icon, GUIStyle style )
\i QPalette::normal()
\i QRegExp::match( const QString \& str, int index = 0, int *len = 0, bool indexIsStart = TRUE ) const
\i QScrollView::childIsVisible( QWidget *child )
\i QScrollView::showChild( QWidget *child, bool show = TRUE )
\i QSignal::block( bool b )
\i QSignal::isBlocked() const
\i QSignal::parameter() const
\i QSignal::setParameter( int value )
\i QSimpleRichText::draw( QPainter *p, int x, int y, const QRegion \& clipRegion, const QColorGroup \& cg, const QBrush *paper = 0 ) const
\i QString::ascii() const
\i QString::data() const
\i QString::setExpand( uint index, QChar c )
\i QStyle::defaultFrameWidth() const
\i QStyle::scrollBarExtent() const
\i QStyle::tabbarMetrics( const QWidget *t, int \& hf, int \& vf, int \& ov ) const
\i QTabDialog::isTabEnabled( const char *name ) const
\i QTabDialog::selected( const QString \& )
\i QTabDialog::selected( const QString \& tabLabel )
\i QTabDialog::setTabEnabled( const char *name, bool enable )
\i QTextStream::QTextStream( QString \& str, int filemode )
\i QToolBar::QToolBar( const QString \& label, QMainWindow *, ToolBarDock = DockTop, bool newLine = FALSE, const char *name = 0 )
\i QToolButton::iconSet( bool on ) const
\i QToolButton::offIconSet() const
\i QToolButton::onIconSet() const
\i QToolButton::setIconSet( const QIconSet \& set, bool on )
\i QToolButton::setOffIconSet( const QIconSet \& )
\i QToolButton::setOnIconSet( const QIconSet \& )
\i QToolTip::enabled()
\i QToolTip::setEnabled( bool enable )
\i QTranslator::find( const char *context, const char *sourceText, const char *comment = 0 ) const
\i QTranslator::insert( const char *context, const char *sourceText, const QString \& translation )
\i QTranslator::remove( const char *context, const char *sourceText )
\i QUriDrag::setFilenames( const QStringList \& fnames )
\i QWidget::backgroundColor() const
\i QWidget::backgroundPixmap() const
\i QWidget::iconify()
\i QWidget::setBackgroundColor( const QColor \& c )
\i QWidget::setBackgroundPixmap( const QPixmap \& pm )
\i QWidget::setFont( const QFont \& f, bool )
\i QWidget::setPalette( const QPalette \& p, bool )
\i QWizard::setFinish( QWidget *, bool )
\i QXmlInputSource::QXmlInputSource( QFile \& file )
\i QXmlInputSource::QXmlInputSource( QTextStream \& stream )
\i QXmlReader::parse( const QXmlInputSource \& input )
\endlist

Additionally, these preprocessor directives have been removed:

\list
\i \c {#define strlen qstrlen}
\i \c {#define strcpy qstrcpy}
\i \c {#define strcmp qstrcmp}
\i \c {#define strncmp qstrncmp}
\i \c {#define stricmp qstricmp}
\i \c {#define strnicmp qstrnicmp}
\endlist

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.

\section1 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.

\table
\header \i Old Name \i New Name \i New Header File
\row \i QArray \i \l QMemArray \i \c <qmemarray.h>
\row \i QCollection \i \l QPtrCollection \i \c <qptrcollection.h>
\row \i QList \i \l QPtrList \i \c <qptrlist.h>
\row \i QListIterator \i \l QPtrListIterator \i \c <qptrlist.h>
\row \i QQueue \i \l QPtrQueue \i \c <qptrqueue.h>
\row \i QStack \i \l QPtrStack \i \c <qptrstack.h>
\row \i QVector \i \l QPtrVector \i \c <qptrvector.h>
\endtable

\section1 QButtonGroup

In Qt 2.x, the function QButtonGroup::selected() returns the selected
\e radio button (QRadioButton). In Qt 3.0, it returns the selected \e
toggle button (\l 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.

\section1 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:

\list
\i QString QDate::monthName( int month ) const
\i QString QDate::dayName( int weekday ) const
\endlist

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.

\section1 QFileDialog

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.

\section1 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.

\section1 QInputDialog

The two static getText(...) methods in QInputDialog have been merged. 
The \c 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 \c echo parameter.

\section1 QLayout and Other Abstract Layout Classes

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

\section1 QListViewItem

The paintBranches() function in Qt 2.x had a GUIStyle parameter; this
has been dropped for Qt 3.x since GUI style is handled by the new
style engine (See \l QStyle.)

\section1 QMoveEvent

In Qt 2.x, the function QMoveEvent::pos() returned the position of the
widget in its parent widget, including the window frame. In Qt 3.0,
it returns the new position of the widget, excluding window frame for
top level widgets.

\section1 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 \c $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.

\section1 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.

\section1 QRegExp

The \l 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 \c <qregexp.h> is no longer included
automatically when you include \c <qstringlist.h>. See
\link #Headers above \endlink for details.

\omit
In Qt 3.0, qregexp.h has to
include qstringlist.h, so it's no good to have qstringlist.h include qregexp.h,
unless one wants to achieve an Escher effect.
\endomit

\section2 New special characters

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

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

Wildcard patterns need no conversion.  Here are two examples:
\code
    QRegExp wild( "(*.*)" );
    wild.setWildcard( TRUE );
\endcode
\code
    // TRUE as third argument means wildcard
    QRegExp wild( "(*.*)", FALSE, TRUE );
\endcode
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.

\section2 QRegExp::operator=()

This function has been replaced by \l QRegExp::setPattern() in Qt 2.2.
Old code such as
\code
    QRegExp rx( "alpha" );
    rx.setCaseSensitive( FALSE );
    rx.setWildcard( TRUE );
    rx = "beta";
\endcode
still compiles with Qt 3, but produces a different result (the case sensitivity
and wildcard options are forgotten). This way,
\code
    rx = "beta";
\endcode
is the same as
\code
    rx = QRegExp( "beta" );
\endcode
which is what one expects.

\section2 QRegExp::match()

The following function is now obsolete, as it has an unwieldy
parameter list and was poorly named:
\list
\i bool QRegExp::match( const QString \& str, int index = 0,
			int * len = 0, bool indexIsStart = TRUE ) const
\endlist
It will be removed in a future version of Qt. Its \link
QRegExp::match() documentation \endlink explains how to replace it.

\section2 QRegExp::find()

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

\section2 QString::findRev() and QString::contains()

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

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

This change affect very few existing programs.

\section2 QString::replace()

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

\section1 QSemiModal 

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

\section1 QSortedList

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

\section1 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 \c
$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.

\section1 QToolButton

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

The old \l QToolButton::onIconSet and \l QToolButton::offIconSet
properties are still provided so that old source will compile, but
their semantics have changed: they are now synonyms for \l
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 \e on parameter of these two functions is now ignored:

\list
\i void QToolButton::setIconSet ( const QIconSet \& set, bool on )
\i QIconSet QToolButton::iconSet ( bool on ) const
\endlist

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

\list
\i void QToolButton::setIconSet( const QIconSet \& set )
\i QIconSet QToolButton::iconSet() const
\endlist

Finally, this function is no longer virtual:

\list
\i void QToolButton::setIconSet( const QIconSet \& set, bool on )
\endlist

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 \l QToolButton::setIconSet(),
a virtual function.

\section1 QTextStream

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

\section1 QTranslator

The \l 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, \link linguist-manual.book Qt
Linguist \endlink).  For source compatibility, no member function was
effectively removed.  The \l QTranslator documentation points out
which functions are obsolete.

This function is no longer virtual:

\list
\i QString QTranslator::find( const char * context,
			      const char * sourceText ) const
\endlist

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.

\section1 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 replacing 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.

\section1 QXml Classes

\section2 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
\code
    QXmlInputSource source( &xmlFile );
    QXmlSimpleReader reader;
    ...
    reader.parse( source );
    ...
    reader.parse( source );
\endcode
must be changed to
\code
    QXmlInputSource source( &xmlFile );
    QXmlSimpleReader reader;
    ...
    reader.parse( source );
    ...
    source.reset();
    reader.parse( source );
\endcode

\section2 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.

\section1 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.

\section1 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.

\section1 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
\list
\i void QPainter::drawCubicBezier( const QPointArray \&, int index=0 ) and
\i QPointArray QPointArray::cubicBezier() const
\endlist
respectively. Neither the arguments nor the resulting curve have changed.

\section1 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 '&eacute;' (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 \l QIconView, \l
QListBox, \l QListView and \l 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.

*/