diff options
Diffstat (limited to 'doc/porting3.doc')
| -rw-r--r-- | doc/porting3.doc | 816 |
1 files changed, 816 insertions, 0 deletions
diff --git a/doc/porting3.doc b/doc/porting3.doc new file mode 100644 index 000000000..bd67bd2f2 --- /dev/null +++ b/doc/porting3.doc @@ -0,0 +1,816 @@ +/**************************************************************************** +** +** 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 retquirements 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 [email protected]. +** +** 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 as well +but source compatibility should not be affected if the macro variable +\c QT_CLEAN_NAMESPACE is not defined: + +\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 retquired 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 +retquire 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>\</tt> (backslash) in front of any +of these (actually, <tt>\\</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 'é' (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. + +*/ |