<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/porting2.doc:36 -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Porting to Qt 2.x</title>
<style type="text/css"><!--
fn { margin-left: 1cm; text-indent: -1cm; }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
body { background: #ffffff; color: black; }
--></style>
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr bgcolor="#E5E5E5">
<td valign=center>
<a href="index.html">
<font color="#004faf">Home</font></a>
| <a href="classes.html">
<font color="#004faf">All Classes</font></a>
| <a href="mainclasses.html">
<font color="#004faf">Main Classes</font></a>
| <a href="annotated.html">
<font color="#004faf">Annotated</font></a>
| <a href="groups.html">
<font color="#004faf">Grouped Classes</font></a>
| <a href="functions.html">
<font color="#004faf">Functions</font></a>
</td>
<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>Porting to Qt 2.x</h1>
<p> <p>
You're probably looking at this page because you want to port
your application from Qt 1.x to Qt 2.x, but to be sure, let's
review the good reasons to do this:
<ul>
<li>To get access to all the new Qt 2.x features like the rich text
HTML subset for formatted labels, tooltips, online help etc.
and the much easier to use layout classes and widgets.
<li>To make your application truly international, with support
for Unicode and translations for the languages of the world.
<li>To allow your application to fit into the new look of the
Unix desktop with configurable, very powerful "themes". The
extended style system also integrates Qt applications better
on MS-Windows desktops. Qt will automatically chose the right
colors and fonts and obey global system setting changes.
<li>To stay up-to-date with the version of Qt that gets all the
new features and bug-fixes.
<li>To get more speed and smoother widgets display with all the
new anti-flicker changes in Qt.
<li>Most of all though, you want to port to Qt 2.x
so that your Wheel Mouse works!
</ul>
<p> <p>
The Qt 2.x series is not binary compatible with the 1.x series.
This means programs compiled for Qt 1.x must be recompiled to work
with Qt 2.x. Qt 2.x is also not completely <em>source</em> compatible
with 1.x, however all points of incompatibility cause
compiler errors (rather than mysterious results), or produce run-time
messages. The result is that Qt 2.x includes many additional features,
discards obsolete functionality that is easily converted to use the new
features, and that porting an application from Qt 1.x to Qt 2.x is
a simple task well worth the amount of effort required.
<p> To port code using Qt 1.x to use Qt 2.x:
<p> <ul>
<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 1.x.
<li> Recompile with Qt 2.x. For each error, search below for related
identifiers (eg. function names, class names) - this documented is
structured to mention all relevant identifiers to facilitate such
searching, even if that makes it a little verbose.
<li> If you get stuck, ask on the qt-interest mailing list, or
Trolltech Technical Support if you're a Professional Edition
licensee.
</ul>
<p> Many very major projects, such as <a href="http://www.kde.org/">KDE</a>
have been port, so there is plenty of expertise in the collective conscious
that is the Qt Developer Community!
</p>
<p> <hr>
<p> <h2 align=center>The Porting Notes</h2>
<p> <ul>
<li><b><a href="#Namespace">Namespace</a></b>
<li><b><a href="#Virtual">Virtual Functions</a></b>
<li><b><a href="#Collection">Collection classes</a></b>
<li><b><a href="#DefaultParent">No Default 0 Parent Widget</a></b>
<li><b><a href="#DebugVsRelease">Debug vs. Release</a></b>
<li><b><a href="#QApplication">QApplication</a></b>
<li><b><a href="#QClipboard">QClipboard</a></b>
<li><b><a href="#QColor">QColor</a></b>
<li><b><a href="#QDataStream">QDataStream</a></b>
<li><b><a href="#QDialog">QDialog</a></b>
<li><b><a href="#QDropSite">QDropSite</a></b>
<li><b><a href="#QEvent">QEvent</a></b>
<li><b><a href="#QFile">QFile</a></b>
<li><b><a href="#QFontMetrics">QFontMetrics</a></b>
<li><b><a href="#QIODevice">QIODevice</a></b>
<li><b><a href="#QLabel">QLabel</a></b>
<li><b><a href="#QLayout">QLayout</a></b>
<li><b><a href="#QListView">QListView</a></b>
<li><b><a href="#QMenuData">QMenuData</a></b>
<li><b><a href="#QMenuData">QPopupMenu</a></b>
<li><b><a href="#QMultiLineEdit">QMultiLineEdit</a></b>
<li><b><a href="#QPainter">QPainter</a></b>
<li><b><a href="#QPicture">QPicture</a></b>
<li><b><a href="#QPoint">QPoint, <a href="qpointarray.html">QPointArray</a>, <a href="qsize.html">QSize</a> and <a href="qrect.html">QRect</a></a></b>
<li><b><a href="#QPixmap">QPixmap</a></b>
<li><b><a href="#QRgb">QRgb</a></b>
<li><b><a href="#QScrollView">QScrollView</a></b>
<li><b><a href="#QStrList">QStrList</a></b>
<li><b><a href="#QString">QString</a></b>
<li><b><a href="#QTextStream">QTextStream</a></b>
<li><b><a href="#QUriDrag">QUriDrag / QUrlDrag</a></b>
<li><b><a href="#QValidator">QComboBox</a></b>
<li><b><a href="#QValidator">QLineEdit</a></b>
<li><b><a href="#QValidator">QSpinBox</a></b>
<li><b><a href="#QValidator">QValidator</a></b>
<li><b><a href="#QWidget">QWidget</a></b>
<li><b><a href="#QWindow">QWindow</a></b>
</ul>
<p> <hr>
<p> <h3><a name="Namespace">Namespace</a></h3>
<p> <p> Qt 2.x is namespace-clean, unlike 1.x. Qt now uses very few
global identifiers. Identifiers like <code>red, blue, LeftButton,
AlignRight, Key_Up, Key_Down, NoBrush</code> etc. are now part of a
special class <code>Qt</code> (defined in qnamespace.h),
which is inherited by
most Qt classes. Member functions of classes that inherit from <a href="qwidget.html">QWidget</a>,
etc. are totally unaffected, but code that is
<em>not</em> in functions of classes inherited from <code>Qt</code>,
you must qualify these identifiers like this: <code>Qt::red,
Qt::LeftButton, Qt::AlignRight</code>, etc.
<p> <p>The <code>qt/bin/qt20fix</code> script helps to fix the code that
needs adaption, though most code does not need changing.
<p> Compiling with -DQT1COMPATIBILITY will help you get going with Qt 2.x
- it allows all the old "dirty namespace" identifiers from Qt 1.x to
continue working. Without it, you'll get compile errors that can
easily be fixed by searching this page for the clean identifiers.
<p> <h3><a name="DefaultParent">No Default 0 Parent Widget</a></h3>
<p> In Qt 1.x, all widget constructors were defined with a default value
of 0 for the parent widget. However, only the main window of the
application should be created with a 0 parent, all other widgets
should have parents. Having the 0 default made it too simple to create
bugs by forgetting to specify the parent of non-mainwindow
widgets. Such widgets would typically never be deleted (causing memory
leaks), and they would become top-level widgets, confusing the window
managers. Therefore, in Qt 2.x the 0 default parent has been removed
for the widget classes that are not likely to be used as main windows.
<p> Note also that programs no longer need (or should) use 0 parent just
to indicate that a widget should be top-level. See
<pre> QWidget::isTopLevel() </pre>
for details. See also the notes about
<a href="#QMenuData">QPopupMenu</a> and <a href="#QDialog">QDialog</a>
below.
<p> <h3><a name="Virtual">Virtual Functions</a></h3>
<p> <p> Some virtual functions have changed signature in Qt 2.x.
If you override them in derived classes, you must change the signature
of your functions accordingly.
<p> <!-- warwick can check for additions to this with his qt-2-report -->
<ul>
<li><pre> QWidget::setStyle(GUIStyle)</pre>
<li><pre> QListView::addColumn(const char *, int)</pre>
<li><pre> QListView::setColumnText(int, const char *)</pre>
<li><pre> QListViewItem::setText(int, const char *)</pre>
<li><pre> QMultiLineEdit::insertLine(const char *, int)</pre>
<li><pre> QMultiLineEdit::insertAt(const char *, int, int, bool)</pre>
<li><pre> QSpinBox::setPrefix(const char *)</pre>
<li><pre> QSpinBox::setSuffix(const char *)</pre>
<li><pre> QToolButton::setTextLabel(const char *, bool)</pre>
<li><pre> QDoubleValidator::validate(QString &, int &)</pre>
<li><pre> QIntValidator::validate(QString &, int &)</pre>
<li><pre> QValidator::fixup(QString &)</pre>
<li><pre> QSlider::paintSlider(QPainter *, const <a href="qrect.html">QRect</a> &)</pre>
</ul>
<p> This is one class of changes that are
not detected by the compiler,
so you should mechanically search for each of
these function names in your header files, eg.
<p> <pre>
egrep -w 'setStyle|addColumn|setColumnText|setText...' *.h
</pre>
<p> Of course, you'll get a few false positives (eg. if you have a setText
function that is not in a subclass of <a href="qlistviewitem.html">QListViewItem</a>).
<p> <h3><a name="Collection">Collection classes</a></h3>
<p> <p> The <a href="collection.html#collection-classes">collection classes</a> include generic
classes such as QGDict, QGList, and
the subclasses such as <a href="qdict.html">QDict</a> and QList.
<p> <p> The macro-based Qt collection classes are obsolete; use the
template-based classes instead. Simply remove includes of qgeneric.h and
replace e.g. Q_DECLARE(<a href="qcache.html">QCache</a>,QPixmap) with QCache<QPixmap>.
<p> <p> The GCI global typedef is replaced by QCollection::Item. Only if you
make your own subclasses of the undocumented generic collection classes
will you have GCI in your code.
This change has been made to avoid collisions with other namespaces.
<p> <p> The GCF global typedef is removed (it was not used in Qt).
<p> <h3><a name="DebugVsRelease">Debug vs. Release</a></h3>
<p> <p>The Q_ASSERT macro is now a null expression if the QT_CHECK_STATE flag
is not set (i.e. if the QT_NO_CHECK flag is defined).
<p> <p>The debug() function now outputs nothing if Qt was compiled with
the QT_NO_DEBUG macro defined.
<p> <h3><a name="QString">QString</a></h3>
<p> <a href="qstring.html">QString</a> has undergone major changes internally, and although it is highly
backward compatible, it is worth studying in detail when porting to Qt 2.x.
The Qt 1.x QString class has been renamed to <a href="qcstring.html">QCString</a> in Qt 2.x, though if
you use that you will incur a performance penalty since all Qt functions
that took const char* now take const QString&.
<p> <p>
To take full advantage of the new <a href="i18n.html#internationalization">Internationalization</a>
functionality in Qt 2.x, the following steps are required:
<p> <ul>
<li> Start converting all uses of "const char*" in parameters to
"const QString&" - this can often be done mechanically, eg.
using Perl. Convert usage of char[] for temporary string
building to QString (much software already uses QString for
this purpose as it offers many more facilities).
<p> If you find that you are mixing usage of QCString, QString,
and <a href="qbytearray.html">QByteArray</a>, this causes lots of unnecessary copying and
might indicate that the true nature of the data you are
dealing with is uncertain. If the data is NUL-terminated
8-bit data, use QCString; if it is unterminated (ie.
contains NULs) 8-bit data, use QByteArray; if it is text,
use <a href="qstring.html">QString</a>.
</p>
<li> Put a breakpoint in <pre> QString::latin1()</pre>
to catch places where
Unicode information is being converted to ASCII (loosing
information if your user in not using Latin1). Qt has
a small number of calls to this - ignore those. As a stricter
alternative, compile your code with QT_NO_ASCII_CAST defined,
which hides the automatic conversion of QString to const char*,
so you can catch problems at compile time.
</p>
<li> See the Qt <a href="i18n.html">Internationalization page</a>
for information about the full process of internationalizing
your software.
</ul>
<p> <p>
Points to note about the new QString are:
<p> <dl compact>
<dt><b>Unicode</b></dt>
<dd>
Qt now uses Unicode throughout.
data() now returns a <em>const</em> reference to an ASCII version
of the string - you cannot directly access the
string as an array of bytes, because it isn't one. Often, latin1() is
what you want rather than data(), or just leave it to convert to
const char* automatically. data() is only used now to aide porting to Qt 2.x,
and ideally you'll only need latin1() or implicit conversion when interfacing
to facilities that do not have Unicode support.
<p> <dt><b>Automatic-expanding</b></dt>
<dd>
A big advantage of the new <a href="qstring.html">QString</a> is that it automatically expands
when you write to an indexed position.
<p> <dt><b>QChar and <a href="qcharref.html">QCharRef</a></b></dt>
<dd>
<a href="qchar.html">QChar</a> are the Unicode characters that make up a QString. A QCharRef is
a temporary reference to a QChar in a QString that when assigned to
ensures that the <a href="shclass.html#implicit-sharing">implicit sharing</a> semantics of the QString are maintained.
You are unlikely to use QCharRef in your own code - but so that you
understand compiler error messages, just know that <tt>mystring[123]</tt>
is a QCharRef whenever <tt>mystring</tt> is not a constant string. A QCharRef
has basically the same functionality as a QChar, except it is more restricted
in what you can assign to it and cast it to (to avoid programming errors).
<p> <dt><b>Use QString</b></dt>
<dd>
Try to always use QString. If you <em>must</em>, use <a href="qcstring.html">QCString</a> which is the
old implementation from Qt 1.x.
<p> <dt><b>Unicode vs. ASCII</b></dt>
<dd>
Every conversion to and from ASCII is wasted time, so try to use <a href="qstring.html">QString</a>
as much as possible rather than const char*. This also ensures you have
full 16-bit support.
<p> <dt><b>Convertion to ASCII</b></dt>
<dd>
The return value from operator const char*() is transient - don't expect
it to remain valid while you make deep function calls.
It is valid for as long as you don't modify or destroy the QString.
<p> <dt><b>QString is simpler</b></dt>
<dd>
Expect your code to become simpler with the new QString, especially
places where you have used a char* to wander over the string rather
than using indexes into the string.
<p> <dt><b>Some hacks don't work</b></dt>
<dd>
This hack:
use_sub_string( &my_string[index] )
should be replaced by:
use_sub_string( my_string.mid(index) )
<p> <dt><b>QString(const char*, int) is removed</b></dt>
<dd>
The QString constructor taking a const char* and an integer is removed.
Use of this constructor was error-prone, since the length included the
'\0' terminator. Use <a href="qstring.html#left">QString::left</a>(int) or <a href="qstring.html#fromLatin1">QString::fromLatin1</a>( const char*,
int ) -- in both cases the int parameter signifies the number of characters.
<p> <dt><b>QString(int) is private</b></dt>
<dd>
The <a href="qstring.html">QString</a> constructor taking an integer is now private. This function
is not meaningful anymore, since QString does all space allocation
automatically. 99% of cases can simple be changed to use the
default constructor, QString().
<p>
In Qt 1.x the constructor was used in two ways: accidentally,
by attempting to convert a char to a QString (the char converts to int!) -
giving strange bugs, and as a way to make a QString big enough prior to
calling <pre> QString::sprintf()</pre>
. In Qt 2.x, the accidental bug case is
prevented (you will get a compilation error) and QString::sprintf has
been made safe - you no longer need to pre-allocate space (though for
other reasons, sprintf is still a poor choice - eg. it doesn't pass Unicode).
The only remaining common case is conversion of 0 (NULL) to QString, which
would usually give expected results in Qt 1.x. For Qt 2.x the correct
syntax is to use <a href="qstring.html#QString-null">QString::null</a>, though note that
the default constructor, QString(), creates a null string too.
Assignment of 0 to a <a href="qstring.html">QString</a> is ambiguous - assign
QString::null; you'll mainly find these in code that has been converted
from const char* types to QString.
This also prevents a common error case from Qt 1.x - in
that version, mystr = 'X' would <em>not</em> produce the expected
results and was always a programming error; in Qt 2.x, it works - making
a single-character string.
<p> <p>
Also see <a href="#QStrList">QStrList</a>.
<p> <dt><b>Signals and Slots</b></dt>
<dd>
Many signal/slots have changed from const char* to QString. You will
get run-time errors when you try to <pre> QObject::connect()</pre>
to the old
signals and slots, usually with a message indicating the const QString&
replacement signal/slot.
<p> <dt><b>Optimize with Q2HELPER</b></dt>
<dd>
In qt/src/tools/qstring.cpp there is a Q2HELPER - define it for some
extra debugging/optimizing features (don't leave it it - it kills performance).
You'll get an extra function, qt_qstring_stats(), which will print a
summary of how much your application is doing Unicode and ASCII
back-and-forth conversions.
<p> <dt><b>QString::detach() is obsolete and removed</b></dt>
<dd>
Since <a href="qstring.html">QString</a> is now always shared, this function does nothing.
Remove calls to QString::detach().
<p> <dt><b>QString::resize(int size) is obsolete and removed</b></dt>
<dd>
Code using this to truncate a string should use
<a href="qstring.html#truncate">truncate(size-1)</a>.
Code using qstr.resize(0) should use qstr = QString::null.
Code calling resize(n) prior to using
<a href="qstring.html#operator[]">operator[]</a> up to n just remove
the resize(n) completely.
<p> <dt><b>QString::size() is obsolete and removed</b></dt>
<dd>
Calls to this function must be replaced by
<a href="qstring.html#length">length()</a>+1.
<p> <dt><b>QString::setStr(const char*) is removed</b></dt>
<dd>Try to understand why you were using this.
If you just meant assignment, use that. Otherwise,
you are probably using QString as an array of bytes, in which case use
<a href="qbytearray.html">QByteArray</a> or <a href="qcstring.html">QCString</a> instead.
<p> <dt><b>QString is not an array of bytes</b></dt>
<dd>
Code that uses <a href="qstring.html">QString</a> as an array of bytes should use QByteArray
or a char[], <em>then</em> convert that to a QString if needed.
<p> <dt><b>"string = 0"</b></dt>
<dd>
Assigning 0 to a QString should be assigning the null string,
ie. string = QString::null.
<p> <dt><b>System functions</b></dt>
<dd>
You may find yourself needing latin1() for passing to the operating system
or other libraries, and be tempted to use QCString to save the conversion,
but you are better off using Unicode throughout, then when the operating
system supports Unicode, you'll be prepared. Some Unix operating systems
are now beginning to have basic Unicode support, and Qt will be tracking
these improvements as they become more widespread.
<p> <dt><b>Bugs removed</b></dt>
<dd>
toShort() returns 0 (and sets *ok to false) on error.
toUInt() now works for big valid unsigned integers.
insert() now works into the same string.
<p> <dt><b>NULL pointers</b></dt>
<dd>
When converting "const char*" usage to QString in order to make your
application fully Unicode-aware, use QString::null for the null value
where you would have used 0 with char pointers.
<p> <dt><b>QString is not null terminated</b></dt>
<dd>
This means that inserting a 0-character
in the middle of the string does <em>not</em> change the length(). ie.
<pre>
<a href="qstring.html">QString</a> s = "fred";
s[1] = '\0';
// s.<a href="qstring.html#length">length</a>() == 4
// s == "f\0ed"
// s.<a href="qstring.html#latin1">latin1</a>() == "f"
s[1] = 'r';
// s == "fred"
// s.<a href="qstring.html#latin1">latin1</a>() == "fred"
</pre>
Especially look out for this type of code:
<pre>
<a href="qstring.html">QString</a> s(2);
s[0] = '?';
s[1] = 0;
</pre>
This creates a string 2 characters long.
To find these problems while converting, you might like to
add <a href="qapplication.html#Q_ASSERT">Q_ASSERT</a>(strlen(d->ascii)==d->len) inside
<pre> QString::latin1()</pre>
.
<p> <dt><b>QString or Standard C++ string?</b></dt>
<dd>
<p>
The Standard C++ Library string is not Unicode. Nor is wstring defined
to be so (for the small number of platforms where it is defined at all).
This is the same mistake made over and over
in the history of C - only when non-8-bit characters are <em>the norm</em>
do programmers find them usable. Though it is possible to convert between
string and <a href="qstring.html">QString</a>, it is less efficient than using QString throughout.
For example, when using:
<pre>
QLabel::<a href="qlabel.html#setText">setText</a>( const <a href="qstring.html">QString</a>& )
</pre>
if you use string, like this:
<pre>
void myclass::dostuffwithtext( const string& str )
{
mylabel.setText( QString(str.c_str()) );
}
</pre>
that will create a (ASCII only) copy of str, stored in mylabel.
But this:
<pre>
void myclass::dostuffwithtext( const <a href="qstring.html">QString</a>& str )
{
mylabel.setText( str );
}
</pre>
will make an <a href="shclass.html#implicitly-shared">implicitly shared</a> reference to str in the <a href="qlabel.html">QLabel</a> - no copying
at all. This function might be 10 nested function calls away from something
like this:
<pre>
void toplevelclass::initializationstuff()
{
doStuff( tr("Okay") );
}
</pre>
At this point, in Qt 2.x, the tr() does a very fast dictionary lookup
through memory-mapped message files, returning some Unicode <a href="qstring.html">QString</a> for
the appropriate language (the default being to just make a QString out
of the text, of course - you're not <em>forced</em> to use any of these
features), and that <em>same</em> memory mapped Unicode will be passed
though the system. All occurrences of the translation of "Okay" can
potentially be shared.
<p> </dl>
<p> <h3><a name="QApplication">QApplication</a></h3>
<p> In the function <pre> QApplication::setColorSpec()</pre>
,
PrivateColor and TrueColor are obsolete. Use ManyColor instead.
<p> <h3><a name="QColor">QColor</a></h3>
<p> <p>
All colors
(color0,
color1,
black,
white,
darkGray,
gray,
lightGray,
red,
green,
blue,
cyan,
magenta,
yellow,
darkRed,
darkGreen,
darkBlue,
darkCyan,
darkMagenta,
and
darkYellow)
are in the Qt namespace.
In members of classes that inherit the Qt namespace-class (eg. <a href="qwidget.html">QWidget</a>
subclasses), you can use the unqualified names as before, but in global
functions (eg. main()), you need to qualify them: Qt::red, Qt::white, etc.
See also the <a href="#QRgb">QRgb</a> section below.
<p> <h3><a name="QRgb">QRgb</a></h3>
<p> In QRgb (a typedef of long), the order of the RGB channels has changed to
be in the more efficient order (for typical contemporary hardware). If your
code made assumptions about the order, you will get blue where you expect
red and vice versa (you'll not notice the problem if you use shades of
gray, green, or magenta). You should port your code to use the
creator function <a href="qcolor.html#qRgb">qRgb</a>(int r,int g,int b) and the
access functions <a href="qcolor.html#qRed">qRed</a>(QRgb), <a href="qcolor.html#qBlue">qBlue</a>(QRgb), and <a href="qcolor.html#qGreen">qGreen</a>(QRgb).
If you are using the alpha channel, it hasn't moved, but you should use
the functions <a href="qcolor.html#qRgba">qRgba</a>(int,int,int,int) and <a href="qcolor.html#qAlpha">qAlpha</a>(QRgb). Note also that
<a href="qcolor.html#pixel">QColor::pixel</a>() does <i>not</i> return a QRgb (it never did on all platforms,
but your code may have assumed so on your platform) - this may also produce
strange color results - use <a href="qcolor.html#rgb">QColor::rgb</a>() if you want a QRgb.
<p> <h3><a name="QDataStream">QDataStream</a></h3>
<p> <p>The QDatastream serialization format of most Qt classes is changed
in Qt 2.x. Use <pre> QDataStream::setVersion( 1 )</pre>
to get a
datastream object that can read and write Qt 1.x format data streams.
<p> <p>If you want to write Qt 1.x format datastreams, note the following
compatibility issues:
<ul>
<li>QString: Qt 1.x has no Unicode support, so strings will be
serialized by writing the classic C string returned by <pre>
QString::<a href="qstring.html#latin1">latin1</a>().</pre>
<li><a href="#QPoint">QPoint & al.</a>: Coordinates will be
truncated to the Qt 1.x 16 bit format.
</ul>
<p> <h3><a name="QWidget">QWidget</a></h3>
<p> <h4>QWidget::recreate()</h4>
<p>
This function is now called <a href="qwidget.html#reparent">reparent()</a>.
<p> <h4>QWidget::setAcceptFocus(bool)</h4>
<p>
This function is removed.
Calls like QWidget::setAcceptFocus(TRUE) should be replaced by
<pre> QWidget::setFocusPolicy(StrongFocus)</pre>
, and
calls like QWidget::setAcceptFocus(FALSE) should be replaced by
<pre> QWidget::setFocusPolicy(NoFocus)</pre>
.
Additional policies are TabFocus and ClickFocus.
<p> <h4>QWidget::paintEvent()</h4>
<p>
paintEvent(0) is not permitted - subclasses need not check for
a null event, and might crash.
Never pass 0 as the argument to paintEvent(). You probably
just want repaint() or update() instead.
<p>
When processing a paintEvent, painting is only permitted within
the update region specified in the event. Any painting outside will be
clipped away. This shouldn't break any code (it was always like this
on MS-Windows) but makes many explicit calls to
<a href="qpainter.html#setClipRegion">QPainter::setClipRegion</a>() superfluous. Apart from the improved
consistency, the change is likely to reduce flicker and to make Qt
event slightly faster.
<p> <h3><a name="QIODevice">QIODevice</a></h3>
<p>
The protected member QIODevice::index is renamed to QIODevice::ioIndex
to avoid warnings and to allow compilation with bad C libraries that
#define index to strchr. If you have made a subclass of <a href="qiodevice.html">QIODevice</a>,
check every occurrence of the string "index" in the implementation, since
a compiler will not always catch cases like <pre>(uint)index</pre>
that need to be changed.
<p> <h3><a name="QLabel">QLabel</a></h3>
<p> <h4><pre> QLabel::setMargin()</pre>
</h4>
<p>
<pre> QLabel::setMargin()</pre>
and<pre> QLabel::margin()</pre>
have been renamed to <pre> QLabel::setIndent()</pre>
and
<pre> QLabel::indent()</pre>
, respectively. This was done to avoid
collision with <a href="qframe.html#setMargin">QFrame::setMargin</a>(), which is now virtual.
<p> <h4><pre> QLabel::setMovie()</pre>
</h4>
<p>
Previously, setting a movie on a label cleared the value of text().
Now it doesn't. If you somehow used <tt>QLabel::text()</tt>
to detect if a
movie was set, you might have trouble. This is unlikely.
<p> <h3><a name="QDialog">QDialog</a></h3>
<p> <p> The semantics of the parent pointer changed for modeless dialogs:
In Qt-2.x, dialogs are always top level windows. The parent, however,
takes the ownership of the dialog, i.e. it will delete the dialog at
destruction if it has not been explicitly deleted
already. Furthermore, the window system will be able to tell that both
the dialog and the parent belong together. Some X11 window managers
will for instance provide a common taskbar entry in that case.
<p> <p>
If the dialog belongs to a top level main window
of your application, pass this main window as parent to the dialog's
constructor. Old code (with 0 pointer) will still run. Old code that
included QDialogs as child widgets will no longer work (it never really did).
If you think you might be doing this, put a breakpoint in
<a href="qdialog.html#QDialog">QDialog::QDialog</a>() conditional on parent not being 0.
<p> <h3><a name="QStrList">QStrList</a></h3>
<p> Many methods that took a <a href="qstrlist.html">QStrList</a> can now instead take a <a href="qstringlist.html">QStringList</a>,
which is a real list of <a href="qstring.html">QString</a> values.
<p> To use QStringList rather than QStrList, change loops that look like this:
<pre>
<a href="qstrlist.html">QStrList</a> list = ...;
const char* s;
for ( s = list.<a href="qptrlist.html#first">first</a>(); s; s = list.<a href="qptrlist.html#next">next</a>() ) {
process(s);
}
</pre>
to be like this:
<pre>
<a href="qstringlist.html">QStringList</a> list = ...;
QStringList::ConstIterator i;
for ( i = list.<a href="qvaluelist.html#begin">begin</a>(); i != list.<a href="qvaluelist.html#end">end</a>(); ++i ) {
process(*i);
}
</pre>
<p> In general, the QStrList functions are less efficient, building a temporary QStringList.
<p> The following functions now use QStringList rather than QStrList
for return types/parameters.
<p> <ul>
<li><tt>void <a href="qfiledialog.html#setFilters">QFileDialog::setFilters</a>(const <a href="qstrlist.html">QStrList</a>&)</tt>
becomes <tt>void QFileDialog::setFilters(const <a href="qstringlist.html">QStringList</a>&)</tt>
<li><tt>QStrList <a href="qfiledialog.html#getOpenFileNames">QFileDialog::getOpenFileNames</a>(...)</tt>
becomes <tt>QStringList QFileDialog::getOpenFileNames(...)</tt>
<li><tt>bool QUrlDrag::decodeLocalFiles(<a href="qmimesource.html">QMimeSource</a>*, QStrList&)</tt>
becomes <tt>bool <a href="quridrag.html#decodeLocalFiles">QUriDrag::decodeLocalFiles</a>(QMimeSource*, QStringList&)</tt>
<li><tt>const QStrList *QDir::entryList(...) const</tt>
becomes <tt>QStringList <a href="qdir.html#entryList">QDir::entryList</a>(...) const</tt>
(note that the return type is no longer a pointer). You may also
choose to use encodedEntryList().
</ul>
<p> The following functions are added:
<ul>
<li><tt>QComboBox::insertStringList(const QStringList &, int index=-1)</tt>
<li><tt>QListBox::insertStringList(const QStringList &,int index=-1)</tt>
</ul>
<p> The rarely used static function <tt>void
QFont::listSubstitutions(<a href="qstrlist.html">QStrList</a>*)</tt> is replaced by <tt>QStringList
<a href="qfont.html#substitutions">QFont::substitutions</a>()</tt>.
<p> <h3><a name="QLayout">QLayout</a></h3>
<p> <p> Calling resize(0,0) or resize(1,1) will no longer work magically.
Remove all such calls. The default size of top level widgets will be their
<a href="qwidget.html#sizeHint">sizeHint()</a>.
<p> <p> The default implementation of <a href="qwidget.html#sizeHint">QWidget::sizeHint</a>() will no longer
return just an invalid size; if the widget has a layout, it will return
the layout's preferred size.
<p> <p> The special maximum MaximumHeight/Width is now QWIDGETSIZE_MAX,
not QCOORD_MAX.
<p> <p> <a href="qboxlayout.html#addWidget">QBoxLayout::addWidget()</a>
now interprets the <em>alignment</em> parameter more aggressively. A
non-default alignment now indicates that the widget should not grow to
fill the available space, but should be sized according to sizeHint().
If a widget is too small, set the alignment to 0. (Zero indicates no
alignment, and is the default.)
<p> <p> The class QGManager is removed. Subclasses of <a href="qlayout.html">QLayout</a> need to be rewritten
to use the new, much simpler <a href="qlayout.html">QLayout API</a>.
<p> <p> For typical layouts, all use of
<a href="qwidget.html#setMinimumSize">setMinimumSize()</a>
and
<a href="qwidget.html#setFixedSize">setFixedSize()</a>
can be removed.
<a href="qlayout.html#activate">activate()</a> is no longer necessary.
<p> <p>
You might like to look at the <a href="qgrid.html">QGrid</a>, <a href="qvbox.html">QVBox</a>, and <a href="qhbox.html">QHBox</a> widgets - they offer
a simple way to build nested widget structures.
<p> <h3><a name="QListView">QListView</a></h3>
<p> <p>In Qt 1.x mouse events to the viewport where redirected to the
event handlers for the listview; in Qt 2.x, this functionality is
in <a href="qscrollview.html">QScrollView</a> where mouse (and other position-oriented) events are
redirected to viewportMousePressEvent() etc, which in turn translate
the event to the coordinate system of the contents and call
contentsMousePressEvent() etc, thus providing events in the most
convenient coordinate system. If you overrode QListView::MouseButtonPress(),
<a href="qwidget.html#mouseDoubleClickEvent">QListView::mouseDoubleClickEvent</a>(), <a href="qwidget.html#mouseMoveEvent">QListView::mouseMoveEvent</a>(), or
<a href="qwidget.html#mouseReleaseEvent">QListView::mouseReleaseEvent</a>() you must instead override
viewportMousePressEvent(),
viewportMouseDoubleClickEvent(), viewportMouseMoveEvent(), or
viewportMouseReleaseEvent() respectively. New code will usually override
contentsMousePressEvent() etc.
<p> <p>The signal <a href="qlistview.html#selectionChanged">QListView::selectionChanged</a>(<a href="qlistviewitem.html">QListViewItem</a> *) can now be
emitted with a null pointer as parameter. Programs that use the
argument without checking for 0, may crash.
<p> <h3><a name="QMultiLineEdit">QMultiLineEdit</a></h3>
<p> <p>
The protected function
<pre> QMultiLineEdit::textWidth(QString*)</pre>
changed to
<pre> QMultiLineEdit::textWidth(const <a href="qstring.html">QString</a>&)</pre>
.
This is unlikely to be a problem, and you'll get a compile error
if you called it.
<p> <h3><a name="QClipboard">QClipboard</a></h3>
<p> <p>
<pre> QClipboard::pixmap()</pre>
now returns a <a href="qpixmap.html">QPixmap</a>, not a QPixmap*.
The pixmap
will be <a href="qpixmap.html#isNull">null</a> if no pixmap is on the
clipboard. <a href="qclipboard.html">QClipboard</a> now offers powerful MIME-based types on the
clipboard, just like drag-and-drop (in fact, you can reuse most of your
drag-and-drop code with clipboard operations).
<p> <h3><a name="QDropSite">QDropSite</a></h3>
<p> <P>
QDropSite is obsolete. If you simply passed <tt>this</tt>, just remove
the inheritance of QDropSite and call
<a href="qwidget.html#setAcceptDrops">setAcceptDrops(TRUE)</a> in the class
constructor.
If you passed something other than <tt>this</tt>,
your code will not work. A common case is passing
the
<a href="qscrollview.html#viewport">viewport()</a> of a <a href="qlistview.html">QListView</a>,
in which case,
override the
<a href="qscrollview.html#contentsDragMoveEvent">contentsDragMoveEvent()</a>,
etc.
functions rather than QListView's dragMoveEvent() etc. For other
cases, you will need to use an event filter to act on the drag/drop events
of another widget (as is the usual way to intercept foreign events).
<p> <h3><a name="QScrollView">QScrollView</a></h3>
<p> The parameters in the signal
<a href="qscrollview.html#contentsMoving">contentsMoving(int,int)</a>
are now positive rather than negative values, coinciding with
<a href="qscrollview.html#setContentsPos">setContentsPos()</a>. Search for
connections you make to this signal, and either change the slot they are
connected to such that it also expects positive rather than negative
values, or introduce an intermediate slot and signal that negates them.
<p> If you used drag and drop with <a href="qscrollview.html">QScrollView</a>, you may experience the problem
described for <a href="#QDropSite">QDropSite</a>.
<p> <h3><a name="QTextStream">QTextStream</a></h3>
<p> <p>
<pre> operator<<(QTextStream&, QChar&)</pre>
does not skip whitespace.
<pre> operator<<(QTextStream&, char&)</pre>
does,
as was the case with Qt 1.x. This is for backward compatibility.
<p> <h3><a name="QUriDrag">QUriDrag</a></h3>
<p> The class QUrlDrag is renamed to <a href="quridrag.html">QUriDrag</a>, and the API has been
broadened to include additional conversion routines, including
conversions to Unicode filenames (see the class documentation
for details). Note that in Qt 1.x
the QUrlDrag class used the non-standard MIME type "url/url",
while QUriDrag uses the standardized "text/uri-list" type. Other
identifiers affected by the Url to Uri change are
QUrlDrag::setUrls() and QUrlDrag::urlToLocalFile().
<p> <h3><a name="QPainter">QPainter</a></h3>
<p> <p> The GrayText painter flag has been removed. Use
<a href="qpainter.html#setPen">setPen( palette().disabled().foreground() )</a>
instead.
<p> <p> The RasterOp enum
(CopyROP,
OrROP,
XorROP,
NotAndROP,
EraseROP,
NotCopyROP,
NotOrROP,
NotXorROP,
AndROP, NotEraseROP,
NotROP,
ClearROP,
SetROP,
NopROP,
AndNotROP,
OrNotROP,
NandROP,
NorROP, LastROP)
is now part of the Qt namespace class, so if you
use it outside a member function, you'll need to prefix with Qt::.
<p> <h3><a name="QPicture">QPicture</a></h3>
<p> <p>The binary storage format of <a href="qpicture.html">QPicture</a> is changed, but the Qt 2.x
QPicture class can both read and write Qt 1.x format QPictures. No
special handling is required for reading; QPicture will automatically
detect the version number. In order to write a Qt 1.x format QPicture,
set the formatVersion parameter to 1 in the QPicture constructor.
<p> <p>For writing Qt 1.x format QPictures, the compatibility issues of <a
href="#QDataStream">QDataStream</a> applies.
<p> <p>It is safe to try to read a QPicture file generated with Qt 2.x
(without formatVersion set to 1) with a program compiled with Qt
1.x. The program will not crash, it will just issue the warning
"QPicture::play: Incompatible version 2.x" and refuse to load the
picture.
<p> <h3><a name="QPoint">QPoint, <a href="qpointarray.html">QPointArray</a>, <a href="qsize.html">QSize</a> and <a href="qrect.html">QRect</a></a></h3>
<p> <p>The basic coordinate datatype in these classes, QCOORD, is now 32
bit (int) instead of a 16 bit (short). The const values QCOORD_MIN and
QCOORD_MAX have changed accordingly.
<p> <p>QPointArray is now actually, not only seemingly, a QArray of <a href="qpoint.html">QPoint</a>
objects. The semi-internal workaround classes QPointData and QPointVal
are removed since they are no longer needed; QPoint is used directly
instead. The function <pre> QPointArray::shortPoints()</pre>
provides the point array converted to short (16bit) coordinates for
use with external functions that demand that format.
<p> <h3><a name="QImage">QImage</a></h3>
<p> <a href="qimage.html">QImage</a> uses QRgb for the colors - see <a href="#QRgb">the changes to that</a>.
<p> <h3><a name="QPixmap">QPixmap</a></h3>
<p> <pre> QPixmap::convertToImage()</pre>
with bitmaps now guarantees that color0 pixels
become color(0) in the resulting QImage. If you worked around the lack of
this, you may be able to simplify your code. If you made assumptions
about the previous undefined behavior, the symptom will be inverted
bitmaps (eg. "inside-out" masks).
<p> <p>
<pre> QPixmap::optimize(TRUE)</pre>
is replaced by
<pre> QPixmap::setOptimization(QPixmap::NormalOptim)</pre>
or
<pre> QPixmap::setOptimization(QPixmap::BestOptim)</pre>
- see the documentation
to choose which is best for your application. NormalOptim is most like
the Qt 1.x "TRUE" optimization.
<p> <h3><a name="QMenuData">QMenuData / <a href="qpopupmenu.html">QPopupMenu</a></a></h3>
<p> In Qt 1.x, new menu items were assigned either an application-wide
unique identifier or an identifier equal to the index of the item, depending on the
<a href="qmenudata.html#insertItem">insertItem(...)</a> function used.
In Qt 2.x this confusing
situation has been cleaned up: generated identifiers are always
unique across the entire application.
<p> If your code depends on generated ids
being equal to the item's index, a quick fix is to use
<pre> QMenuData::indexOf(int id)</pre>
in the handling function instead. You may alternatively pass
<pre> QMenuData::count()</pre>
as identifier when you insert the items.
<p> Furthermore, QPopupMenus can (and should!) be created with a parent
widget now, for example the main window that is used to display the
popup. This way, the popup will automatically be destroyed together
with its main window. Otherwise you'll have to take care of the
ownership manually.
<p> QPopupMenus are also reusable in 2.x. They may occur in different
locations within one menu structure or be used as both a menubar
drop-down and as a context popup-menu. This should make it possible to
significantly simplify many applications.
<p> Last but not least, <a href="qpopupmenu.html">QPopupMenu</a> no longer inherits QTableView. Instead,
it directly inherits <a href="qframe.html">QFrame</a>.
<p> <h3><a name="QValidator">QValidator (<a href="qlineedit.html">QLineEdit</a>, <a href="qcombobox.html">QComboBox</a>, <a href="qspinbox.html">QSpinBox</a>) </a></h3>
<p> <pre> QValidator::validate(...)</pre>
and
<pre> QValidator::fixup( <a href="qstring.html">QString</a> & )</pre>
are now const
functions. If your subclass reimplements validate() as a
non-const function,
you will get a compile error (validate was pure virtual).
<p> In QLineEdit, QComboBox, and QSpinBox,
setValidator(...) now takes a const pointer to a <a href="qvalidator.html">QValidator</a>, and
validator() returns a const pointer. This change highlights the fact
that the widgets do not take the ownership of the validator (a validator is
a <a href="qobject.html">QObject</a> on its own, with its own parent - you can easily set the same validator
object on many different widgets), so changing the state of
such an object or deleting it is very likely a bug.
<p> <h3><a name="QFile">QFile, <a href="qfileinfo.html">QFileInfo</a>, <a href="qdir.html">QDir</a></a></h3>
<p> File and directory names are now always Unicode strings (ie. <a href="qstring.html">QString</a>). If you used QString
in the past for the simplicity it offers, you'll probably have little consequence. However,
if you pass filenames to system functions rather than using Qt functions (eg. if you use the
Unix <tt>unlink()</tt> function rather than <tt>QFile::remove()</tt>, your code will probably
only work for Latin1 locales (eg. Western Europe, the U.S.). To ensure your code will support
filenames in other locales, either use the Qt functions, or convert the filenames via
<pre> QFile::encodeFilename()</pre>
and <pre> QFile::decodeFilename()</pre>
- but do it
<em>just</em> as you call the system function - code that mixes encoded and unencoded filenames
is very error prone. See the comments in QString, such as regarding QT_NO_ASCII_CAST that
can help find potential problems.
<p> <h3><a name="QFontMetrics">QFontMetrics</a></h3>
<p> boundingRect(char) is replaced by
boundingRect(<a href="qchar.html">QChar</a>), but since
char auto-converts to QChar, you're not likely to run into problems
with this.
<p> <h3><a name="QWindow">QWindow</a></h3>
<p> This class (which was just <a href="qwidget.html">QWidget</a> under a different name) has been
removed. If you used it, do a global search-and-replace of the word
"QWindow" with "QWidget".
<p> <h3><a name="QEvent">QEvent</a></h3>
<p> <p> The global #define macros in qevent.h have been replaced by an
enum in <a href="qevent.html">QEvent</a>. Use e.g. QEvent::Paint instead of Event_Paint. Same
for all of:
Event_None,
Event_Timer,
Event_MouseButtonPress,
Event_MouseButtonRelease,
Event_MouseButtonDblClick,
Event_MouseMove,
Event_KeyPress,
Event_KeyRelease,
Event_FocusIn,
Event_FocusOut,
Event_Enter,
Event_Leave,
Event_Paint,
Event_Move,
Event_Resize,
Event_Create,
Event_Destroy,
Event_Show,
Event_Hide,
Event_Close,
Event_Quit,
Event_Accel,
Event_Clipboard,
Event_SockAct,
Event_DragEnter,
Event_DragMove,
Event_DragLeave,
Event_Drop,
Event_DragResponse,
Event_ChildInserted,
Event_ChildRemoved,
Event_LayoutHint,
Event_ActivateControl,
Event_DeactivateControl,
and
Event_User.
<p> <p> The Q_*_EVENT macros in qevent.h have been deleted. Use an
explicit cast instead. The macros were:
Q_TIMER_EVENT,
Q_MOUSE_EVENT,
Q_KEY_EVENT,
Q_FOCUS_EVENT,
Q_PAINT_EVENT,
Q_MOVE_EVENT,
Q_RESIZE_EVENT,
Q_CLOSE_EVENT,
Q_SHOW_EVENT,
Q_HIDE_EVENT,
and
Q_CUSTOM_EVENT.
<p> <p> QChildEvents are now sent for all QObjects, not just QWidgets.
You may need to add extra checking if you use a <a href="qchildevent.html">QChildEvent</a> without
much testing of its values.
<p> <h3>All the removed functions</h3>
<p> All <a href="removed20.html">these functions</a> have been removed in
Qt 2.x. Most are simply cases where "const char*" has changed to
"const <a href="qstring.html">QString</a>&", or when an enumeration type has moved into the Qt::
namespace (which, technically, is a new name, but your code will
compile just the same anyway). This list is provided for completeness.
<p>
<!-- eof -->
<p><address><hr><div align=center>
<table width=100% cellspacing=0 border=0><tr>
<td>Copyright © 2007
<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
<td align=right><div align=right>Qt 3.3.8</div>
</table></div></address></body>
</html>