source: trunk/doc/html/porting2.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 44.8 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/porting2.doc:36 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>Porting to Qt 2.x</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<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>
33
34
35
36<p> <p>
37You're probably looking at this page because you want to port
38your application from Qt 1.x to Qt 2.x, but to be sure, let's
39review the good reasons to do this:
40<ul>
41<li>To get access to all the new Qt 2.x features like the rich text
42HTML subset for formatted labels, tooltips, online help etc.
43and the much easier to use layout classes and widgets.
44<li>To make your application truly international, with support
45for Unicode and translations for the languages of the world.
46<li>To allow your application to fit into the new look of the
47Unix desktop with configurable, very powerful "themes". The
48extended style system also integrates Qt applications better
49on MS-Windows desktops. Qt will automatically chose the right
50colors and fonts and obey global system setting changes.
51<li>To stay up-to-date with the version of Qt that gets all the
52new features and bug-fixes.
53<li>To get more speed and smoother widgets display with all the
54new anti-flicker changes in Qt.
55<li>Most of all though, you want to port to Qt 2.x
56so that your Wheel Mouse works!
57</ul>
58<p> <p>
59The Qt 2.x series is not binary compatible with the 1.x series.
60This means programs compiled for Qt 1.x must be recompiled to work
61with Qt 2.x. Qt 2.x is also not completely <em>source</em> compatible
62with 1.x, however all points of incompatibility cause
63compiler errors (rather than mysterious results), or produce run-time
64messages. The result is that Qt 2.x includes many additional features,
65discards obsolete functionality that is easily converted to use the new
66features, and that porting an application from Qt 1.x to Qt 2.x is
67a simple task well worth the amount of effort required.
68<p> To port code using Qt 1.x to use Qt 2.x:
69<p> <ul>
70<li> Briefly read the porting notes below to get an idea of what to expect.
71<li> Be sure your code compiles and runs well on all your target platforms with Qt 1.x.
72<li> Recompile with Qt 2.x. For each error, search below for related
73identifiers (eg. function names, class names) - this documented is
74structured to mention all relevant identifiers to facilitate such
75searching, even if that makes it a little verbose.
76<li> If you get stuck, ask on the qt-interest mailing list, or
77Trolltech Technical Support if you're a Professional Edition
78licensee.
79</ul>
80<p> Many very major projects, such as <a href="http://www.kde.org/">KDE</a>
81have been port, so there is plenty of expertise in the collective conscious
82that is the Qt Developer Community!
83</p>
84<p> <hr>
85<p> <h2 align=center>The Porting Notes</h2>
86<p> <ul>
87<li><b><a href="#Namespace">Namespace</a></b>
88<li><b><a href="#Virtual">Virtual Functions</a></b>
89<li><b><a href="#Collection">Collection classes</a></b>
90<li><b><a href="#DefaultParent">No Default 0 Parent Widget</a></b>
91<li><b><a href="#DebugVsRelease">Debug vs. Release</a></b>
92<li><b><a href="#QApplication">QApplication</a></b>
93<li><b><a href="#QClipboard">QClipboard</a></b>
94<li><b><a href="#QColor">QColor</a></b>
95<li><b><a href="#QDataStream">QDataStream</a></b>
96<li><b><a href="#QDialog">QDialog</a></b>
97<li><b><a href="#QDropSite">QDropSite</a></b>
98<li><b><a href="#QEvent">QEvent</a></b>
99<li><b><a href="#QFile">QFile</a></b>
100<li><b><a href="#QFontMetrics">QFontMetrics</a></b>
101<li><b><a href="#QIODevice">QIODevice</a></b>
102<li><b><a href="#QLabel">QLabel</a></b>
103<li><b><a href="#QLayout">QLayout</a></b>
104<li><b><a href="#QListView">QListView</a></b>
105<li><b><a href="#QMenuData">QMenuData</a></b>
106<li><b><a href="#QMenuData">QPopupMenu</a></b>
107<li><b><a href="#QMultiLineEdit">QMultiLineEdit</a></b>
108<li><b><a href="#QPainter">QPainter</a></b>
109<li><b><a href="#QPicture">QPicture</a></b>
110<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>
111<li><b><a href="#QPixmap">QPixmap</a></b>
112<li><b><a href="#QRgb">QRgb</a></b>
113<li><b><a href="#QScrollView">QScrollView</a></b>
114<li><b><a href="#QStrList">QStrList</a></b>
115<li><b><a href="#QString">QString</a></b>
116<li><b><a href="#QTextStream">QTextStream</a></b>
117<li><b><a href="#QUriDrag">QUriDrag / QUrlDrag</a></b>
118<li><b><a href="#QValidator">QComboBox</a></b>
119<li><b><a href="#QValidator">QLineEdit</a></b>
120<li><b><a href="#QValidator">QSpinBox</a></b>
121<li><b><a href="#QValidator">QValidator</a></b>
122<li><b><a href="#QWidget">QWidget</a></b>
123<li><b><a href="#QWindow">QWindow</a></b>
124</ul>
125<p> <hr>
126<p> <h3><a name="Namespace">Namespace</a></h3>
127<p> <p> Qt 2.x is namespace-clean, unlike 1.x. Qt now uses very few
128global identifiers. Identifiers like <code>red, blue, LeftButton,
129AlignRight, Key_Up, Key_Down, NoBrush</code> etc. are now part of a
130special class <code>Qt</code> (defined in qnamespace.h),
131which is inherited by
132most Qt classes. Member functions of classes that inherit from <a href="qwidget.html">QWidget</a>,
133etc. are totally unaffected, but code that is
134<em>not</em> in functions of classes inherited from <code>Qt</code>,
135you must qualify these identifiers like this: <code>Qt::red,
136Qt::LeftButton, Qt::AlignRight</code>, etc.
137<p> <p>The <code>qt/bin/qt20fix</code> script helps to fix the code that
138needs adaption, though most code does not need changing.
139<p> Compiling with -DQT1COMPATIBILITY will help you get going with Qt 2.x
140- it allows all the old "dirty namespace" identifiers from Qt 1.x to
141continue working. Without it, you'll get compile errors that can
142easily be fixed by searching this page for the clean identifiers.
143<p> <h3><a name="DefaultParent">No Default 0 Parent Widget</a></h3>
144<p> In Qt 1.x, all widget constructors were defined with a default value
145of 0 for the parent widget. However, only the main window of the
146application should be created with a 0 parent, all other widgets
147should have parents. Having the 0 default made it too simple to create
148bugs by forgetting to specify the parent of non-mainwindow
149widgets. Such widgets would typically never be deleted (causing memory
150leaks), and they would become top-level widgets, confusing the window
151managers. Therefore, in Qt 2.x the 0 default parent has been removed
152for the widget classes that are not likely to be used as main windows.
153<p> Note also that programs no longer need (or should) use 0 parent just
154to indicate that a widget should be top-level. See
155<pre> QWidget::isTopLevel() </pre>
156 for details. See also the notes about
157<a href="#QMenuData">QPopupMenu</a> and <a href="#QDialog">QDialog</a>
158below.
159<p> <h3><a name="Virtual">Virtual Functions</a></h3>
160<p> <p> Some virtual functions have changed signature in Qt 2.x.
161If you override them in derived classes, you must change the signature
162of your functions accordingly.
163<p> <!-- warwick can check for additions to this with his qt-2-report -->
164<ul>
165<li><pre> QWidget::setStyle(GUIStyle)</pre>
166
167<li><pre> QListView::addColumn(const char *, int)</pre>
168
169<li><pre> QListView::setColumnText(int, const char *)</pre>
170
171<li><pre> QListViewItem::setText(int, const char *)</pre>
172
173<li><pre> QMultiLineEdit::insertLine(const char *, int)</pre>
174
175<li><pre> QMultiLineEdit::insertAt(const char *, int, int, bool)</pre>
176
177<li><pre> QSpinBox::setPrefix(const char *)</pre>
178
179<li><pre> QSpinBox::setSuffix(const char *)</pre>
180
181<li><pre> QToolButton::setTextLabel(const char *, bool)</pre>
182
183<li><pre> QDoubleValidator::validate(QString &amp;, int &amp;)</pre>
184
185<li><pre> QIntValidator::validate(QString &amp;, int &amp;)</pre>
186
187<li><pre> QValidator::fixup(QString &amp;)</pre>
188
189<li><pre> QSlider::paintSlider(QPainter *, const <a href="qrect.html">QRect</a> &amp;)</pre>
190
191</ul>
192<p> This is one class of changes that are
193not detected by the compiler,
194so you should mechanically search for each of
195these function names in your header files, eg.
196<p> <pre>
197egrep -w 'setStyle|addColumn|setColumnText|setText...' *.h
198</pre>
199
200<p> Of course, you'll get a few false positives (eg. if you have a setText
201function that is not in a subclass of <a href="qlistviewitem.html">QListViewItem</a>).
202<p> <h3><a name="Collection">Collection classes</a></h3>
203<p> <p> The <a href="collection.html#collection-classes">collection classes</a> include generic
204classes such as QGDict, QGList, and
205the subclasses such as <a href="qdict.html">QDict</a> and QList.
206<p> <p> The macro-based Qt collection classes are obsolete; use the
207template-based classes instead. Simply remove includes of qgeneric.h and
208replace e.g. Q_DECLARE(<a href="qcache.html">QCache</a>,QPixmap) with QCache<QPixmap>.
209<p> <p> The GCI global typedef is replaced by QCollection::Item. Only if you
210make your own subclasses of the undocumented generic collection classes
211will you have GCI in your code.
212This change has been made to avoid collisions with other namespaces.
213<p> <p> The GCF global typedef is removed (it was not used in Qt).
214<p> <h3><a name="DebugVsRelease">Debug vs. Release</a></h3>
215<p> <p>The Q_ASSERT macro is now a null expression if the QT_CHECK_STATE flag
216is not set (i.e. if the QT_NO_CHECK flag is defined).
217<p> <p>The debug() function now outputs nothing if Qt was compiled with
218the QT_NO_DEBUG macro defined.
219<p> <h3><a name="QString">QString</a></h3>
220<p> <a href="qstring.html">QString</a> has undergone major changes internally, and although it is highly
221backward compatible, it is worth studying in detail when porting to Qt 2.x.
222The Qt 1.x QString class has been renamed to <a href="qcstring.html">QCString</a> in Qt 2.x, though if
223you use that you will incur a performance penalty since all Qt functions
224that took const char* now take const QString&.
225<p> <p>
226To take full advantage of the new <a href="i18n.html#internationalization">Internationalization</a>
227functionality in Qt 2.x, the following steps are required:
228<p> <ul>
229<li> Start converting all uses of "const char*" in parameters to
230"const QString&" - this can often be done mechanically, eg.
231using Perl. Convert usage of char[] for temporary string
232building to QString (much software already uses QString for
233this purpose as it offers many more facilities).
234<p> If you find that you are mixing usage of QCString, QString,
235and <a href="qbytearray.html">QByteArray</a>, this causes lots of unnecessary copying and
236might indicate that the true nature of the data you are
237dealing with is uncertain. If the data is NUL-terminated
2388-bit data, use QCString; if it is unterminated (ie.
239contains NULs) 8-bit data, use QByteArray; if it is text,
240use <a href="qstring.html">QString</a>.
241</p>
242<li> Put a breakpoint in <pre> QString::latin1()</pre>
243
244to catch places where
245Unicode information is being converted to ASCII (loosing
246information if your user in not using Latin1). Qt has
247a small number of calls to this - ignore those. As a stricter
248alternative, compile your code with QT_NO_ASCII_CAST defined,
249which hides the automatic conversion of QString to const char*,
250so you can catch problems at compile time.
251</p>
252<li> See the Qt <a href="i18n.html">Internationalization page</a>
253for information about the full process of internationalizing
254your software.
255</ul>
256<p> <p>
257Points to note about the new QString are:
258<p> <dl compact>
259<dt><b>Unicode</b></dt>
260<dd>
261Qt now uses Unicode throughout.
262data() now returns a <em>const</em> reference to an ASCII version
263of the string - you cannot directly access the
264string as an array of bytes, because it isn't one. Often, latin1() is
265what you want rather than data(), or just leave it to convert to
266const char* automatically. data() is only used now to aide porting to Qt 2.x,
267and ideally you'll only need latin1() or implicit conversion when interfacing
268to facilities that do not have Unicode support.
269<p> <dt><b>Automatic-expanding</b></dt>
270<dd>
271A big advantage of the new <a href="qstring.html">QString</a> is that it automatically expands
272when you write to an indexed position.
273<p> <dt><b>QChar and <a href="qcharref.html">QCharRef</a></b></dt>
274<dd>
275<a href="qchar.html">QChar</a> are the Unicode characters that make up a QString. A QCharRef is
276a temporary reference to a QChar in a QString that when assigned to
277ensures that the <a href="shclass.html#implicit-sharing">implicit sharing</a> semantics of the QString are maintained.
278You are unlikely to use QCharRef in your own code - but so that you
279understand compiler error messages, just know that <tt>mystring[123]</tt>
280is a QCharRef whenever <tt>mystring</tt> is not a constant string. A QCharRef
281has basically the same functionality as a QChar, except it is more restricted
282in what you can assign to it and cast it to (to avoid programming errors).
283<p> <dt><b>Use QString</b></dt>
284<dd>
285Try to always use QString. If you <em>must</em>, use <a href="qcstring.html">QCString</a> which is the
286old implementation from Qt 1.x.
287<p> <dt><b>Unicode vs. ASCII</b></dt>
288<dd>
289Every conversion to and from ASCII is wasted time, so try to use <a href="qstring.html">QString</a>
290as much as possible rather than const char*. This also ensures you have
291full 16-bit support.
292<p> <dt><b>Convertion to ASCII</b></dt>
293<dd>
294The return value from operator const char*() is transient - don't expect
295it to remain valid while you make deep function calls.
296It is valid for as long as you don't modify or destroy the QString.
297<p> <dt><b>QString is simpler</b></dt>
298<dd>
299Expect your code to become simpler with the new QString, especially
300places where you have used a char* to wander over the string rather
301than using indexes into the string.
302<p> <dt><b>Some hacks don't work</b></dt>
303<dd>
304This hack:
305use_sub_string( &my_string[index] )
306should be replaced by:
307use_sub_string( my_string.mid(index) )
308<p> <dt><b>QString(const char*, int) is removed</b></dt>
309<dd>
310The QString constructor taking a const char* and an integer is removed.
311Use of this constructor was error-prone, since the length included the
312'&#92;0' terminator. Use <a href="qstring.html#left">QString::left</a>(int) or <a href="qstring.html#fromLatin1">QString::fromLatin1</a>( const char*,
313int ) -- in both cases the int parameter signifies the number of characters.
314<p> <dt><b>QString(int) is private</b></dt>
315<dd>
316The <a href="qstring.html">QString</a> constructor taking an integer is now private. This function
317is not meaningful anymore, since QString does all space allocation
318automatically. 99% of cases can simple be changed to use the
319default constructor, QString().
320<p>
321In Qt 1.x the constructor was used in two ways: accidentally,
322by attempting to convert a char to a QString (the char converts to int!) -
323giving strange bugs, and as a way to make a QString big enough prior to
324calling <pre> QString::sprintf()</pre>
325 . In Qt 2.x, the accidental bug case is
326prevented (you will get a compilation error) and QString::sprintf has
327been made safe - you no longer need to pre-allocate space (though for
328other reasons, sprintf is still a poor choice - eg. it doesn't pass Unicode).
329The only remaining common case is conversion of 0 (NULL) to QString, which
330would usually give expected results in Qt 1.x. For Qt 2.x the correct
331syntax is to use <a href="qstring.html#QString-null">QString::null</a>, though note that
332the default constructor, QString(), creates a null string too.
333Assignment of 0 to a <a href="qstring.html">QString</a> is ambiguous - assign
334QString::null; you'll mainly find these in code that has been converted
335from const char* types to QString.
336This also prevents a common error case from Qt 1.x - in
337that version, mystr = 'X' would <em>not</em> produce the expected
338results and was always a programming error; in Qt 2.x, it works - making
339a single-character string.
340<p> <p>
341Also see <a href="#QStrList">QStrList</a>.
342<p> <dt><b>Signals and Slots</b></dt>
343<dd>
344Many signal/slots have changed from const char* to QString. You will
345get run-time errors when you try to <pre> QObject::connect()</pre>
346
347to the old
348signals and slots, usually with a message indicating the const QString&
349replacement signal/slot.
350<p> <dt><b>Optimize with Q2HELPER</b></dt>
351<dd>
352In qt/src/tools/qstring.cpp there is a Q2HELPER - define it for some
353extra debugging/optimizing features (don't leave it it - it kills performance).
354You'll get an extra function, qt_qstring_stats(), which will print a
355summary of how much your application is doing Unicode and ASCII
356back-and-forth conversions.
357<p> <dt><b>QString::detach() is obsolete and removed</b></dt>
358<dd>
359Since <a href="qstring.html">QString</a> is now always shared, this function does nothing.
360Remove calls to QString::detach().
361<p> <dt><b>QString::resize(int size) is obsolete and removed</b></dt>
362<dd>
363Code using this to truncate a string should use
364<a href="qstring.html#truncate">truncate(size-1)</a>.
365Code using qstr.resize(0) should use qstr = QString::null.
366Code calling resize(n) prior to using
367<a href="qstring.html#operator[]">operator[]</a> up to n just remove
368the resize(n) completely.
369<p> <dt><b>QString::size() is obsolete and removed</b></dt>
370<dd>
371Calls to this function must be replaced by
372<a href="qstring.html#length">length()</a>+1.
373<p> <dt><b>QString::setStr(const char*) is removed</b></dt>
374<dd>Try to understand why you were using this.
375If you just meant assignment, use that. Otherwise,
376you are probably using QString as an array of bytes, in which case use
377<a href="qbytearray.html">QByteArray</a> or <a href="qcstring.html">QCString</a> instead.
378<p> <dt><b>QString is not an array of bytes</b></dt>
379<dd>
380Code that uses <a href="qstring.html">QString</a> as an array of bytes should use QByteArray
381or a char[], <em>then</em> convert that to a QString if needed.
382<p> <dt><b>"string = 0"</b></dt>
383<dd>
384Assigning 0 to a QString should be assigning the null string,
385ie. string = QString::null.
386<p> <dt><b>System functions</b></dt>
387<dd>
388You may find yourself needing latin1() for passing to the operating system
389or other libraries, and be tempted to use QCString to save the conversion,
390but you are better off using Unicode throughout, then when the operating
391system supports Unicode, you'll be prepared. Some Unix operating systems
392are now beginning to have basic Unicode support, and Qt will be tracking
393these improvements as they become more widespread.
394<p> <dt><b>Bugs removed</b></dt>
395<dd>
396toShort() returns 0 (and sets *ok to false) on error.
397toUInt() now works for big valid unsigned integers.
398insert() now works into the same string.
399<p> <dt><b>NULL pointers</b></dt>
400<dd>
401When converting "const char*" usage to QString in order to make your
402application fully Unicode-aware, use QString::null for the null value
403where you would have used 0 with char pointers.
404<p> <dt><b>QString is not null terminated</b></dt>
405<dd>
406This means that inserting a 0-character
407in the middle of the string does <em>not</em> change the length(). ie.
408<pre>
409 <a href="qstring.html">QString</a> s = "fred";
410 s[1] = '\0';
411 // s.<a href="qstring.html#length">length</a>() == 4
412 // s == "f\0ed"
413 // s.<a href="qstring.html#latin1">latin1</a>() == "f"
414 s[1] = 'r';
415 // s == "fred"
416 // s.<a href="qstring.html#latin1">latin1</a>() == "fred"
417 </pre>
418
419Especially look out for this type of code:
420<pre>
421 <a href="qstring.html">QString</a> s(2);
422 s[0] = '?';
423 s[1] = 0;
424 </pre>
425
426This creates a string 2 characters long.
427To find these problems while converting, you might like to
428add <a href="qapplication.html#Q_ASSERT">Q_ASSERT</a>(strlen(d->ascii)==d->len) inside
429<pre> QString::latin1()</pre>
430 .
431<p> <dt><b>QString or Standard C++ string?</b></dt>
432<dd>
433<p>
434The Standard C++ Library string is not Unicode. Nor is wstring defined
435to be so (for the small number of platforms where it is defined at all).
436This is the same mistake made over and over
437in the history of C - only when non-8-bit characters are <em>the norm</em>
438do programmers find them usable. Though it is possible to convert between
439string and <a href="qstring.html">QString</a>, it is less efficient than using QString throughout.
440For example, when using:
441<pre>
442 QLabel::<a href="qlabel.html#setText">setText</a>( const <a href="qstring.html">QString</a>&amp; )
443</pre>
444
445if you use string, like this:
446<pre>
447 void myclass::dostuffwithtext( const string&amp; str )
448 {
449 mylabel.setText( QString(str.c_str()) );
450 }
451</pre>
452
453that will create a (ASCII only) copy of str, stored in mylabel.
454But this:
455<pre>
456 void myclass::dostuffwithtext( const <a href="qstring.html">QString</a>&amp; str )
457 {
458 mylabel.setText( str );
459 }
460</pre>
461
462will make an <a href="shclass.html#implicitly-shared">implicitly shared</a> reference to str in the <a href="qlabel.html">QLabel</a> - no copying
463at all. This function might be 10 nested function calls away from something
464like this:
465<pre>
466 void toplevelclass::initializationstuff()
467 {
468 doStuff( tr("Okay") );
469 }
470</pre>
471
472At this point, in Qt 2.x, the tr() does a very fast dictionary lookup
473through memory-mapped message files, returning some Unicode <a href="qstring.html">QString</a> for
474the appropriate language (the default being to just make a QString out
475of the text, of course - you're not <em>forced</em> to use any of these
476features), and that <em>same</em> memory mapped Unicode will be passed
477though the system. All occurrences of the translation of "Okay" can
478potentially be shared.
479<p> </dl>
480<p> <h3><a name="QApplication">QApplication</a></h3>
481<p> In the function <pre> QApplication::setColorSpec()</pre>
482 ,
483PrivateColor and TrueColor are obsolete. Use ManyColor instead.
484<p> <h3><a name="QColor">QColor</a></h3>
485<p> <p>
486All colors
487(color0,
488color1,
489black,
490white,
491darkGray,
492gray,
493lightGray,
494red,
495green,
496blue,
497cyan,
498magenta,
499yellow,
500darkRed,
501darkGreen,
502darkBlue,
503darkCyan,
504darkMagenta,
505and
506darkYellow)
507are in the Qt namespace.
508In members of classes that inherit the Qt namespace-class (eg. <a href="qwidget.html">QWidget</a>
509subclasses), you can use the unqualified names as before, but in global
510functions (eg. main()), you need to qualify them: Qt::red, Qt::white, etc.
511See also the <a href="#QRgb">QRgb</a> section below.
512<p> <h3><a name="QRgb">QRgb</a></h3>
513<p> In QRgb (a typedef of long), the order of the RGB channels has changed to
514be in the more efficient order (for typical contemporary hardware). If your
515code made assumptions about the order, you will get blue where you expect
516red and vice versa (you'll not notice the problem if you use shades of
517gray, green, or magenta). You should port your code to use the
518creator function <a href="qcolor.html#qRgb">qRgb</a>(int r,int g,int b) and the
519access 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).
520If you are using the alpha channel, it hasn't moved, but you should use
521the functions <a href="qcolor.html#qRgba">qRgba</a>(int,int,int,int) and <a href="qcolor.html#qAlpha">qAlpha</a>(QRgb). Note also that
522<a href="qcolor.html#pixel">QColor::pixel</a>() does <i>not</i> return a QRgb (it never did on all platforms,
523but your code may have assumed so on your platform) - this may also produce
524strange color results - use <a href="qcolor.html#rgb">QColor::rgb</a>() if you want a QRgb.
525<p> <h3><a name="QDataStream">QDataStream</a></h3>
526<p> <p>The QDatastream serialization format of most Qt classes is changed
527in Qt 2.x. Use <pre> QDataStream::setVersion( 1 )</pre>
528 to get a
529datastream object that can read and write Qt 1.x format data streams.
530<p> <p>If you want to write Qt 1.x format datastreams, note the following
531compatibility issues:
532<ul>
533<li>QString: Qt 1.x has no Unicode support, so strings will be
534serialized by writing the classic C string returned by <pre>
535 QString::<a href="qstring.html#latin1">latin1</a>().</pre>
536
537<li><a href="#QPoint">QPoint & al.</a>: Coordinates will be
538truncated to the Qt 1.x 16 bit format.
539</ul>
540<p> <h3><a name="QWidget">QWidget</a></h3>
541<p> <h4>QWidget::recreate()</h4>
542<p>
543This function is now called <a href="qwidget.html#reparent">reparent()</a>.
544<p> <h4>QWidget::setAcceptFocus(bool)</h4>
545<p>
546This function is removed.
547Calls like QWidget::setAcceptFocus(TRUE) should be replaced by
548<pre> QWidget::setFocusPolicy(StrongFocus)</pre>
549 , and
550calls like QWidget::setAcceptFocus(FALSE) should be replaced by
551<pre> QWidget::setFocusPolicy(NoFocus)</pre>
552 .
553Additional policies are TabFocus and ClickFocus.
554<p> <h4>QWidget::paintEvent()</h4>
555<p>
556paintEvent(0) is not permitted - subclasses need not check for
557a null event, and might crash.
558Never pass 0 as the argument to paintEvent(). You probably
559just want repaint() or update() instead.
560<p>
561When processing a paintEvent, painting is only permitted within
562the update region specified in the event. Any painting outside will be
563clipped away. This shouldn't break any code (it was always like this
564on MS-Windows) but makes many explicit calls to
565<a href="qpainter.html#setClipRegion">QPainter::setClipRegion</a>() superfluous. Apart from the improved
566consistency, the change is likely to reduce flicker and to make Qt
567event slightly faster.
568<p> <h3><a name="QIODevice">QIODevice</a></h3>
569<p>
570The protected member QIODevice::index is renamed to QIODevice::ioIndex
571to avoid warnings and to allow compilation with bad C libraries that
572#define index to strchr. If you have made a subclass of <a href="qiodevice.html">QIODevice</a>,
573check every occurrence of the string "index" in the implementation, since
574a compiler will not always catch cases like <pre>(uint)index</pre>
575
576that need to be changed.
577<p> <h3><a name="QLabel">QLabel</a></h3>
578<p> <h4><pre> QLabel::setMargin()</pre>
579 </h4>
580<p>
581<pre> QLabel::setMargin()</pre>
582 and<pre> QLabel::margin()</pre>
583
584have been renamed to <pre> QLabel::setIndent()</pre>
585 and
586<pre> QLabel::indent()</pre>
587 , respectively. This was done to avoid
588collision with <a href="qframe.html#setMargin">QFrame::setMargin</a>(), which is now virtual.
589<p> <h4><pre> QLabel::setMovie()</pre>
590 </h4>
591<p>
592Previously, setting a movie on a label cleared the value of text().
593Now it doesn't. If you somehow used <tt>QLabel::text()</tt>
594to detect if a
595movie was set, you might have trouble. This is unlikely.
596<p> <h3><a name="QDialog">QDialog</a></h3>
597<p> <p> The semantics of the parent pointer changed for modeless dialogs:
598In Qt-2.x, dialogs are always top level windows. The parent, however,
599takes the ownership of the dialog, i.e. it will delete the dialog at
600destruction if it has not been explicitly deleted
601already. Furthermore, the window system will be able to tell that both
602the dialog and the parent belong together. Some X11 window managers
603will for instance provide a common taskbar entry in that case.
604<p> <p>
605If the dialog belongs to a top level main window
606of your application, pass this main window as parent to the dialog's
607constructor. Old code (with 0 pointer) will still run. Old code that
608included QDialogs as child widgets will no longer work (it never really did).
609If you think you might be doing this, put a breakpoint in
610<a href="qdialog.html#QDialog">QDialog::QDialog</a>() conditional on parent not being 0.
611<p> <h3><a name="QStrList">QStrList</a></h3>
612<p> Many methods that took a <a href="qstrlist.html">QStrList</a> can now instead take a <a href="qstringlist.html">QStringList</a>,
613which is a real list of <a href="qstring.html">QString</a> values.
614<p> To use QStringList rather than QStrList, change loops that look like this:
615<pre>
616 <a href="qstrlist.html">QStrList</a> list = ...;
617 const char* s;
618 for ( s = list.<a href="qptrlist.html#first">first</a>(); s; s = list.<a href="qptrlist.html#next">next</a>() ) {
619 process(s);
620 }
621</pre>
622
623to be like this:
624<pre>
625 <a href="qstringlist.html">QStringList</a> list = ...;
626 QStringList::ConstIterator i;
627 for ( i = list.<a href="qvaluelist.html#begin">begin</a>(); i != list.<a href="qvaluelist.html#end">end</a>(); ++i ) {
628 process(*i);
629 }
630</pre>
631
632<p> In general, the QStrList functions are less efficient, building a temporary QStringList.
633<p> The following functions now use QStringList rather than QStrList
634for return types/parameters.
635<p> <ul>
636<li><tt>void <a href="qfiledialog.html#setFilters">QFileDialog::setFilters</a>(const <a href="qstrlist.html">QStrList</a>&)</tt>
637becomes <tt>void QFileDialog::setFilters(const <a href="qstringlist.html">QStringList</a>&)</tt>
638<li><tt>QStrList <a href="qfiledialog.html#getOpenFileNames">QFileDialog::getOpenFileNames</a>(...)</tt>
639becomes <tt>QStringList QFileDialog::getOpenFileNames(...)</tt>
640<li><tt>bool QUrlDrag::decodeLocalFiles(<a href="qmimesource.html">QMimeSource</a>*, QStrList&)</tt>
641becomes <tt>bool <a href="quridrag.html#decodeLocalFiles">QUriDrag::decodeLocalFiles</a>(QMimeSource*, QStringList&)</tt>
642<li><tt>const QStrList *QDir::entryList(...) const</tt>
643becomes <tt>QStringList <a href="qdir.html#entryList">QDir::entryList</a>(...) const</tt>
644(note that the return type is no longer a pointer). You may also
645choose to use encodedEntryList().
646</ul>
647<p> The following functions are added:
648<ul>
649<li><tt>QComboBox::insertStringList(const QStringList &, int index=-1)</tt>
650<li><tt>QListBox::insertStringList(const QStringList &,int index=-1)</tt>
651</ul>
652<p> The rarely used static function <tt>void
653QFont::listSubstitutions(<a href="qstrlist.html">QStrList</a>*)</tt> is replaced by <tt>QStringList
654<a href="qfont.html#substitutions">QFont::substitutions</a>()</tt>.
655<p> <h3><a name="QLayout">QLayout</a></h3>
656<p> <p> Calling resize(0,0) or resize(1,1) will no longer work magically.
657Remove all such calls. The default size of top level widgets will be their
658<a href="qwidget.html#sizeHint">sizeHint()</a>.
659<p> <p> The default implementation of <a href="qwidget.html#sizeHint">QWidget::sizeHint</a>() will no longer
660return just an invalid size; if the widget has a layout, it will return
661the layout's preferred size.
662<p> <p> The special maximum MaximumHeight/Width is now QWIDGETSIZE_MAX,
663not QCOORD_MAX.
664<p> <p> <a href="qboxlayout.html#addWidget">QBoxLayout::addWidget()</a>
665now interprets the <em>alignment</em> parameter more aggressively. A
666non-default alignment now indicates that the widget should not grow to
667fill the available space, but should be sized according to sizeHint().
668If a widget is too small, set the alignment to 0. (Zero indicates no
669alignment, and is the default.)
670<p> <p> The class QGManager is removed. Subclasses of <a href="qlayout.html">QLayout</a> need to be rewritten
671to use the new, much simpler <a href="qlayout.html">QLayout API</a>.
672<p> <p> For typical layouts, all use of
673<a href="qwidget.html#setMinimumSize">setMinimumSize()</a>
674and
675<a href="qwidget.html#setFixedSize">setFixedSize()</a>
676can be removed.
677<a href="qlayout.html#activate">activate()</a> is no longer necessary.
678<p> <p>
679You 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
680a simple way to build nested widget structures.
681<p> <h3><a name="QListView">QListView</a></h3>
682<p> <p>In Qt 1.x mouse events to the viewport where redirected to the
683event handlers for the listview; in Qt 2.x, this functionality is
684in <a href="qscrollview.html">QScrollView</a> where mouse (and other position-oriented) events are
685redirected to viewportMousePressEvent() etc, which in turn translate
686the event to the coordinate system of the contents and call
687contentsMousePressEvent() etc, thus providing events in the most
688convenient coordinate system. If you overrode QListView::MouseButtonPress(),
689<a href="qwidget.html#mouseDoubleClickEvent">QListView::mouseDoubleClickEvent</a>(), <a href="qwidget.html#mouseMoveEvent">QListView::mouseMoveEvent</a>(), or
690<a href="qwidget.html#mouseReleaseEvent">QListView::mouseReleaseEvent</a>() you must instead override
691viewportMousePressEvent(),
692viewportMouseDoubleClickEvent(), viewportMouseMoveEvent(), or
693viewportMouseReleaseEvent() respectively. New code will usually override
694contentsMousePressEvent() etc.
695<p> <p>The signal <a href="qlistview.html#selectionChanged">QListView::selectionChanged</a>(<a href="qlistviewitem.html">QListViewItem</a> *) can now be
696emitted with a null pointer as parameter. Programs that use the
697argument without checking for 0, may crash.
698<p> <h3><a name="QMultiLineEdit">QMultiLineEdit</a></h3>
699<p> <p>
700The protected function
701<pre> QMultiLineEdit::textWidth(QString*)</pre>
702
703changed to
704<pre> QMultiLineEdit::textWidth(const <a href="qstring.html">QString</a>&amp;)</pre>
705 .
706This is unlikely to be a problem, and you'll get a compile error
707if you called it.
708<p> <h3><a name="QClipboard">QClipboard</a></h3>
709<p> <p>
710<pre> QClipboard::pixmap()</pre>
711 now returns a <a href="qpixmap.html">QPixmap</a>, not a QPixmap*.
712The pixmap
713will be <a href="qpixmap.html#isNull">null</a> if no pixmap is on the
714clipboard. <a href="qclipboard.html">QClipboard</a> now offers powerful MIME-based types on the
715clipboard, just like drag-and-drop (in fact, you can reuse most of your
716drag-and-drop code with clipboard operations).
717<p> <h3><a name="QDropSite">QDropSite</a></h3>
718<p> <P>
719QDropSite is obsolete. If you simply passed <tt>this</tt>, just remove
720the inheritance of QDropSite and call
721<a href="qwidget.html#setAcceptDrops">setAcceptDrops(TRUE)</a> in the class
722constructor.
723If you passed something other than <tt>this</tt>,
724your code will not work. A common case is passing
725the
726<a href="qscrollview.html#viewport">viewport()</a> of a <a href="qlistview.html">QListView</a>,
727in which case,
728override the
729<a href="qscrollview.html#contentsDragMoveEvent">contentsDragMoveEvent()</a>,
730etc.
731functions rather than QListView's dragMoveEvent() etc. For other
732cases, you will need to use an event filter to act on the drag/drop events
733of another widget (as is the usual way to intercept foreign events).
734<p> <h3><a name="QScrollView">QScrollView</a></h3>
735<p> The parameters in the signal
736<a href="qscrollview.html#contentsMoving">contentsMoving(int,int)</a>
737are now positive rather than negative values, coinciding with
738<a href="qscrollview.html#setContentsPos">setContentsPos()</a>. Search for
739connections you make to this signal, and either change the slot they are
740connected to such that it also expects positive rather than negative
741values, or introduce an intermediate slot and signal that negates them.
742<p> If you used drag and drop with <a href="qscrollview.html">QScrollView</a>, you may experience the problem
743described for <a href="#QDropSite">QDropSite</a>.
744<p> <h3><a name="QTextStream">QTextStream</a></h3>
745<p> <p>
746<pre> operator&lt;&lt;(QTextStream&amp;, QChar&amp;)</pre>
747 does not skip whitespace.
748<pre> operator&lt;&lt;(QTextStream&amp;, char&amp;)</pre>
749 does,
750as was the case with Qt 1.x. This is for backward compatibility.
751<p> <h3><a name="QUriDrag">QUriDrag</a></h3>
752<p> The class QUrlDrag is renamed to <a href="quridrag.html">QUriDrag</a>, and the API has been
753broadened to include additional conversion routines, including
754conversions to Unicode filenames (see the class documentation
755for details). Note that in Qt 1.x
756the QUrlDrag class used the non-standard MIME type "url/url",
757while QUriDrag uses the standardized "text/uri-list" type. Other
758identifiers affected by the Url to Uri change are
759QUrlDrag::setUrls() and QUrlDrag::urlToLocalFile().
760<p> <h3><a name="QPainter">QPainter</a></h3>
761<p> <p> The GrayText painter flag has been removed. Use
762<a href="qpainter.html#setPen">setPen( palette().disabled().foreground() )</a>
763instead.
764<p> <p> The RasterOp enum
765(CopyROP,
766OrROP,
767XorROP,
768NotAndROP,
769EraseROP,
770NotCopyROP,
771NotOrROP,
772NotXorROP,
773AndROP, NotEraseROP,
774NotROP,
775ClearROP,
776SetROP,
777NopROP,
778AndNotROP,
779OrNotROP,
780NandROP,
781NorROP, LastROP)
782is now part of the Qt namespace class, so if you
783use it outside a member function, you'll need to prefix with Qt::.
784<p> <h3><a name="QPicture">QPicture</a></h3>
785<p> <p>The binary storage format of <a href="qpicture.html">QPicture</a> is changed, but the Qt 2.x
786QPicture class can both read and write Qt 1.x format QPictures. No
787special handling is required for reading; QPicture will automatically
788detect the version number. In order to write a Qt 1.x format QPicture,
789set the formatVersion parameter to 1 in the QPicture constructor.
790<p> <p>For writing Qt 1.x format QPictures, the compatibility issues of <a
791href="#QDataStream">QDataStream</a> applies.
792<p> <p>It is safe to try to read a QPicture file generated with Qt 2.x
793(without formatVersion set to 1) with a program compiled with Qt
7941.x. The program will not crash, it will just issue the warning
795"QPicture::play: Incompatible version 2.x" and refuse to load the
796picture.
797<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>
798<p> <p>The basic coordinate datatype in these classes, QCOORD, is now 32
799bit (int) instead of a 16 bit (short). The const values QCOORD_MIN and
800QCOORD_MAX have changed accordingly.
801<p> <p>QPointArray is now actually, not only seemingly, a QArray of <a href="qpoint.html">QPoint</a>
802objects. The semi-internal workaround classes QPointData and QPointVal
803are removed since they are no longer needed; QPoint is used directly
804instead. The function <pre> QPointArray::shortPoints()</pre>
805
806provides the point array converted to short (16bit) coordinates for
807use with external functions that demand that format.
808<p> <h3><a name="QImage">QImage</a></h3>
809<p> <a href="qimage.html">QImage</a> uses QRgb for the colors - see <a href="#QRgb">the changes to that</a>.
810<p> <h3><a name="QPixmap">QPixmap</a></h3>
811<p> <pre> QPixmap::convertToImage()</pre>
812 with bitmaps now guarantees that color0 pixels
813become color(0) in the resulting QImage. If you worked around the lack of
814this, you may be able to simplify your code. If you made assumptions
815about the previous undefined behavior, the symptom will be inverted
816bitmaps (eg. "inside-out" masks).
817<p> <p>
818<pre> QPixmap::optimize(TRUE)</pre>
819
820is replaced by
821<pre> QPixmap::setOptimization(QPixmap::NormalOptim)</pre>
822
823or
824<pre> QPixmap::setOptimization(QPixmap::BestOptim)</pre>
825
826- see the documentation
827to choose which is best for your application. NormalOptim is most like
828the Qt 1.x "TRUE" optimization.
829<p> <h3><a name="QMenuData">QMenuData / <a href="qpopupmenu.html">QPopupMenu</a></a></h3>
830<p> In Qt 1.x, new menu items were assigned either an application-wide
831unique identifier or an identifier equal to the index of the item, depending on the
832<a href="qmenudata.html#insertItem">insertItem(...)</a> function used.
833In Qt 2.x this confusing
834situation has been cleaned up: generated identifiers are always
835unique across the entire application.
836<p> If your code depends on generated ids
837being equal to the item's index, a quick fix is to use
838<pre> QMenuData::indexOf(int id)</pre>
839
840in the handling function instead. You may alternatively pass
841<pre> QMenuData::count()</pre>
842
843as identifier when you insert the items.
844<p> Furthermore, QPopupMenus can (and should!) be created with a parent
845widget now, for example the main window that is used to display the
846popup. This way, the popup will automatically be destroyed together
847with its main window. Otherwise you'll have to take care of the
848ownership manually.
849<p> QPopupMenus are also reusable in 2.x. They may occur in different
850locations within one menu structure or be used as both a menubar
851drop-down and as a context popup-menu. This should make it possible to
852significantly simplify many applications.
853<p> Last but not least, <a href="qpopupmenu.html">QPopupMenu</a> no longer inherits QTableView. Instead,
854it directly inherits <a href="qframe.html">QFrame</a>.
855<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>
856<p> <pre> QValidator::validate(...)</pre>
857
858and
859<pre> QValidator::fixup( <a href="qstring.html">QString</a> &amp; )</pre>
860
861are now const
862functions. If your subclass reimplements validate() as a
863non-const function,
864you will get a compile error (validate was pure virtual).
865<p> In QLineEdit, QComboBox, and QSpinBox,
866setValidator(...) now takes a const pointer to a <a href="qvalidator.html">QValidator</a>, and
867validator() returns a const pointer. This change highlights the fact
868that the widgets do not take the ownership of the validator (a validator is
869a <a href="qobject.html">QObject</a> on its own, with its own parent - you can easily set the same validator
870object on many different widgets), so changing the state of
871such an object or deleting it is very likely a bug.
872<p> <h3><a name="QFile">QFile, <a href="qfileinfo.html">QFileInfo</a>, <a href="qdir.html">QDir</a></a></h3>
873<p> File and directory names are now always Unicode strings (ie. <a href="qstring.html">QString</a>). If you used QString
874in the past for the simplicity it offers, you'll probably have little consequence. However,
875if you pass filenames to system functions rather than using Qt functions (eg. if you use the
876Unix <tt>unlink()</tt> function rather than <tt>QFile::remove()</tt>, your code will probably
877only work for Latin1 locales (eg. Western Europe, the U.S.). To ensure your code will support
878filenames in other locales, either use the Qt functions, or convert the filenames via
879<pre> QFile::encodeFilename()</pre>
880 and <pre> QFile::decodeFilename()</pre>
881 - but do it
882<em>just</em> as you call the system function - code that mixes encoded and unencoded filenames
883is very error prone. See the comments in QString, such as regarding QT_NO_ASCII_CAST that
884can help find potential problems.
885<p> <h3><a name="QFontMetrics">QFontMetrics</a></h3>
886<p> boundingRect(char) is replaced by
887boundingRect(<a href="qchar.html">QChar</a>), but since
888char auto-converts to QChar, you're not likely to run into problems
889with this.
890<p> <h3><a name="QWindow">QWindow</a></h3>
891<p> This class (which was just <a href="qwidget.html">QWidget</a> under a different name) has been
892removed. If you used it, do a global search-and-replace of the word
893"QWindow" with "QWidget".
894<p> <h3><a name="QEvent">QEvent</a></h3>
895<p> <p> The global #define macros in qevent.h have been replaced by an
896enum in <a href="qevent.html">QEvent</a>. Use e.g. QEvent::Paint instead of Event_Paint. Same
897for all of:
898Event_None,
899Event_Timer,
900Event_MouseButtonPress,
901Event_MouseButtonRelease,
902Event_MouseButtonDblClick,
903Event_MouseMove,
904Event_KeyPress,
905Event_KeyRelease,
906Event_FocusIn,
907Event_FocusOut,
908Event_Enter,
909Event_Leave,
910Event_Paint,
911Event_Move,
912Event_Resize,
913Event_Create,
914Event_Destroy,
915Event_Show,
916Event_Hide,
917Event_Close,
918Event_Quit,
919Event_Accel,
920Event_Clipboard,
921Event_SockAct,
922Event_DragEnter,
923Event_DragMove,
924Event_DragLeave,
925Event_Drop,
926Event_DragResponse,
927Event_ChildInserted,
928Event_ChildRemoved,
929Event_LayoutHint,
930Event_ActivateControl,
931Event_DeactivateControl,
932and
933Event_User.
934<p> <p> The Q_*_EVENT macros in qevent.h have been deleted. Use an
935explicit cast instead. The macros were:
936Q_TIMER_EVENT,
937Q_MOUSE_EVENT,
938Q_KEY_EVENT,
939Q_FOCUS_EVENT,
940Q_PAINT_EVENT,
941Q_MOVE_EVENT,
942Q_RESIZE_EVENT,
943Q_CLOSE_EVENT,
944Q_SHOW_EVENT,
945Q_HIDE_EVENT,
946and
947Q_CUSTOM_EVENT.
948<p> <p> QChildEvents are now sent for all QObjects, not just QWidgets.
949You may need to add extra checking if you use a <a href="qchildevent.html">QChildEvent</a> without
950much testing of its values.
951<p> <h3>All the removed functions</h3>
952<p> All <a href="removed20.html">these functions</a> have been removed in
953Qt 2.x. Most are simply cases where "const char*" has changed to
954"const <a href="qstring.html">QString</a>&", or when an enumeration type has moved into the Qt::
955namespace (which, technically, is a new name, but your code will
956compile just the same anyway). This list is provided for completeness.
957<p>
958<!-- eof -->
959<p><address><hr><div align=center>
960<table width=100% cellspacing=0 border=0><tr>
961<td>Copyright &copy; 2007
962<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
963<td align=right><div align=right>Qt 3.3.8</div>
964</table></div></address></body>
965</html>
Note: See TracBrowser for help on using the repository browser.