diff options
Diffstat (limited to 'doc/src/porting')
29 files changed, 9912 insertions, 0 deletions
diff --git a/doc/src/porting/porting-qsa.qdoc b/doc/src/porting/porting-qsa.qdoc new file mode 100644 index 0000000..d22e2db --- /dev/null +++ b/doc/src/porting/porting-qsa.qdoc @@ -0,0 +1,475 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Moving from QSA to Qt Script + \page porting-qsa.html + \ingroup porting + + The purpose of this document is to map the differences between Qt + Script for Applications (QSA) and Qt Script, the ECMAScript compatible + engine supplied with Qt 4.3. This document is not supposed to be a + complete function by function porting guide, but will cover the most + obvious aspects. + + First of all it is important to realize that Qt Script is only an + interpreter, it does not provide an editor, completion or script project + management, like QSA does. Qt Script however does provides almost full + compliance with the ECMAScript standard and performs significantly + better than the script engine provided by QSA. + + \tableofcontents + + \section1 The Scripting Language + + The scripting language used in QSA, from here on referred to as QSA, + was derived from ECMAScript 3.0 and 4.0 and is a hybrid of these + standards. Most of the run-time logic, such as classes and scoping + rules, is based on the ECMAScript 4.0 proposal, while the library + implementation is based on the ECMAScript 3.0 standard. + Qt Script on the other hand is solely based on the ECMAScript 3.0 + standard. Though the languages look identical at first glance, + there are a few differences that we'll cover in the sections below. + + + \section2 Classes vs. Objects and Properties + + QSA implements classes and inheritance much in a familiar way to users + of other object oriented languages, like C++ and Java. However, the + ECMAScript 3.0 standard defines that everything is an object, and objects + can have named properties. For instance to create an point object with + the properties x and y one would write the following Qt Script code: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 0 + + The object \c point in this case is constructed as a plain object and + we assign two properties, \c x and \c y, to it with the values 12 and + 35. The \c point object is assigned to the "Global Object" as the + named property \c{point}. The global object can be considered the + global namespace of the script engine. Similarly, global functions are + named properties of the global object; for example: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 1 + + An equivalent construction that illustrates that the function is a + property of the global object is the following assignment: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 2 + + Since functions are objects, they can be assigned to objects as + properties, becoming member functions: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 3 + + In the code above, we see the first subtle difference between + QSA and Qt Script. In QSA one would write the point class like this: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 4 + + where in the \c manhattanLength() function we access \c x and \c y + directly because, when the function is called, the \c this object is + implicitly part of the current scope, as in C++. In Qt Script, + however, this is not the case, and we need to explicitly access + the \c x and \c y values via \c{this}. + + All the code above runs with QSA except the assignment of a function + to \c{point.manhattanLength}, which we repeat here for clarity: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 5 + + This is because, in QSA, the value of \c this is decided based on + the location of the declaration of the function it is used in. In the + code above, the function is assigned to an object, but it is declared + in the global scope, hence there will be no valid \c this value. + In Qt Script, the value of \c this is decided at run-time, + hence you could have assigned the \c manhattanLength() function to any + object that had \c x and \c y values. + + + \section2 Constructors + + In the code above, we use a rather awkward method for constructing + the objects, by first instantiating them, then manually + assigning properties to them. In QSA, the proper way to solve this + is to implement a constructor in the class: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 6 + + The equivalent in Qt Script is to create a constructor function: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 7 + + As we can see, the constructor is just a normal function. What is + special with is how we call it, namely prefixed with the \c new + keyword. This will create a new object and call the \c Car() + function with the newly created object as the \c this pointer. + So, in a sense, it is equivalent to: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 8 + + This is similar to the manhattenLength() example above. Again, the + main difference between QSA and Qt Script is that one has to + explicitly use the keyword \c this to access the members and that + instead of declaring the variable, \c regNumber, we just extend the + \c this object with the property. + + + \section2 Member Functions and Prototypes + + As we saw above, one way of creating member functions of a Qt Script + object is to assign the member function to the object as a property + and use the \c this object inside the functions. So, if we add a + \c toString function to the \c Car class + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 9 + + one could write this in Qt Script as: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 10 + + In QSA, the member functions were part of the class declaration, + and were therefore shared between all instances of a given class. + In Qt Script, each instance has a instance member for each function. + This means that more memory is used when multiple instances are used. + Qt Script uses prototypes to remedy this. + + The basic prototype-based inheritance mechanism works as follows. + Each Qt Script object has an internal link to another object, its + prototype. When a property is looked up in an object, and the object + itself does not have the property, the interpreter searches for the + property in the prototype object instead; if the prototype has the + property then that property is returned. If the prototype object does + not have the property, the interpreter searches for the property in + the prototype of the prototype object, and so on. + + This chain of objects constitutes a prototype chain. The chain of + prototype objects is followed until the property is found or the end + of the chain is reached. + + To make the \c toString() function part of the prototype, we write + code like this: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 11 + + Here, we made the \c toString() function part of the prototype so + that, when we call \c{car.toString()} it will be resolved via the + internal prototype object of the car object. Note, however, that the + \c this object is still the original object that the function was + called on, namely \c{car}. + + + \section2 Inheritance + + Now that we've seen how to use prototypes to create a "class" members + in Qt Script, let's see how we can use prototypes to create + polymorphism. In QSA you would write + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 12 + + With Qt Script, we acheive the same effect by creating a prototype + chain. The default prototype of an object is a plain \c Object + without any special members, but it is possible to replace this + object with another prototype object. + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 13 + + In the code above, we have a constructor, \c{GasolineCar}, which + calls the "base class" implementation of the constructor to + initialize the \c this object with the property \c{regNumber}, + based on the values passed in the constructor. The interesting line + in this case is the line after the constructor where we change the + default prototype for \c GasolineCar to be an instance of type + \c{Car}. This means that all members available in a \c Car object + are now available in all \c GasolineCar objects. In the last line, + we replace the \c toString() function in the prototype with our own, + thus overriding the \c toString() for all instances of + \c{GasolineCar}. + + + \section2 Static Members + + QSA allowed users to declare static members in classes, and these + could be accessed both through instances of the class and through + the class itself. For example, the following variable is accessed + through the \c Car class: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 14 + + The equivalent in Qt Script is to assign variables that should appear + as static members as properties of the constructor function. For + example: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 15 + + Note that in QSA, static member variables were also accessible in + instances of the given class. In Qt Script, with the approach + illustrated above, the variable is a member of the constructor + object only, and thus only accessible through \c{Car.globalCount}. + + + \section1 The Built-in Functions and Library + + The built-in functions in QSA are based on those defined in the + ECMAScript 3.0 standard, the same standard used for Qt Script, but + QSA adds some extensions to this, specifically for the \c String + and \c RegExp types. QSA also lacked some functions from the + standard, most notably the \c Date type. Below we list all the + differences. All changes made to Qt Script are to increase + compliance with ECMAScript 3.0. + + \table + \header \o QSA Function \o Notes about Equivalent Qt Script Functions + \row \o eval() + \o The eval function in QSA opened a new scope for code being + executed in the eval function, so locally declared variables were not + accessible outside. In Qt Script, the eval() function shares the + current scope, making locally declared variables accessible outside + the eval() call. + + \row \o debug() + \o This function is not available in Qt Script. Use print() instead. + + \row \o connect() + \o QSA had closures, meaning that a member function + reference implicitly contained its \c this object. Qt Script does not + support this. See the Qt Script documentation for details on using the + connect function. + + \row \o String.arg() + \o This function is not available in Qt Script. Use replace() or concat() instead. + + \row \o String.argDec() + \o This function is not available in Qt Script. Use replace() or concat() instead. + + \row \o String.argInt() + \o This function is not available in Qt Script. Use replace() or concat() instead. + + \row \o String.argStr() + \o This function is not available in Qt Script. Use replace() or concat() instead. + + \row \o String.endsWith() + \o This function is not available in Qt Script. Use lastIndexOf() instead. + + \row \o String.find() + \o This function is not available in Qt Script. Use indexOf() instead. + + \row \o String.findRev() + \o This function is not available in Qt Script. Use lastIndexOf() and length instead. + + \row \o String.isEmpty() + \o This function is not available in Qt Script. Use length == 0 instead. + + \row \o String.left() + \o This function is not available in Qt Script. Use substring() instead. + + \row \o String.lower() + \o This function is not available in Qt Script. Use toLowerCase() instead. + + \row \o String.mid() + \o This function is not available in Qt Script. Use substring() instead. + + \row \o String.right() + \o This function is not available in Qt Script. Use substring() instead. + + \row \o String.searchRev() + \o This function is not available in Qt Script. Use search() / match() instead. + + \row \o String.startsWith() + \o This function is not available in Qt Script. Use indexOf() == 0 instead. + + \row \o String.upper() + \o This function is not available in Qt Script. Use toUpperCase() instead. + + \row \o RegExp.valid + \o This property is not available in Qt Script because it is not + required; a \c SyntaxError exception is thrown for bad \c RegExp objects. + + \row \o RegExp.empty + \o This property is not available in Qt Script. Use \c{toString().length == 0} instead. + + \row \o RegExp.matchedLength + \o This property is not available in Qt Script. RegExp.exec() returns an + array whose size is the matched length. + + \row \o RegExp.capturedTexts + \o This property is not available in Qt Script. RegExp.exec() returns an + array of captured texts. + + \row \o RegExp.search() + \o This function is not available in Qt Script. Use RegExp.exec() instead. + + \row \o RegExp.searchRev() + \o This function is not available in Qt Script. Use RegExp.exec() or + String.search()/match() instead. + + \row \o RegExp.exactMatch() + \o This function is not available in Qt Script. Use RegExp.exec() instead. + + \row \o RegExp.pos() + \o This function is not available in Qt Script. Use String.match() instead. + + \row \o RegExp.cap() + \o This function is not available in Qt Script. RegExp.exec() returns an + array of captured texts. + \endtable + + QSA also defined some internal Qt API which is not present in Qt + Script. The types provided by QSA which are not provided by Qt Script are: + + \list + \o Rect + \o Point + \o Size + \o Color + \o Palette + \o ColorGroup + \o Font + \o Pixmap + \o ByteArray + \endlist + + + \section1 The C++ API of QSA vs Qt Script + + QSA is more than just a scripting engine. It provides project + management, an editor with completion and a minimalistic IDE to edit + scriptable projects. Qt Script on the other hand is just a scripting + engine. This means that equivalents to the classes \c QSEditor, + \c QSScript, \c QSProject and \c QSWorkbench do not exist in Qt Script. + QSA also provides some extension APIs through the \c QSUtilFactory and + \c QSInputDialogFactory. There is also no equivalent to these classes + in the Qt Script API. + + + \section2 Making QObjects Accessible from Scripts + + There are two different ways of making \l{QObject}s accessible from + scripts in QSA. The first method is via the + \c QSInterpreter::addTransientObject() and \c QSProject::addObject() + functions. In this case objects are added to the global namespace of + the interpreter using their object names as the names of the + variables. + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 16 + + The code above adds the button to the global namespace under the name + "button". One obvious limitation here is that there is potential for + either unnamed \l{QObject}s or objects whose names conflict. Qt Script + provides a more flexible way of adding QObjects to the scripting + environment. + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 17 + + In the code above we create a QPushButton and wrap it in a script + value using the function, QScriptEngine::newQObject(). This gives us + a script value that we put into the global object using the name + "button". The concept of objects and properties discussed above is + quite visible here in the public C++ API as well. We have no + dependency on the object's name and we can also resolve name conflicts + more gracefully. Here, we operate directly on QScriptValue objects. + This is the actual object that is being passed around inside + the script engine, so we actually have low-level access to the + internal script data structures, far beyond that which is possible + in QSA. Properties, signals and slots of the QObject are accessible + to the scripter in Qt Script, just like in QSA. + + The other way to expose \l{QObject}s in QSA was to create a + \c QSObjectFactory that made it possible to instantiate QObjects from + scripts. + + Below is listed some code from the filter example in the QSA + package. + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 18 + + The equivalent in Qt Script is written in much the same way as + constructors are written in scripts. We register a callback C++ + function under the name "ImageSource" in the global namespace and + return the QObject from this function: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 19 + + In the Qt Script case we use the same approach that we use to expose + a QObject, namely via QScriptEngine::newQObject(). This function also + has the benefit that it is possible to specify if the QObject should + expose properties and slots of its base class. It is also possible to + specify custom ownership rules. + + The reader might question why we don't add the constructor function + directly into the namespace, but create a meta-object script value for + it in addition. The plain function would certainly be good enough, + but by creating a QMetaObject based constructor we get the enums on + QPushButton for free in the QPushButton function object. Exposing + enums in QSA is rather painful in comparison. + + If we want to add more "static" data to the QPushButton type in Qt + Script, we're free to add properties, similar to how we did for + the script. It is also possible to add custom functions to a Qt Script + QPushButton instance by setting more properties on it, such as making + the \l{QPushButton::}{setText()} C++ function available. It is also + possible to acheive this by installing a custom prototype, and be + memory efficient, as discussed in the script example above. + + + \section2 Accessing Non-QObjects + + In QSA, it was possible to expose non-QObjects to QSA by wrapping them + in a QObject and using either \c QSWrapperFactory or \c QSObjectFactory + to expose them. Deciding when to use each of these classes could be + confusing, as one was used for script based construction and the other + for wrapping function parameters and return values, but in essence they + did exactly the same thing. + + In Qt Script, providing access to QObjects and non-QObjects is done in + the same way as shown above, by creating a constructor function, and + by adding properties or a custom prototype to the constructed object. + + + \section2 Data Mapping + + QSA supported a hardcoded set of type mappings which covered most + of the QVariant types, QObjects and primitives. For more complex type + signatures, such as the template-based tool classes, it had rather + limited support. Qt Script is significantly better at type mapping + and will convert lists of template types into arrays of the + appropriate types, given that all the types are declared to the + meta-type system. +*/ diff --git a/doc/src/porting/porting4-canvas.qdoc b/doc/src/porting/porting4-canvas.qdoc new file mode 100644 index 0000000..5435723 --- /dev/null +++ b/doc/src/porting/porting4-canvas.qdoc @@ -0,0 +1,702 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page graphicsview-porting.html + \title Porting to Graphics View + \contentspage {Porting Guides}{Contents} + \previouspage Porting UI Files to Qt 4 + \nextpage qt3to4 - The Qt 3 to 4 Porting Tool + \ingroup porting + \brief Hints and tips to assist with porting canvas applications to the + Graphics View framework. + + \keyword QGraphicsView GraphicsView Porting Graphics Canvas + \since 4.2 + + Graphics View provides a surface for managing and interacting with a large + number of custom-made 2D graphical items, and a view widget for + visualizing the items, with support for zooming and rotation. Graphics + View was introduced in Qt 4.2, replacing its predecessor, QCanvas. For + more on Graphics View, see \l{The Graphics View Framework}. + + This document walks through the steps needed, class by class and function + by function, to port a QCanvas application to Graphics View. + + \tableofcontents + + Qt 4.2 provides two complete examples of Q3Canvas applications ported to + Graphics View: + + \list + \o \l{Ported Canvas Example}, the canvas example from Qt 3. + \o \l{Ported Asteroids Example}, the Asteroids game from the Qt 3 demo. + \endlist + + \section1 Introduction + + Conceptually, the Graphics View classes from Qt 4 and the Canvas + classes from Qt 3 provide similar functionality using a similar + design. Instead of "canvas", we use the term "scene". Otherwise, the + class names and functions are almost the same as in Qt 3. The easiest + classes to port will be QCanvas and QCanvasView. Experience shows that + most time is spent porting the item classes, depending on the + complexity of the QCanvasItem classes you have been using before. + + This porting guide will assume you have already ported your + application to Qt 4, by making use of Q3Canvas. If you have not done + so already, as a first step, run the \l qt3to4 tool on your + project. This tool will automate the most tedious part of the porting + effort. + + Some additional steps are usually required before your application + will compile and run. You can read more about the porting process in + \l{Porting to Qt 4}. + + \section1 Porting from Q3Canvas + + QGraphicsScene is the closest equivalent to Q3Canvas. There + are some noticable differences in this new API: Whereas the + Q3Canvas classes use integer precision, QGraphicsScene is + entirely based on double coordinates, with graphical + primitives such as QPointF instead of QPoint, QRectF instead + of QRect, and QPolygonF and QPainterPath. The canvas area is + defined by a scene rectangle, allowing negative coordinates, + as opposed to Q3Canvas, which only defines a size (QSize), and + whose top-left corner is always (0, 0). + + In addition, there is no explicit support for canvas tiles + anymore; see \l{Porting scenes with tiles} for more + information. The chunks-based indexing system has been + replaced with an implicitly maintained internal BSP tree. + + \section2 Porting table + + \table + \header \o Q3Canvas \o QGraphicsScene + + \row \o Q3Canvas::Q3Canvas() \o There is no QPixmap based + constructor, and the concept of tiles is gone. You can use + QGraphicsScene::backgroundBrush to set a brush pattern for + the background, or reimplement + QGraphicsScene::drawBackground() in a QGraphicsScene + subclass (see \l{Porting scenes with tiles}). In addition, + the QGraphicsScene geometry is provided as a full + QRectF. Instead of Q3Canvas(int width, int height), you can + use QGraphicsScene(int top, int left, int width, int + height). + + \row \o Q3Canvas::allItems() \o QGraphicsScene::items() + returns a list of all items on the scene. + + \row \o Q3Canvas::backgroundColor() \o You can assign a color for the + background through the QGraphicsScene::backgroundBrush + or QGraphicsView::backgroundBrush properties. + + \row \o Q3Canvas::backgroundPixmap() \o You can set a tiled + pixmap for the background through + QGraphicsScene::backgroundBrush or + QGraphicsView::backgroundBrush. For more control on the pixmap + positioning, you can reimplement + QGraphicsScene::drawBackground() or + QGraphicsView::drawBackground(). + + \row \o Q3Canvas::chunkSize() \o The closest equivalent to the + chunks size in Q3Canvas is the depth of QGraphicsScene's BSP + tree. QGraphicsScene assigns a depth automatically, and the + size of each scene segment depends on this depth, and + QGraphicsScene::sceneRect(). See + QGraphicsScene::itemIndexMethod. + + \row \o Q3Canvas::collisions() \o QGraphicsScene provides + several means to detect item collisions. The + QGraphicsScene::items() overloads return items that collide + with a point, a rectangle, a polygon, or an arbitrary vector + path (QPainterPath). You can also call + QGraphicsScene::collidingItems() to determine collision with + an item. + + \row \o Q3Canvas::drawArea() \o The QGraphicsScene::render() + function provides the original behavior + Q3Canvas::drawArea(). In addition, you can pass a source + rectangle for rendering only parts of the scene, and a + destination rectangle for rendering onto designated area of + the destination device. QGraphicsScene::render() can + optionally transform the source rectangle to fit into the + destination rectangle. See \l{Printing} + + \row \o Q3Canvas::onCanvas() \o The is no equivalent to this + function in Graphics View. However, you can combine + QGraphicsScene::sceneRect() and QRectF::intersects(): + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 0 + + \row \o Q3Canvas::rect() \o The equivalent, + QGraphicsScene::sceneRect(), returns a QRectF (double + precision coordinates). Its top-left corner can be an + arbitrary coordinate (Q3Canvas::rect().topLeft() is always (0, + 0)). + + \row \o Q3Canvas::resize() \o You can call + QGraphicsScene::setSceneRect(0, 0, width, height) instead. + + \row \o Q3Canvas::retune() \o See + QGraphicsScene::itemIndexMethod. You can tune the indexing by + setting a suitable sceneRect(). The optimal depth of + QGraphicsScene's BSP tree is determined automatically. + + \row \o Q3Canvas::setAdvancePeriod() \o There is no concept of + an advance period in the new API; instead, you can connect + QTimer::timeout() to the QGraphicsScene::advance() slot to + obtain similar functionality. This will cause all items' + QGraphicsItem::advance() function to be called. See also + QGraphicsItemAnimation. + + \row \o Q3Canvas::setAllChanged() \o You can call + QGraphicsScene::update() with no arguments. + + \row \o Q3Canvas::setChanged() \o QGraphicsScene::update() + will trigger a repaint of the whole scene, or parts of the + scene. + + \row \o Q3Canvas::setDoubleBuffering() \o Q3Canvas' double + buffering enabled cacheing of the scene contents in device + (i.e., viewport) coordinates. This cache layer has been moved + to the view instead; you can cache QGraphicsScene's background + through + QGraphicsView::setCacheMode(). QGraphicsView::resetCachedContent() + will reset the areas of the cache that has changed. + + \row \o Q3Canvas::tile() \o See \l{Porting scenes with tiles}. + + \row \o Q3Canvas::setTiles() \o See \l{Porting scenes with tiles}. + + \row \o Q3Canvas::setUnchanged() \o There is no equivalent in + Graphics View. This call can usually be removed with no side + effects. + + \row \o Q3Canvas::setUpdatePeriod() \o There is no concept of an + update period in the new API; instead, you can connect + QTimer::timeout() to the QGraphicsScene::update() slot to obtain + similar functionality. See also QGraphicsItemAnimation. + + \row \o Q3Canvas::size() \o + \tt{QGraphicsScene::sceneRect().size()} returns a QSizeF, with + double precision coordinates. + + \row \o Q3Canvas::validChunk() \o To determine if an area is + inside the scene area or not, you can combine + QRectF::intersects() with QGraphicsScene::sceneRect(). + + \row \o Q3Canvas::resized() \o QGraphicsScene emits + \l{QGraphicsScene::sceneRectChanged()}{sceneRectChanged()} + whenever the scene rect changes. + + \row \o Q3Canvas::drawBackground() \o You can reimplement + QGraphicsScene::drawBackground() to render the scene + background. You can also reimplement + QGraphicsView::drawBackground() to override this background if + you need different backgrounds for different views. + + \row \o Q3Canvas::drawForeground() \o You can reimplement + QGraphicsScene::drawForeground() to render the scene + foreground. You can also reimplement + QGraphicsView::drawForeground() to override this foreground if + you need different foregrounds for different views. + + \endtable + + \section2 Porting scenes with tiles + + QGraphicsScene does not provide an API for tiles. However, you + can achieve similar behavior by drawing pixmaps in a reimplementation of + QGraphicsScene::drawBackground(). + + Q3Canvas' tile support is based on providing one pixmap + containing tiles of a fixed width and height, and then + accessing them (reading and replacing tiles) by index. The + tiles in the pixmap are arranged from the left to right, top + to bottom. + + \table + \row \i 0 \i 1 \i 2 \i 3 + \row \i 4 \i 5 \i 6 \i 7 + \endtable + + With Graphics View, this pixmap can be stored as a member of a + subclass of QGraphicsScene. The three main functions that make + out the public tile API can then be declared as new members of + this class. Here is one example of how to implement tile support: + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 1 + + Depending on how your scene uses tiles, you may be able to + simplify this approach. In this example, we will try to mimic the behavior + of the Q3Canvas functions. + + We start by creating a subclass of QGraphicsScene ("TileScene"). + In this class, we declare two of the tile + functions from Q3Canvas, and we then add two helper function that returns the + rectangle for a certain tile in our tile pixmap. We will use a + two-dimensional vector of ints to keep track of what tiles should + be used at what parts of the scene. + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 2 + + In setTiles(), we store the pixmap and tile properties as + members of the class. Then we resize the tiles vector + to match the width and height of our tile grid. + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 3 + + The setTile() function updates the tiles index, and then + updates the corresponding rect in the scene by calling + tileRect(). + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 4 + + The first tileRect() function returns a QRect for the tile at + position (x, y). + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 5 + + The second tileRect() function returns a QRect for a tile number. + With these functions in place, we can implement the drawBackground() + function. + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 6 + + In drawBackground(), we redraw all tiles that have been + exposed by intersecting each tile rect with the exposed background + area. + + \section1 Porting from Q3CanvasView + + The closest equivalent to Q3CanvasView in Graphics View is + called QGraphicsView. In most cases, this is the easiest + class to port. In addition to providing all of Q3CanvasView's + functionality, QGraphicsView includes some useful new features. You + can read more about this in QGraphicsView's documentation. + + \section2 Porting table + + \table + \header \o Q3CanvasView \o QGraphicsView + + \row \o Q3CanvasView::Q3CanvasView() \o QGraphicsView provides + the same constructors as Q3CanvasView, but without the name + and flags arguments. You can set the name by calling + \l{QWidget::setObjectName()}{setObjectName()}, and the flags by + calling \l{QWidget::setWindowFlags()}{setWindowFlags()}. + + \row \o Q3CanvasView::canvas() \o QGraphicsView::scene() + returns the scene that is currently associated with the + view. QGraphicsScene also provides the opposite function, + QGraphicsScene::views(), which returns a list of views + observing the scene. + + \row \o Q3CanvasView::inverseWorldMatrix() \o You can call + QGraphicsView::matrix() and QMatrix::inverted(). + QGraphicsView::mapToScene() and QGraphicsView::mapFromScene() + allow transforming of viewport shapes to scene shapes, and + vice versa. + + \row \o Q3CanvasView::setCanvas() \o QGraphicsView::setScene(). + + \row \o Q3CanvasView::setWorldMatrix() \o + QGraphicsView::setMatrix(), QGraphicsView::rotate(), + QGraphicsView::scale(), QGraphicsView::shear() and + QGraphicsView::translate(). + + \row \o Q3CanvasView::worldMatrix() \o QGraphicsView::matrix() + + \row \o Q3CanvasView::drawContents() \o The + QGraphicsView::drawBackground() function draws the background, + QGraphicsView::drawItems() draws the items, and + QGraphicsView::drawForeground() draws the foreground of the + scene in scene coordinates. You can also reimplement these + functions in QGraphicsScene. + + \endtable + + \section2 Other differences + + QGraphicsView can cache the visible contents of the scene, + similar to how Q3Canvas::setDoubleBuffering() could cache the + entire scene contents. You can call + QGraphicsView::setCacheMode() to configure cacheing, and + QGraphicsView::resetCachedContent() invalidates the cache. + + For improved navigation support, you can set a resize or + transformation anchor through QGraphicsView::resizeAnchor and + QGraphicsView::transformationAnchor. This allows you to easily + rotate and zoom the view while keeping the center fixed, or + zooming towards the position under the mouse cursor. In + addition, if you set the QGraphicsView::dragMode of the view, + QGraphicsView will provide rubber band selection or + click-and-pull navigation using the + \l{Qt::OpenHandCursor}{OpenHandCursor} and + \l{Qt::ClosedHandCursor}{ClosedHandCursor} cursors. + + \section1 Porting from Q3CanvasItem + + The closest equivalent to Q3CanvasItem in Graphics View is + called QGraphicsItem. Deriving from this class is very common, + and because of that, porting from Q3CanvasItem often involves + more work than Q3Canvas and Q3CanvasView. + + Q3CanvasItem has become easier to use, easier to subclass, and more + powerful with QGraphicsItem. The key difference from Q3CanvasItem lies + in event propagation and item groups, but you will also find several + convenient new features, such as support for tooltips, cursors, item + transformation and drag and drop. You can read all about QGraphicsItem + in its own class documentation. + + This section starts with a table that shows how to port each function + from Q3CanvasItem to QGraphicsItem. Immediately after that, each of + Q3CanvasItem's standard subclasses have a section of their own. + + \table + \header \o Q3CanvasItem \o QGraphicsItem + + \row \o Q3CanvasItem::advance() \o QGraphicsItem::advance() is + provided for compatibility. QGraphicsScene::advance() calls + QGraphicsItem::advance() for all items. See also QTimeLine and + QGraphicsItemAnimation. + + \row \o Q3CanvasItem::animated() \o No equivalent; all items + are advanced by QGraphicsScene::advance(). + + \row \o Q3CanvasItem::boundingRectAdvanced() \o No + equivalent. You can translate QGraphicsItem::boundingRect() + instead (see QRectF::translate()). + + \row \o Q3CanvasItem::canvas() \o QGraphicsItem::scene() + + \row \o Q3CanvasItem::collidesWith() \o + QGraphicsItem::collidesWithItem() and + QGraphicsItem::collidesWithPath(). + + \row \o Q3CanvasItem::collisions() \o + QGraphicsItem::collidingItems() returns a list of all items + that collide with an item. You can specify whether you want + fast, rough estimate collision between bounding rectangles, or + the slower, more accurate shapes. + + \row \o Q3CanvasItem::draw() \o QGraphicsItem::paint(). See + also QStyleOptionGraphicsItem, QGraphicsScene::drawItems() and + QGraphicsView::drawItems(). + + \row \o Q3CanvasItem::hide() \o QGraphicsItem::hide() or + QGraphicsItem::setVisible(). \l{QGraphicsItem}s are \e visible by + default; \l{Q3CanvasItem}s, however, are not. + + \row \o Q3CanvasItem::isActive() \o No equivalent. To achieve + similar behavior, you can add this property in a custom + subclass of QGraphicsItem. + + \row \o Q3CanvasItem::isVisible() \o + QGraphicsItem::isVisible(). \l{QGraphicsItem}s are \e visible by + default; \l{Q3CanvasItem}s, however, are not. + + \row \o Q3CanvasItem::move() \o You can call + QGraphicsItem::setPos() to change the position of the item. + + \row \o Q3CanvasItem::rtti() \o QGraphicsItem::type() and qgraphicsitem_cast(). + + \row \o Q3CanvasItem::setActive() \o No equivalent. + + \row \o Q3CanvasItem::setAnimated() \o No equivalent; all + items are by default "animated" (i.e., + QGraphicsScene::advance() advances all items on the scene). + + \row \o Q3CanvasItem::setCanvas() \o You can call + QGraphicsScene::addItem(), or pass a pointer to the canvas to + QGraphicsItem's constructor. + + \row \o Q3CanvasItem::setVelocity() \o No equivalent. You can + add x and y velocity as member data of your class, and call + QGraphicsItem::moveBy(x, y) from inside + QGraphicsItem::advance(). See also QTimeLine and + QGraphicsItemAnimation. + + \row \o Q3CanvasItem::setVisible() \o + QGraphicsItem::setVisible(). \l{QGraphicsItem}s are \e visible by + default; \l{Q3CanvasItem}s, however, are not. + + \row \o Q3CanvasItem::setX() \o QGraphicsItem::setPos() + \row \o Q3CanvasItem::setY() \o QGraphicsItem::setPos() + + \row \o Q3CanvasItem::setXVelocity() \o No equivalent. + \row \o Q3CanvasItem::setYVelocity() \o No equivalent. + + \row \o Q3CanvasItem::setZ() \o QGraphicsItem::setZValue() + + \row \o Q3CanvasItem::show() \o QGraphicsItem::show() or + QGraphicsItem::setVisible(). \l{QGraphicsItem}s are \e visible by + default; \l{Q3CanvasItem}s, however, are not. + + \row \o Q3CanvasItem::xVelocity() \o No equivalent. + \row \o Q3CanvasItem::yVelocity() \o No equivalent. + + \endtable + + Note that some virtual functions that have passed on to + QGraphicsItem have lost their virtuality. An example is + Q3CanvasItem::moveBy(), which was often used to track movement of + items. In this case, the virtual QGraphicsItem::itemChange() has + taken over as a substitute. + + \section2 Q3CanvasPolygonalItem + + The closest equivalent to Q3CanvasPolygonalItem in + Graphics View is called QAbstractGraphicsShapeItem. Unlike + Q3CanvasPolygonalItem, it does not define area points + (Q3CanvasPolygonalItem::areaPoints()); instead, each + item's geometry is stored as a member of the subclasses. + + The Q3CanvasPolygonalItem::drawShape() function is no longer + available; instead, you can set the brush and pen from inside + QGraphicsItem::paint(). + + \table + \header \o Q3CanvasPolygonalItem \o QAbstractGraphicsShapeItem + + \row \o Q3CanvasPolygonalItem::areaPoints() \o No equivalent; each + item's geometry is stored in the respective subclass. + + \row \o Q3CanvasPolygonalItem::areaPointsAdvanced() \o No + equivalent; you can use QPolygonF::translate() or + QPainterPath::translate() instead. + + \row \o Q3CanvasPolygonalItem::drawShape() \o + QGraphicsItem::paint(). You can set the pen and brush from inside + this function. + + \row \o Q3CanvasPolygonalItem::invalidate() \o Call + QGraphicsItem::prepareGeometryChange() before changing the + item's geometry. + + \row \o Q3CanvasPolygonalItem::isValid() \o No equivalent; + items' geometry is always in a valid state. + + \row \o Q3CanvasPolygonalItem::winding() \o This function is only + useful for polygon items and path items; see + QGraphicsPolygonItem::fillRule(), and QPainterPath::fillRule() for + QGraphicsPathItem. + + \endtable + + \section2 Q3CanvasEllipse + + The closest equivalent to Q3CanvasEllipse in Graphics View + is called QGraphicsEllipseItem. The most noticable + difference to QGraphicsEllipseItem is that the ellipse is + not longer drawn centered around its position; rather, it + is drawn using a bounding QRectF, just like + QPainter::drawEllipse(). + + For compatibility, you may want to shift the ellipse up and to the + left to keep the ellipse centered. Example: + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 7 + + Note: QGraphicsEllipseItem uses QAbstractGraphicsShapeItem::pen() + for outlines, whereas Q3CanvasEllipse did not use + Q3CanvasPolygonalItem::pen(). + + \table + \header \o Q3CanvasEllipse \o QGraphicsEllipseItem + + \row \o Q3CanvasEllipse::angleLength() \o QGraphicsEllipseItem::spanAngle() + + \row \o Q3CanvasEllipse::angleStart() \o QGraphicsEllipseItem::startAngle() + + \row \o Q3CanvasEllipse::setAngles() \o + QGraphicsEllipseItem::setStartAngle() and + QGraphicsEllipseItem::setSpanAngle() + + \row \o Q3CanvasEllipse::setSize() \o QGraphicsEllipseItem::setRect() + + \endtable + + \section2 Q3CanvasLine + + The closest equivalent to Q3CanvasLine in Graphics View is + called QGraphicsLineItem. + + \table + \header \o Q3CanvasLine \o QGraphicsLineItem + + \row \o Q3CanvasLine::endPoint() \o QGraphicsLineItem::line() and QLineF::p2() + + \row \o Q3CanvasLine::setPoints() \o QGraphicsLineItem::setLine() + + \row \o Q3CanvasLine::startPoint() \o QGraphicsLineItem::line() + and QLineF::p1() + + \endtable + + \section2 Q3CanvasPolygon + + The closest equivalent to Q3CanvasPolygon in Graphics View + is called QGraphicsPolygonItem. + + \table + \header \o Q3CanvasPolygon \o QGraphicsPolygonItem + + \row \o Q3CanvasPolygon::areaPoints() \o + QGraphicsPolygonItem::polygon() and QGraphicsItem::mapToParent() + + \row \o Q3CanvasPolygon::points() \o QGraphicsPolygonItem::polygon() + + \row \o Q3CanvasPolygon::setPoints() \o QGraphicsPolygonItem::setPolygon() + + \endtable + + \section2 Q3CanvasSpline + + The closest equivalent to Q3CanvasSpline in Graphics View + is called QGraphicsPathItem. This item can be used to + describe any type of path supported by QPainter. + + Q3CanvasSpline takes its control points as a Q3PointArray, but + QPainterPath operates on a sequence of calls to + QPainterPath::moveTo() and QPainterPath::cubicTo(). Here is how + you can convert a bezier curve Q3PointArray to a QPainterPath: + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 8 + + Note: QGraphicsPathItem uses QAbstractGraphicsShapeItem::pen() for + outlines, whereas Q3CanvasSpline did not use + Q3CanvasPolygonalItem::pen(). + + \table + \header \o Q3CanvasSpline \o QGraphicsPathItem + + \row \o Q3CanvasSpline::closed() \o No equivalent. You can call + QPainterPath::closeSubPath() to close a subpath explicitly. + + \endtable + + \section2 Q3CanvasRectangle + + The closest equivalent to Q3CanvasRectangle in Graphics + View is called QGraphicsRectItem. + + \table + \header \o Q3CanvasRectangle \o QGraphicsRectItem + + \row \o Q3CanvasRectangle::height() \o QGraphicsRectItem::rect() + and QRectF::height() + + \row \o Q3CanvasRectangle::setSize() \o QGraphicsRectItem::setRect() + + \row \o Q3CanvasRectangle::size() \o QGraphicsRectItem::rect() and QRectF::size() + + \row \o Q3CanvasRectangle::width() \o QGraphicsRectItem::rect() and QRectF::width() + + \row \o Q3CanvasRectangle::chunks() \o No equivalent. + + \endtable + + \section2 Q3CanvasSprite + + Q3CanvasSprite is the item class that differs the most from its + Q3Canvas predecessor. The closest resemblance of Q3CanvasSprite in + Graphics View is QGraphicsPixmapItem. + + Q3CanvasSprite supports animated pixmaps; QGraphicsPixmapItem, + however, is a simple single-frame pixmap item. If all you need is + a pixmap item, porting is straight-forward. If you do need the + animation support, extra work is required; there is no direct + porting approach. + + For the \l{Ported Asteroids Example}, a subclass of + QGraphicsPixmapItem is used to replace Q3CanvasSprite, storing a + list of pixmaps and a frame counter. The animation is advanced in + QGraphicsItem::advance(). + + \section3 Q3CanvasPixmap, Q3CanvasPixmapArray + + These classes have been removed from the API. You can use + QPixmap instead of Q3CanvasPixmap, and QList instead of + Q3CanvasPixmapArray. + + Q3CanvasPixmapArray included convenience for loading a + sequence of pixmaps or masks using a path with a wildcard (see + Q3CanvasPixmapArray::readPixmaps() and + Q3CanvasPixmapArray::readCollisionMasks()). To achieve similar + functionality using Graphics View, you can load the images by + using QDir: + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 9 + + \section2 Q3CanvasText + + Q3CanvasText has been split into two classes in Graphics View: + QGraphicsSimpleTextItem and QGraphicsTextItem. For porting, + QGraphicsSimpleTextItem should be adequate. QGraphicsTextItem + provides advanced document structuring features similar to that of + QTextEdit, and it also allows interaction (e.g., editing and + selection). + + \table + \header \o Q3CanvasText \o QGraphicsSimpleTextItem + + \row \o Q3CanvasText::color() \o QGraphicsSimpleTextItem::pen(). + + \row \o Q3CanvasText::setColor() \o QGraphicsSimpleTextItem::setPen(). + + \row \o Q3CanvasText::textFlags() \o Use QGraphicsTextItem instead. + + \endtable + + + \section2 Q3CanvasItemList + + Use QList instead. + + \section1 Other Resources + + The \l{Porting to Qt 4.2's Graphics View} article in Qt Quarterly 21 covered the + process of porting the Qt 3 canvas example to Qt 4. + The result of this is the \l{Ported Canvas Example}{Ported Canvas} example. +*/ diff --git a/doc/src/porting/porting4-designer.qdoc b/doc/src/porting/porting4-designer.qdoc new file mode 100644 index 0000000..d356392 --- /dev/null +++ b/doc/src/porting/porting4-designer.qdoc @@ -0,0 +1,349 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page porting4-designer.html + \title Porting UI Files to Qt 4 + \contentspage {Porting Guides}{Contents} + \previouspage Porting to Qt 4 - Drag and Drop + \nextpage Porting to Graphics View + \ingroup porting + \brief Information about changes to the UI file format in Qt 4. + + Qt Designer has changed significantly in the Qt 4 release. We + have moved away from viewing Qt Designer as an IDE and + concentrated on creating a robust form builder which can be + extended and embedded in existing IDEs. Our efforts are ongoing + and include the \l{Visual Studio Integration}, + as well as integrating Designer with KDevelop and possibly other + IDEs. + + The most important changes in Qt Designer 4 which affect porting + for UI files are summarized below: + + \list + \o \bold{Removed project manager.} + Qt Designer now only reads and edits UI + files. It has no notion of a project file (\c .pro). + + \o \bold{Removed code editor.} + Qt Designer can no longer be used to edit source files. + + \o \bold{Changed format of UI files.} + Qt Designer 4 cannot read files created by Qt Designer 3 and + vice versa. However, we provide the tool \c uic3 to generate Qt + 4 code out of Qt 3 UI files, and to convert old UI files + into a format readable by Qt Designer 4. + + \o \bold{Changed structure of the code generated by \c uic.} + The \c myform.ui file containing the form \c MyForm is now + converted into a single header file \c ui_myform.h, which + contains the declaration and inline definition of a POD class + \c Ui::MyForm. + + \o \bold{New resource file system.} Icon data is no longer + stored in the UI file. Instead, icons are put into resource + files (\c .qrc). + \endlist + + The rest of this document explains how to deal with the main + differences between Qt Designer 3 and Qt Designer 4: + + \tableofcontents + + See \l{Porting to Qt 4} and \l{qt3to4 - The Qt 3 to 4 Porting + Tool} for more information about porting from Qt 3 to Qt 4. See + also the \l{Qt Designer Manual}. + + \section1 uic Output + + In Qt 3, \c uic generated a header file and an implementation for + a class, which inherited from one of Qt's widgets. To use the + form, the programmer included the generated sources into the + application and created an instance of the class. + + In Qt 4, \c uic creates a header file containing a POD class. The + name of this class is the object name of the main container, + qualified with the \c Ui namespace (e.g., \c Ui::MyForm). The + class is implemented using inline functions, removing the need of + a separate \c .cpp file. Just as in Qt 3, this class contains + pointers to all the widgets inside the form as public members. In + addition, the generated class provides the public method \c + setupUi(). + + The class generated by \c uic is not a QWidget; in fact, it's not + even a QObject. Instead, it is a class which knows how to + populate an instance of a main container with the contents of the + form. The programmer creates the main container himself, then + passes it to \c setupUi(). + + For example, here's the \c uic output for a simple \c + helloworld.ui form (some details were removed for simplicity): + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 0 + + In this case, the main container was specified to be a QWidget + (or any subclass of QWidget). Had we started with a QMainWindow + template in Qt Designer, \c setupUi()'s parameter would be of + type QMainWindow. + + There are two ways to create an instance of our form. One + approach is to create an instance of the \c Ui::HelloWorld class, + an instance of the main container (a plain QWidget), and call \c + setupUi(): + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 1 + + The second approach is to inherit from both the \c Ui::HelloWorld + class and the main container, and to call \c setupUi() in the + constructor of the subclass. In that case, QWidget (or one of + its subclasses, e.g. QDialog) must appear first in the base class + list so that \l{moc} picks it up correctly. For example: + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 2 + + This second method is useful when porting Qt 3 forms to Qt 4. \c + HelloWorldWidget is a class whose instance is the actual form + and which contains public pointers to all the widgets in it. It + therefore has an interface identical to that of a class generated + by \c uic in Qt 3. + + Creating POD classes from UI files is more flexible and + generic than the old approach of creating widgets. Qt Designer + does not need to know anything about the main container apart from + the base widget class it inherits. Indeed, \c Ui::HelloWorld can + be used to populate any container that inherits QWidget. + Conversely, all non-GUI aspects of the main container may be + implemented by the programmer in the application's sources + without reference to the form. + + \section1 Working with uic3 + + Qt 4 comes with the tool \c uic3 for working with old \c .ui + files. It can be used in two ways: + + \list 1 + \o To generate headers and source code for a widget to implement any + custom signals and slots added using Qt Designer 3. + \o To generate a new UI file that can be used with Qt Designer 4. + \endlist + + You can use both these methods in combination to obtain UI, header + and source files that you can use as a starting point when porting + your user interface to Qt 4. + + The first method generates a Qt 3 style header and implementation + which uses Qt 4 widgets (this includes the Qt 3 compatibility classes + present in the Qt3Support library). This process should be familiar to + anyone used to working with Qt Designer 3: + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 3 + + The resulting files \c myform.h and \c myform.cpp implement the + form in Qt 4 using a QWidget that will include custom signals, + slots and connections specified in the UI file. However, + see below for the \l{#Limitations of uic3}{limitations} of this + method. + + The second method is to use \c uic3 to convert a Qt Designer 3 \c .ui + file to the Qt Designer 4 format: + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 4 + + The resulting file \c myform4.ui can be edited in Qt Designer 4. The + header file for the form is generated by Qt 4's \c uic. See the + \l{Using a Designer UI File in Your Application} chapter of the + \l{Qt Designer Manual} for information about the preferred ways to + use forms created with Qt Designer 4. + + \c uic3 tries very hard to map Qt 3 classes and their properties to + Qt 4. However, the behavior of some classes changed significantly + in Qt 4. To keep the form working, some Qt 3 classes are mapped + to classes in the Qt3Support library. Table 1 shows a list of + classes this applies to. + + \table + \header \o Qt 3 class \o Qt 4 class + \row \o \c QButtonGroup \o Q3ButtonGroup + \row \o \c QDateEdit \o Q3DateEdit + \row \o \c QDateTimeEdit \o Q3DateTimeEdit + \row \o \c QGroupBox \o Q3GroupBox + \row \o \c QListBox \o Q3ListBox + \row \o \c QListView \o Q3ListView + \row \o \c QMainWindow \o Q3MainWindow + \row \o \c QTextEdit \o Q3TextEdit + \row \o \c QTextView \o Q3TextView + \row \o \c QTimeEdit \o Q3TimeEdit + \row \o \c QWidgetStack \o Q3WidgetStack + \row \o \c QWizard \o Q3Wizard + \endtable + + \section1 Limitations of uic3 + + Converting Qt 3 UI files to Qt 4 has some limitations. The + most noticeable limitation is the fact that since \c uic no + longer generates a QObject, it's not possible to define custom + signals or slots for the form. Instead, the programmer must + define these signals and slots in the main container and connect + them to the widgets in the form after calling \c setupUi(). For + example: + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 5 + + A quick and dirty way to port forms containing custom signals and + slots is to generate the code using \c uic3, rather than \c uic. Since + \c uic3 does generate a QWidget, it will populate it with custom + signals, slots and connections specified in the UI file. + However, \c uic3 can only generate code from Qt 3 UI files, which + implies that the UI files never get translated and need to be + edited using Qt Designer 3. + + Note also that it is possible to create implicit connections + between the widgets in a form and the main container. After \c + setupUi() populates the main container with child widgets it + scans the main container's list of slots for names with the form + \tt{on_\e{objectName}_\e{signalName}().} + + If the form contains a widget whose object name is + \tt{\e{objectName}}, and if that widget has a signal called + \tt{\e{signalName}}, then this signal will be connected to the + main container's slot. For example: + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 6 + + Because of the naming convention, \c setupUi() automatically + connects \c pushButton's \c clicked() signal to \c + HelloWorldWidget's \c on_pushButton_clicked() slot. + + \section1 Icons + + In Qt 3, the binary data for the icons used by a form was stored + in the UI file. In Qt 4 icons and any other external files + can be compiled into the application by listing them in a \l{The + Qt Resource System}{resource file} (\c .qrc). This file is + translated into a C++ source file using Qt's resource compiler + (\c rcc). The data in the files is then available to any Qt class + which takes a file name argument. + + Imagine that we have two icons, \c yes.png and \c no.png. We + create a resource file called \c icons.qrc with the following + contents: + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 7 + + Next, we add the resource file to our \c .pro file: + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 8 + + When \c qmake is run, it will create the appropriate Makefile + rules to call \c rcc on the resource file, and compile and link + the result into the application. The icons may be accessed as + follows: + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 9 + + In each case, the leading colon tells Qt to look for the file in + the virtual file tree defined by the set of resource files + compiled into the application instead of the file system. + + In the \c .qrc file, the \c qresource tag's \c prefix attribute + is used to arrange the files into categories and set a virtual + path where the files will be accessed. + + Caveat: If the resource file was not linked directly into the + application, but instead into a dynamic or static library that + was later linked with the application, its virtual file tree will + not be available to QFile and friends until the Q_INIT_RESOURCE() + macro is called. This macro takes one argument, which is the name + of the \c .qrc file, without the path or the file extension. A + convenient place to initialize resources is at the top of the + application's \c main() function. + + In Qt Designer 4, we can associate any number of resource files + with a form using the resource editor tool. The widgets in the + form can access all icons specified in its associated resource + files. + + In short, porting of icons from a Qt 3 to a Qt 4 form involves + the following steps: + + \list 1 + \o Use \c{uic3 -convert} to obtain a UI file understood by + Qt Designer 4. + + \o Create a \c .qrc file with a list of all the icon files. + + \o Add the resource file to the \c .pro file. + + \o Open the form in Qt Designer 4 and add the resource file to the + form's resource editor. + + \o Set the icon properties for the appropriate widgets. + \endlist + + \section1 Custom Widgets + + Qt Designer 3 supported defining custom widgets by specifying + their name, header file and methods. In Qt Designer 4, a custom + widget is always created by "promoting" an existing Qt widget to + a custom class. Qt Designer 4 assumes that the custom widget will + inherit from the widget that has been promoted. In the form + editor, the custom widget will retain the looks, behavior, + properties, signals and slots of the base widget. It is not + currently possible to tell Qt Designer 4 that the custom widget + will have additional signals or slots. + + \c{uic3 -convert} handles the conversion of custom widgets to the + new \c .ui format, however all custom signals and slots are lost. + Furthermore, since Qt Designer 3 never knew the base widget class + of a custom widget, it is taken to be QWidget. This is often + sufficient. If not, the custom widgets have to be inserted + manually into the form. + + Custom widget plugins, which contain custom widgets to be used in + Qt Designer, must themselves be ported before they can be used in + forms ported with \c{uic3}. + The \l{Porting to Qt 4} document contains information about general + porting issues that may apply to the custom widget code itself, and + the \l{Creating Custom Widgets for Qt Designer} chapter of the + \l{Qt Designer Manual} describes how the ported widget should be + built in order to work in Qt Designer 4. +*/ diff --git a/doc/src/porting/porting4-dnd.qdoc b/doc/src/porting/porting4-dnd.qdoc new file mode 100644 index 0000000..2eb2d01 --- /dev/null +++ b/doc/src/porting/porting4-dnd.qdoc @@ -0,0 +1,152 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page porting4-dnd.html + \title Porting to Qt 4 - Drag and Drop + \contentspage {Porting Guides}{Contents} + \previouspage Porting to Qt 4 - Virtual Functions + \nextpage Porting UI Files to Qt 4 + \ingroup porting + \brief An overview of the porting process for applications that use drag and drop. + + Qt 4 introduces a new set of classes to handle drag and drop operations + that aim to be easier to use than their counterparts in Qt 3. As a result, + the way that drag and drop is performed is quite different to the way + developers of Qt 3 applications have come to expect. In this guide, we + show the differences between the old and new APIs and indicate where + applications need to be changed when they are ported to Qt 4. + + \tableofcontents + + \section1 Dragging + + In Qt 3, drag operations are encapsulated by \c QDragObject (see Q3DragObject) + and its subclasses. These objects are typically constructed on the heap in + response to mouse click or mouse move events, and ownership of them is + transferred to Qt so that they can be deleted when the corresponding drag and + drop operations have been completed. The drag source has no control over how + the drag and drop operation is performed once the object's + \l{Q3DragObject::}{drag()} function is called, and it receives no information + about how the operation ended. + + \snippet doc/src/snippets/code/doc_src_dnd.qdoc 0 + + Similarly, in Qt 4, drag operations are also initiated when a QDrag object + is constructed and its \l{QDrag::}{exec()} function is called. In contrast, + these objects are typically constructed on the stack rather than the heap + since each drag and drop operation is performed synchronously as far as the + drag source is concerned. One key benefit of this is that the drag source + can receive information about how the operation ended from the value returned + by \l{QDrag::}{exec()}. + + \snippet doc/src/snippets/porting4-dropevents/window.cpp 2 + \snippet doc/src/snippets/porting4-dropevents/window.cpp 3 + \dots 8 + \snippet doc/src/snippets/porting4-dropevents/window.cpp 4 + \snippet doc/src/snippets/porting4-dropevents/window.cpp 5 + + A key difference in the above code is the use of the QMimeData class to hold + information about the data that is transferred. Qt 3 relies on subclasses + of \c QDragObject to provide support for specific MIME types; in Qt 4, the + use of QMimeData as a generic container for data makes the relationship + between MIME type and data more tranparent. QMimeData is described in more + detail later in this document. + + \section1 Dropping + + In both Qt 3 and Qt 4, it is possible to prepare a custom widget to accept + dropped data by enabling the \l{QWidget::}{acceptDrops} property of a widget, + usually in the widget's constructor. As a result, the widget will receive + drag enter events that can be handled by its \l{QWidget::}{dragEnterEvent()} + function. + As in Qt 3, custom widgets in Qt 4 handle these events by determining + whether the data supplied by the drag and drop operation can be dropped onto + the widget. Since the classes used to encapsulate MIME data are different in + Qt 3 and Qt 4, the exact implementations differ. + + In Qt 3, the drag enter event is handled by checking whether each of the + standard \c QDragObject subclasses can decode the data supplied, and + indicating success or failure of these checks via the event's + \l{QDragEnterEvent::}{accept()} function, as shown in this simple example: + + \snippet doc/src/snippets/code/doc_src_dnd.qdoc 1 + + In Qt 4, you can examine the MIME type describing the data to determine + whether the widget should accept the event or, for common data types, you + can use convenience functions: + + \snippet doc/src/snippets/porting4-dropevents/window.cpp 0 + + The widget has some control over the type of drag and drop operation to be + performed. In the above code, the action proposed by the drag source is + accepted, but + \l{Drag and Drop#Overriding Proposed Actions}{this can be overridden} if + required. + + In both Qt 3 and Qt 4, it is necessary to accept a given drag event in order + to receive the corresponding drop event. A custom widget in Qt 3 that can + accept dropped data in the form of text or images might provide an + implementation of \l{QWidget::}{dropEvent()} that looks like the following: + + \snippet doc/src/snippets/code/doc_src_dnd.qdoc 2 + + In Qt 4, the event is handled in a similar way: + + \snippet doc/src/snippets/porting4-dropevents/window.cpp 1 + + It is also possible to extract data stored for a particular MIME type if it + was specified by the drag source. + + \section1 MIME Types and Data + + In Qt 3, data to be transferred in drag and drop operations is encapsulated + in instances of \c QDragObject and its subclasses, representing specific + data formats related to common MIME type and subtypes. + + In Qt 4, only the QMimeData class is used to represent data, providing a + container for data stored in multiple formats, each associated with + a relevant MIME type. Since arbitrary MIME types can be specified, there is + no need for an extensive class hierarchy to represent different kinds of + information. Additionally, QMimeData it provides some convenience functions + to allow the most common data formats to be stored and retrieved with less + effort than for arbitrary MIME types. +*/ diff --git a/doc/src/porting/porting4-modifiedvirtual.qdocinc b/doc/src/porting/porting4-modifiedvirtual.qdocinc new file mode 100644 index 0000000..1164238 --- /dev/null +++ b/doc/src/porting/porting4-modifiedvirtual.qdocinc @@ -0,0 +1,63 @@ +\row \o int QAccessibleInterface::navigate(NavDirection, int) const \o int QAccessibleInterface::navigate(RelationFlag, int, QAccessibleInterface **) const +\row \o bool QApplication::winEventFilter(MSG *) \o bool QApplication::winEventFilter(MSG *, long *) +\row \o Function: Offset QIODevice::at() const \o Function: Q_LONGLONG QIODevice::pos() const +\row \o bool QIODevice::at(Offset) \o bool QIODevice::seek(Q_LONGLONG) +\row \o bool QIODevice::open(int) \o bool QIODevice::open(OpenMode) +\row \o Q_LONG QIODevice::readBlock(char *, Q_ULONG) \o Q_LONGLONG QIODevice::readData(char *, Q_LONGLONG) +\row \o Q_LONG QIODevice::writeBlock(const char *, Q_ULONG) \o Q_LONGLONG QIODevice::writeData(const char *, Q_LONGLONG) +\row \o const char * QImageFormatType::formatName() const \o QByteArray QImageFormatType::formatName() const +\row \o QPopupMenu * QLineEdit::createPopupMenu() \o QMenu * QLineEdit::createPopupMenu() +\row \o bool QMacMime::canConvert(const char *, int) \o bool QMacMime::canConvert(const QString &, int) +\row \o QValueList<QByteArray> QMacMime::convertFromMime(QByteArray, const char *, int) \o QList<QByteArray> QMacMime::convertFromMime(QByteArray, const QString &, int) +\row \o QByteArray QMacMime::convertToMime(QValueList<QByteArray> data, const char *, int) \o QByteArray QMacMime::convertToMime(QList<QByteArray> data, const QString &, int) +\row \o const char * QMacMime::convertorName() \o QString QMacMime::convertorName() +\row \o int QMacMime::flavorFor(const char *) \o int QMacMime::flavorFor(const QString &) +\row \o const char * QMacMime::mimeFor(int) \o QString QMacMime::mimeFor(int) +\row \o QMetaObject * QObject::metaObject() const \o const QMetaObject * QObject::metaObject() const +\row \o bool QScreen::onCard(unsigned char *) const \o bool QScreen::onCard(const unsigned char *) const +\row \o bool QScreen::onCard(unsigned char *, ulong &) const \o bool QScreen::onCard(const unsigned char *, ulong &) const +\row \o int QSpinBox::mapTextToValue(bool *) \o int QSpinBox::mapTextToValue(QString *, QValidator::State *) const +\row \o QString QSpinBox::mapValueToText(int) \o QString QSpinBox::mapValueToText(int) const +\row \o bool QSqlDriver::open(const QString &, const QString &, const QString &, const QString &, int) \o bool QSqlDriver::open(const QString &, const QString &, const QString &, const QString &, int, const QString &) +\row \o QStringList QSqlDriver::tables(const QString &) const \o QStringList QSqlDriver::tables(QSql::TableType) const +\row \o bool QSqlQuery::prev() \o bool QSqlQuery::previous() +\row \o bool QSqlResult::fetchPrev() \o bool QSqlResult::fetchPrevious() +\row \o void QStyle::drawComplexControl(ComplexControl, QPainter *, const QWidget *, const QRect &, const QColorGroup &, SFlags, SCFlags, SCFlags, const QStyleOption &) const \o void QStyle::drawComplexControl(ComplexControl, const QStyleOptionComplex *, QPainter *, const QWidget *) const +\row \o void QStyle::drawComplexControlMask(ComplexControl, QPainter *, const QWidget *, const QRect &, const QStyleOption &) const \o void QStyle::drawComplexControlMask(ComplexControl, const QStyleOptionComplex *, QPainter *, const QWidget *) const +\row \o void QStyle::drawControl(ControlElement, QPainter *, const QWidget *, const QRect &, const QColorGroup &, SFlags, const QStyleOption &) const \o void QStyle::drawControl(ControlElement, const QStyleOption *, QPainter *, const QWidget *) const +\row \o void QStyle::drawControlMask(ControlElement, QPainter *, const QWidget *, const QRect &, const QStyleOption &) const \o void QStyle::drawControlMask(ControlElement, const QStyleOption *, QPainter *, const QWidget *) const +\row \o void QStyle::drawItem(QPainter *, const QRect &, int, const QColorGroup &, bool, const QPixmap *, const QString &, int, const QColor *) const \o void QStyle::drawItem(QPainter *, const QRect &, int, const QPalette &, bool, const QString &, int, const QColor *) const +\row \o void QStyle::drawPrimitive(PrimitiveElement, QPainter *, const QRect &, const QColorGroup &, SFlags, const QStyleOption &) const \o void QStyle::drawPrimitive(PrimitiveElement, const QStyleOption *, QPainter *, const QWidget *) const +\row \o QRect QStyle::itemRect(QPainter *, const QRect &, int, bool, const QPixmap *, const QString &, int) const \o QRect QStyle::itemTextRect(const QFontMetrics &, const QRect &, int, bool, const QString &, int) const +\row \o int QStyle::pixelMetric(PixelMetric, const QWidget *) const \o int QStyle::pixelMetric(PixelMetric, const QStyleOption *, const QWidget *) const +\row \o SubControl QStyle::querySubControl(ComplexControl, const QWidget *, const QPoint &, const QStyleOption &) const \o SubControl QStyle::hitTestComplexControl(ComplexControl, const QStyleOptionComplex *, const QPoint &, const QWidget *) const +\row \o QRect QStyle::querySubControlMetrics(ComplexControl, const QWidget *, SubControl, const QStyleOption &) const \o QRect QStyle::subControlRect(ComplexControl, const QStyleOptionComplex *, SubControl, const QWidget *) const +\row \o QSize QStyle::sizeFromContents(ContentsType, const QWidget *, const QSize &, const QStyleOption &) const \o QSize QStyle::sizeFromContents(ContentsType, const QStyleOption *, const QSize &, const QFontMetrics &, const QWidget *) const +\row \o int QStyle::styleHint(StyleHint, const QWidget *, const QStyleOption &, QStyleHintReturn *) const \o int QStyle::styleHint(StyleHint, const QStyleOption *, const QWidget *, QStyleHintReturn *) const +\row \o QPixmap QStyle::stylePixmap(StylePixmap, const QWidget *, const QStyleOption &) const \o QPixmap QStyle::standardPixmap(StandardPixmap, const QStyleOption *, const QWidget *) const +\row \o QRect QStyle::subRect(SubRect, const QWidget *) const \o QRect QStyle::subRect(SubRect, const QStyleOption *, const QFontMetrics &, const QWidget *) const +\row \o void QStyle::unPolish(QApplication *) \o void QStyle::unpolish(QApplication *) +\row \o void QStyle::unPolish(QWidget *) \o void QStyle::unpolish(QWidget *) +\row \o QCString QTextCodec::fromUnicode(const QString &, int &) const \o QByteArray QTextCodec::fromUnicode(const QString &, int &) const +\row \o QValueList<int> QTextCodecPlugin::mibEnums() const \o QList<int> QTextCodecPlugin::mibEnums() const +\row \o void QTextDrag::setSubtype(const QCString &) \o void QTextDrag::setSubtype(const QString &) +\row \o QCString QTextEncoder::fromUnicode(const QString &, int &) \o QByteArray QTextEncoder::fromUnicode(const QString &, int &) +\row \o void QUriDrag::setUris(QStrList) \o void QUriDrag::setUris(const QList<QByteArray> & list) +\row \o void QUrlInfo::setSize(uint) \o void QUrlInfo::setSize(Q_LONGLONG) +\row \o bool QWindowsMime::canConvert(const char *, int) \o bool QWindowsMime::canConvert(const QString &, int) +\row \o int QWindowsMime::cfFor(const char *) \o int QWindowsMime::cfFor(const QString &) +\row \o QByteArray QWindowsMime::convertFromMime(QByteArray, const char *, int) \o QByteArray QWindowsMime::convertFromMime(const QByteArray &, const QString &, int) +\row \o QByteArray QWindowsMime::convertToMime(QByteArray, const char *, int) \o QByteArray QWindowsMime::convertToMime(const QByteArray &, const QString &, int) +\row \o const char * QWindowsMime::convertorName() \o QString QWindowsMime::convertorName() +\row \o void QWSMouseHandler::calibrate(QWSPointerCalibrationData *) \o void QWSMouseHandler::calibrate(const QWSPointerCalibrationData *) +\row \o bool QWidget::macEvent(MSG *) \o bool QWidget::macEvent(EventHandlerCallRef, EventRef) +\row \o bool QWidget::winEvent(MSG *) \o bool QWidget::winEvent(MSG *, long *) +\row \o QString QXmlContentHandler::errorString() \o QString QXmlContentHandler::errorString() const +\row \o QString QXmlDTDHandler::errorString() \o QString QXmlDTDHandler::errorString() const +\row \o QString QXmlDeclHandler::errorString() \o QString QXmlDeclHandler::errorString() const +\row \o QString QXmlEntityResolver::errorString() \o QString QXmlEntityResolver::errorString() const +\row \o QString QXmlErrorHandler::errorString() \o QString QXmlErrorHandler::errorString() const +\row \o QString QXmlInputSource::data() \o QString QXmlInputSource::data() const +\row \o QString QXmlLexicalHandler::errorString() \o QString QXmlLexicalHandler::errorString() const +\row \o int QXmlLocator::columnNumber() \o int QXmlLocator::columnNumber() const +\row \o int QXmlLocator::lineNumber() \o int QXmlLocator::lineNumber() const diff --git a/doc/src/porting/porting4-obsoletedmechanism.qdocinc b/doc/src/porting/porting4-obsoletedmechanism.qdocinc new file mode 100644 index 0000000..584b910 --- /dev/null +++ b/doc/src/porting/porting4-obsoletedmechanism.qdocinc @@ -0,0 +1,3 @@ +If you use this mechanism in your application, please submit a +report to the \l{Task Tracker} on the Qt website and we will +try to find a satisfactory substitute. diff --git a/doc/src/porting/porting4-overview.qdoc b/doc/src/porting/porting4-overview.qdoc new file mode 100644 index 0000000..5eff1ba --- /dev/null +++ b/doc/src/porting/porting4-overview.qdoc @@ -0,0 +1,373 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page porting4-overview.html + \title Moving from Qt 3 to Qt 4 + \ingroup porting + \brief Porting advice for authors of new and existing Qt 3 applications. + + This document describes which parts of Qt should be used when + writing an application with Qt 3, so that it can be upgraded to + use Qt 4 later with a minimum of effort. However, the advice may + also be useful to developers who are porting existing applications + from Qt 3 to Qt 4. + + For a detailed overview + of the porting process for existing Qt 3 applications, see the + \l{Porting to Qt 4} document. + + \tableofcontents + + Since Qt 4 provides important new functionality at the cost of + some compatibility with Qt 3, it is useful for developers of + Qt 3-based applications to learn how to take advantage of + Qt 3's API now while preparing for future changes that will be + needed when upgrading to Qt 4. + + Certain advanced Qt 3 features were moved to the Qt 3 support + library (\l{Qt3Support}) in Qt 4.0, and have been gradually + replaced in subsequent releases of Qt 4. + + Making Qt 3 applications as portable to Qt 4 as possible + enables a smooth transition between versions of Qt in the + long term, and allows for a stable development process + throughout. + + \section1 Qt 3 Features to Avoid + + Although we are proud of the level of stability we have achieved + with Qt, it is important to realise that, for Qt 4 to be a + substantial improvement over Qt 3, certain features have + been revised to make the framework more maintainable for us + and more usable for developers. It is therefore useful to + know which features of Qt 3 should be avoided to help save + time during a later porting effort to Qt 4. Note that it is + still possible to use many of the following classes and + features through the use of the \l{Qt3Support} module. + + \section2 Painting Outside Paint Events + + In Qt 3, under certain circumstances, it was possible to use + QPainter to draw on a given custom widget outside its + \l{QWidget::}{paintEvent()} reimplementation. In Qt 4, in most + situations, painting must occur within a widget's paint event + handler. + + On X11, it is possible to set the \l{Qt::WA_PaintOutsidePaintEvent} + attribute on widgets to keep existing code, but we recommend + restricting the use of painting code to within paint event handlers + where possible. + + More information about this change can be found in the + \l{Porting to Qt 4#Painting and Redrawing Widgets}{Painting and Redrawing Widgets} + section of the \l{Porting to Qt 4} document. + + \section2 Qt Designer + + The version of Qt Designer supplied with Qt 3 provided + extensive code editing and project management features + (control over \c{.ui.h} and \c{.pro} files), and encouraged + users to design main window applications from within the + Qt Designer environment. + + The version of Qt Designer supplied with Qt 4 is intended + to be integrated with other software development tools (such + as integrated development environments), and does not + support these project-level features. + + We recommend using one of the + \l{Using a Designer UI File in Your Application}{form subclassing approaches} + with forms created using Qt Designer. This avoids the need + to use \c{.ui.h} files and special purpose code editors. + + Existing Qt 3 forms created using Qt Designer can be gradually + ported to Qt 4 by following the advice in the + \l{Porting UI Files to Qt 4} guide. However, some extra effort + will be required to move application logic from \c{.ui.h} files + into the main body of a Qt 4 application. + + \section2 Menu Items (QMenuItem) + + The old-style construction of menus by creating individual + menu items has been superseded in Qt 4 by the use of + generic actions which can be used in menus, toolbars, and + as keyboard shortcuts. + + Qt 3 also supports this action-based approach, so, by using + QAction throughout your application, less work will be + required to adapt your application to Qt 4. + + \section2 Pointer-Based Classes (QPtr*) + + Qt 3 provides a group of pointer-based classes (\c QPtrList, + \c QPtrDict, \c QPtrVector, etc.) that help manage collections + of pointers to objects (usually QObject subclasses) in an + application. In addition, the value-based collection classes + (\c QValueList, \c QValueDict, \c QValueVector, etc.) provide + a way to store standard value types which cannot be easily stored + in pointer-based collections. + + Qt 4 introduces a single set of collection classes which + does not require developers to pay as much attention to + memory allocation and object ownership issues. As a result, + Qt 3's pointer-based classes have no direct equivalent + classes in Qt 4. + + To ease migration, use Qt 3's value-based classes to store + most objects, including pointers; for example, use + \c QValueVector<QWidget *> rather than + \c QPtrVector<QWidget *>. These can be replaced by + Qt 4's QVector, QLinkedList, and QList later. + + \section2 Other Collection Classes (QStrList, Q*Dict) + + Some collection classes in Qt 3 have been deprecated in + favor of easier to use, higher level alternatives. These + include the dictionary classes (\c QAsciiDict, \c QDict, + \c QIntDict, \c QPtrDict) and \c QStrList. + + \c QStrList can usually replaced by the higher level QStringList + class in Qt 3; this is also available in Qt 4. It is + recommended that you use the QMap class instead of the \c QDict + classes. In Qt 4, QMap is also complemented by the QHash + class. + + \section2 Memory Arrays (QMemArray) + + In Qt 3, the \c QMemArray class is used as a simple array + container for simple data types. This class is deprecated in + Qt 4 in favor of the QVector and QVarLengthVector classes + which provide more powerful and consistent array objects. + + Qt 3's closest equivalent class to Qt 4's QVector is the + \c QValueVector class. For many purposes, this can be used + instead of \c QMemArray. + + \section2 URL Operations (QUrlOperator) + + The URL operator in Qt 3 provides an abstract way to + handle files via HTTP, FTP, and on the local file system. + However, Qt 4 only provides this functionality through the + use of the Q3UrlOperator. + + From Qt 4.4, the Network Access API provides a subset of the features + provided by \c QUrlOperator that are mostly intended for use with + applications that use the HTTP and FTP protocols. See the + QNetworkRequest, QNetworkReply, and QNetworkAccessManager documentation + for further details. + + It is also possible to perform operations on remote files through + the QNetworkAccessManager and QFtp classes, and on local files + with the QFile class. + + \section2 SQL Cursors (QSqlCursor) + + In Qt 3, one of the preferred methods of working with SQL + is to use a cursor to manipulate the contents of a database. + In Qt 4, the preferred method of working with SQL is to use + the model/view architecture (QSqlQueryModel and QSqlTableModel) + and, as a result, the cursor interface is only supplied in the + Q3SqlCursor class. + + The easiest way to ensure continuity between Qt 3 and Qt 4 + is to use QSqlQuery rather than \c QSqlCursor, + and migrate to QSqlQueryModel later. + + \section2 Domain Name Service (QDns) + + The QDns class in Qt 4 provides a much simpler interface + than the QDns class in Qt 3, and is mainly used for host + name resolution. + As a result, many of the more complex features of Qt 3's + QDns class are only available through Qt 4's Q3Dns + compatibility class. + + To resolve host names with Qt 3, it is recommended that you + use the higher level interface of QSocket rather than QDns. + The equivalent functionality is available in Qt 4 in the + QAbstractSocket and QHostInfo classes. + + \section2 Wizard Dialogs (QWizard) + + Qt 3 provides support for "wizard" dialogs in the form of + the \c QWizard class. Prior to Qt 4.3, this class was made + available as Q3Wizard, and provides the same interface for + creating relatively complex wizards. + + In Qt 4.3 and later, a revised QWizard class can be used to + create this kind of dialog, but existing Qt 3 wizard + implementations may need to be redesigned to work with the + new QWizard API. + + \section2 Abstract Grid Views (QGridView) + + Before the introduction of the Qt 3 \c QTable class, + \c QGridView was the recommended way to create tables of + custom items. + With the introduction of \c QTable, the \c QGridView class was + effectively obsoleted, and the \c QTable class should now be + used to display tabular information in your Qt 3 application. + This approach allows you to use QTableWidget as a replacement + when later porting your application to Qt 4. + + \section2 Specialized Scrolling Views + + In Qt 3, the \c QScrollView class provides a viewport that can + be used to display part of a larger widget, and will + optionally provide scroll bars for navigation purposes. + In Qt 4, this functionality is superseded by classes such as + QScrollArea, which provides a more intuitive interface for + developers to use. + \c QScrollView is available in Qt 4 as the Q3ScrollView class. + + In Qt 3, it is recommended that \c QScrollView should be + used with child widgets rather than subclassed. However, it + should be noted that this approach may not be appropriate if + you need to use extremely large scrolling areas in your + application, since Qt 3 widgets cannot be wider or taller + than 32767 pixels. + + \section1 Significantly Changed Features + + Some Qt 3 features have changed significantly for Qt 4. + and the recommended way of using them has therefore changed + significantly, too. This is most notably true for the drag + and drop API. + + Additionally, some of the more specialized features in Qt 3 are + often used to help customize widgets and add extra polish to an + application. + Although these improvements make applications more presentable to + users, many of them are unnecessary with Qt 4, and may create + additional porting work. + + \section2 Drag and Drop + + Qt 4 introduces a simpler and more intuitive implementation + of drag and drop between widgets, and with other applications. + As a result, there is no simple approach that can be used to + make drag and drop in a Qt 3 application easier to port to + Qt 4. + + \section2 Extensive Customization of Item Views + + Each of the classes that are used to display list, tree, + and table items in Qt 3 can be subclassed for the purposes + of customizing their appearance. The item view framework + in Qt 4 is implemented according to a different paradigm + (model/view) which does not allow items to be customized + using this method. + + Although Qt 4 provides compatibility classes (Q3ListBoxItem, + Q3ListViewItem, and Q3TableItem) that can be used in the same + way as their Qt 3 counterparts, these cannot be used within + the standard model/view framework. It is recommended that, + to minimize porting effort, extensive customization of item + classes should be avoided in Qt 3, if at all possible. + + \section2 Double Buffering + + Qt 3 applications often use double buffering for reducing + flicker when painting custom widgets. This approach is + unnecessary with Qt 4 because double buffering is + automatically performed by the paint engine. + + It still makes sense to use double buffering in + Qt 4 in certain contexts. For example, in + Chapter 5 of \l{GUI Programming with Qt 3}, double buffering + was presented as a speed optimization and not just as a means + of reducing flicker. + + \section2 Data-Aware Forms + + The \c QDataTable, \c QDataBrowser, and \c QDataView classes + in Qt 3 allow integration between widgets and SQL-based + databases. + + In Qt 4.1 and earlier, the preferred way to create a data-aware + widget is to connect an generic item view (such as a table view) + to a SQL model. In Qt 4.2 and later, the QDataWidgetMapper class + can be used to map data to widgets in a form-based user interface. + + New applications written with Qt 3 should use QSqlQuery in + preference to an approach based on the old-style data-aware + widgets. + This offers a choice of porting strategies when later migrating + the application to Qt 4: You can either continue to use + QSqlQuery or take the opportunity to use the model/view + classes to handle database integration. + + \section2 Dock Windows and Areas + + In Qt 4, the way that dock windows are constructed and used + in main window applications differs significantly to the + pattern of use provided by Qt 3. As a result, the introduction + of a simpler and cleaner API means that Qt 3 applications that + make extensive use of dock window areas will require careful + examination when they are ported to Qt 4. + + We recommend that the QMainWindow class be used in preference + to the Q3MainWindow compatibility class when an existing Qt 3 + main window application is ported to Qt 4. Therefore, we + recommend that specialized use of dock window areas should + be avoided when writing a Qt 3 application with Qt 4 in mind. + + \section2 Custom Styles + + The style system used to provide consistent themes for Qt's + standard widgets has been revised for Qt 4. As a result, + custom styles for Qt 3 require some porting work to be done + before they can be used with Qt 4. To ease the porting process, + we recommend that you avoid implementing custom widget styles + for Qt 3 applications unless it is absolutely necessary for + your users. + + In Qt 4.2 and later, \l{Qt Style Sheets} can be used to + implement many common modifications to existing styles, and + this may be sufficient for Qt 3 applications. + + \section2 Events + In Qt 3, QCloseEvents were not accepted by default. In Qt 4, + the event handler QWidget::closeEvent() receives QCloseEvents, + and accepts them by default closing the application. To avoid + this, please reimplement QWidget::closeEvent(). +*/ diff --git a/doc/src/porting/porting4-removedenumvalues.qdocinc b/doc/src/porting/porting4-removedenumvalues.qdocinc new file mode 100644 index 0000000..fe38d0e --- /dev/null +++ b/doc/src/porting/porting4-removedenumvalues.qdocinc @@ -0,0 +1,6 @@ +\row \o QButton::SingleShot +\row \o QButton::Toggle +\row \o QButton::Tristate +\row \o QEvent::AccelAvailable +\row \o QEvent::ParentFontChange +\row \o QEvent::ParentPaletteChange diff --git a/doc/src/porting/porting4-removedtypes.qdocinc b/doc/src/porting/porting4-removedtypes.qdocinc new file mode 100644 index 0000000..9d7c519 --- /dev/null +++ b/doc/src/porting/porting4-removedtypes.qdocinc @@ -0,0 +1 @@ +\row \o QAbstractButton::ToggleType diff --git a/doc/src/porting/porting4-removedvariantfunctions.qdocinc b/doc/src/porting/porting4-removedvariantfunctions.qdocinc new file mode 100644 index 0000000..dfaa8f3 --- /dev/null +++ b/doc/src/porting/porting4-removedvariantfunctions.qdocinc @@ -0,0 +1,16 @@ +\row \o toBitmap () \o QVariant::value() +\row \o toBrush () \o QVariant::value() +\row \o toColorGroup () \o Use QVariant::value() with QPalette instead. +\row \o toColor () \o QVariant::value() +\row \o toCString () \o QVariant::toByteArray() +\row \o toCursor () \o QVariant::value() +\row \o toFont () \o QVariant::value() +\row \o toIconSet () \o Use QVariant::value() with QIcon instead. +\row \o toImage () \o QVariant::value() +\row \o toKeySequence () \o QVariant::value() +\row \o toPalette () \o QVariant::value() +\row \o toPen () \o QVariant::value() +\row \o toPixmap () \o QVariant::value() +\row \o toPointArray () \o QVariant::value() +\row \o toRegion () \o QVariant::value() +\row \o toSizePolicy () \o QVariant::value() diff --git a/doc/src/porting/porting4-removedvirtual.qdocinc b/doc/src/porting/porting4-removedvirtual.qdocinc new file mode 100644 index 0000000..1af4fa6 --- /dev/null +++ b/doc/src/porting/porting4-removedvirtual.qdocinc @@ -0,0 +1,605 @@ +\row \o void QAccessibleInterface::clearSelection() \o Port to the new QAccessibleInterface API. +\row \o int QAccessibleInterface::controlAt(int, int) const \o Port to the new QAccessibleInterface API. +\row \o bool QAccessibleInterface::doDefaultAction(int) \o Port to the new QAccessibleInterface API. +\row \o QMemArray<int> QAccessibleInterface::selection() const \o Port to the new QAccessibleInterface API. +\row \o bool QAccessibleInterface::setFocus(int) \o Port to the new QAccessibleInterface API. +\row \o bool QAccessibleInterface::setSelected(int, bool, bool) \o Port to the new QAccessibleInterface API. +\row \o bool QAction::addTo(QWidget *) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::addedTo(QWidget *, QWidget *) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::addedTo(int, QPopupMenu *) \o Use Q3Action instead or port to the new QAction API. +\row \o bool QAction::removeFrom(QWidget *) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setAccel(const QKeySequence &) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setEnabled(bool) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setIconSet(const QIcon &) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setMenuText(const QString &) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setOn(bool) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setStatusTip(const QString &) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setText(const QString &) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setToggleAction(bool) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setToolTip(const QString &) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setWhatsThis(const QString &) \o Use Q3Action instead or port to the new QAction API. +\row \o void QButton::drawButton(QPainter *) \o Use Q3Button instead or reimplement QButton::paintEvent(). +\row \o void QButton::drawButtonLabel(QPainter *) \o Use Q3Button instead or reimplement QButton::paintEvent(). +\row \o void QButton::setAccel(const QKeySequence &) \o Setter. +\row \o void QButton::setAutoRepeat(bool) \o Setter. +\row \o void QButton::setDown(bool) \o Use Q3Button instead or reimplement or port to the new QPushButton API. +\row \o void QButton::setPixmap(const QPixmap &) \o Setter. +\row \o void QButton::setState(ToggleState) \o Setter. +\row \o void QButton::setText(const QString &) \o Use the QAbstractButton::setText() setter function. +\row \o void QButton::setToggleType(ToggleType) \o Setter. +\row \o void QButtonGroup::moveFocus(int) \o Use the QWidget::setFocus() setter function. +\row \o void QButtonGroup::setButton(int) \o Setter. +\row \o void QButtonGroup::setExclusive(bool) \o Setter. +\row \o void QButtonGroup::setRadioButtonExclusive(bool) \o Setter. +\row \o void QComboBox::setAutoCompletion(bool) \o Setter. +\row \o void QComboBox::setAutoResize(bool) \o Setter. +\row \o void QComboBox::setCurrentItem(int) \o Setter. +\row \o void QComboBox::setCurrentText(const QString &) \o Setter. +\row \o void QComboBox::setFont(const QFont &) \o Setter. +\row \o void QComboBox::setInsertionPolicy(Policy) \o Setter. +\row \o void QComboBox::setLineEdit(QLineEdit *) \o Setter. +\row \o void QComboBox::setListBox(QListBox *) \o Setter. +\row \o void QComboBox::setMaxCount(int) \o Setter. +\row \o void QComboBox::setPalette(const QPalette &) \o Setter. +\row \o void QComboBox::setSizeLimit(int) \o Setter. +\row \o void QComboBox::setValidator(const QValidator *) \o Setter. +\row \o void QDateEdit::fix() \o Port to the new QDateTimeEdit API. +\row \o QString QDateEdit::sectionFormattedText(int) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setAutoAdvance(bool) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setDate(const QDate &) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setDay(int) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setMaxValue(const QDate &) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setMinValue(const QDate &) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setMonth(int) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setOrder(Order) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setRange(const QDate &, const QDate &) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setSeparator(const QString &) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setYear(int) \o Port to the new QDateTimeEdit API. +\row \o void QDateTimeEdit::setAutoAdvance(bool) \o Port to the new QDateTimeEdit API. +\row \o void QDateTimeEdit::setDateTime(const QDateTime &) \o Port to the new QDateTimeEdit API. +\row \o void QDial::rangeChange() \o Reimplement QDial::sliderChange() instead. +\row \o void QDial::repaintScreen(const QRect *) \o Reimplement QDial::paintEvent() instead. +\row \o void QDial::setNotchTarget(double) \o Setter. +\row \o void QDial::setNotchesVisible(bool) \o Setter. +\row \o void QDial::setTracking(bool) \o Setter. +\row \o void QDial::setValue(int) \o Use QDial::sliderChange() instead. +\row \o void QDial::setWrapping(bool) \o Setter. +\row \o void QDial::valueChange() \o Use QDial::sliderChange() instead. +\row \o QString QDir::absFilePath(const QString &, bool) const \o Value type. +\row \o QString QDir::absPath() const \o Value type. +\row \o QString QDir::canonicalPath() const \o Value type. +\row \o bool QDir::cd(const QString &, bool) \o Value type. +\row \o bool QDir::cdUp() \o Value type. +\row \o void QDir::convertToAbs() \o Value type. +\row \o QString QDir::dirName() const \o Value type. +\row \o QStrList QDir::encodedEntryList(int, int) const \o Value type. +\row \o QStrList QDir::encodedEntryList(const QString &, int, int) const \o Value type. +\row \o const QFileInfoList * QDir::entryInfoList(int, int) const \o Value type. +\row \o const QFileInfoList * QDir::entryInfoList(const QString &, int, int) const \o Value type. +\row \o QStringList QDir::entryList(const QString &, int, int) const \o Value type. +\row \o QStringList QDir::entryList(int, int) const \o Value type. +\row \o bool QDir::exists() const \o Value type. +\row \o bool QDir::exists(const QString &, bool) \o Value type. +\row \o QString QDir::filePath(const QString &, bool) const \o Value type. +\row \o bool QDir::isReadable() const \o Value type. +\row \o bool QDir::isRelative() const \o Value type. +\row \o bool QDir::isRoot() const \o Value type. +\row \o bool QDir::mkdir(const QString &, bool) const \o Value type. +\row \o bool QDir::operator!=() const \o Value type. +\row \o bool QDir::operator==() const \o Value type. +\row \o QString QDir::path() const \o Value type. +\row \o bool QDir::remove(const QString &, bool) \o Value type. +\row \o bool QDir::rename(const QString &, const QString &, bool) \o Value type. +\row \o bool QDir::rmdir(const QString &, bool) const \o Value type. +\row \o void QDir::setFilter(int) \o Value type. +\row \o void QDir::setMatchAllDirs(bool) \o Value type. +\row \o void QDir::setNameFilter(const QString &) \o Value type. +\row \o void QDir::setPath(const QString &) \o Value type. +\row \o void QDir::setSorting(int) \o Value type. +\row \o void QDns::setLabel(const QString &) \o Use Q3Dns instead. +\row \o void QDns::setLabel(const QHostAddress &) \o Use Q3Dns instead. +\row \o void QDns::setRecordType(RecordType) \o Use Q3Dns instead. +\row \o void QDockWindow::dock() \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setCloseMode(int) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setFixedExtentHeight(int) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setFixedExtentWidth(int) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setHorizontallyStretchable(bool) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setMovingEnabled(bool) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setNewLine(bool) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setOffset(int) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setOpaqueMoving(bool) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setOrientation(Orientation) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setResizeEnabled(bool) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setVerticallyStretchable(bool) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setWidget(QWidget *) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::undock() \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o QString QDomAttr::name() const \o Value type. +\row \o QDomElement QDomAttr::ownerElement() const \o Value type. +\row \o void QDomAttr::setValue(const QString &) \o Value type. +\row \o bool QDomAttr::specified() const \o Value type. +\row \o QString QDomAttr::value() const \o Value type. +\row \o void QDomCharacterData::appendData(const QString &) \o Value type. +\row \o QString QDomCharacterData::data() const \o Value type. +\row \o void QDomCharacterData::deleteData(unsigned, unsigned) \o Value type. +\row \o void QDomCharacterData::insertData(unsigned, const QString &) \o Value type. +\row \o uint QDomCharacterData::length() const \o Value type. +\row \o void QDomCharacterData::replaceData(unsigned, unsigned, const QString &) \o Value type. +\row \o void QDomCharacterData::setData(const QString &) \o Value type. +\row \o QString QDomCharacterData::substringData(unsigned, unsigned) \o Value type. +\row \o QDomNamedNodeMap QDomDocumentType::entities() const \o Value type. +\row \o QString QDomDocumentType::internalSubset() const \o Value type. +\row \o QString QDomDocumentType::name() const \o Value type. +\row \o QDomNamedNodeMap QDomDocumentType::notations() const \o Value type. +\row \o QString QDomDocumentType::publicId() const \o Value type. +\row \o QString QDomDocumentType::systemId() const \o Value type. +\row \o QDomNamedNodeMap QDomElement::attributes() const \o Value type. +\row \o QDomNodeList QDomElement::elementsByTagName(const QString &) const \o Value type. +\row \o QDomNodeList QDomElement::elementsByTagNameNS(const QString &, const QString &) const \o Value type. +\row \o QString QDomEntity::notationName() const \o Value type. +\row \o QString QDomEntity::publicId() const \o Value type. +\row \o QString QDomEntity::systemId() const \o Value type. +\row \o QDomDocument QDomImplementation::createDocument(const QString &, const QString &, const QDomDocumentType &) \o Value type. +\row \o QDomDocumentType QDomImplementation::createDocumentType(const QString &, const QString &, const QString &) \o Value type. +\row \o bool QDomImplementation::hasFeature(const QString &, const QString &) \o Value type. +\row \o QDomImplementation::~QDomImplementation() \o Value type. +\row \o QDomNode QDomNode::appendChild(const QDomNode &) \o Value type. +\row \o QDomNamedNodeMap QDomNode::attributes() const \o Value type. +\row \o QDomNodeList QDomNode::childNodes() const \o Value type. +\row \o QDomNode QDomNode::cloneNode(bool) const \o Value type. +\row \o QDomNode QDomNode::firstChild() const \o Value type. +\row \o bool QDomNode::hasAttributes() const \o Value type. +\row \o bool QDomNode::hasChildNodes() const \o Value type. +\row \o QDomNode QDomNode::insertAfter(const QDomNode &, const QDomNode &) \o Value type. +\row \o QDomNode QDomNode::insertBefore(const QDomNode &, const QDomNode &) \o Value type. +\row \o bool QDomNode::isAttr() const \o Value type. +\row \o bool QDomNode::isCDATASection() const \o Value type. +\row \o bool QDomNode::isCharacterData() const \o Value type. +\row \o bool QDomNode::isComment() const \o Value type. +\row \o bool QDomNode::isDocument() const \o Value type. +\row \o bool QDomNode::isDocumentFragment() const \o Value type. +\row \o bool QDomNode::isDocumentType() const \o Value type. +\row \o bool QDomNode::isElement() const \o Value type. +\row \o bool QDomNode::isEntity() const \o Value type. +\row \o bool QDomNode::isEntityReference() const \o Value type. +\row \o bool QDomNode::isNotation() const \o Value type. +\row \o bool QDomNode::isProcessingInstruction() const \o Value type. +\row \o bool QDomNode::isSupported(const QString &, const QString &) const \o Value type. +\row \o bool QDomNode::isText() const \o Value type. +\row \o QDomNode QDomNode::lastChild() const \o Value type. +\row \o QString QDomNode::localName() const \o Value type. +\row \o QString QDomNode::namespaceURI() const \o Value type. +\row \o QDomNode QDomNode::nextSibling() const \o Value type. +\row \o QString QDomNode::nodeName() const \o Value type. +\row \o QDomNode::NodeType QDomNode::nodeType() const \o Value type. +\row \o QString QDomNode::nodeValue() const \o Value type. +\row \o void QDomNode::normalize() \o Value type. +\row \o QDomDocument QDomNode::ownerDocument() const \o Value type. +\row \o QDomNode QDomNode::parentNode() const \o Value type. +\row \o QString QDomNode::prefix() const \o Value type. +\row \o QDomNode QDomNode::previousSibling() const \o Value type. +\row \o QDomNode QDomNode::removeChild(const QDomNode &) \o Value type. +\row \o QDomNode QDomNode::replaceChild(const QDomNode &, const QDomNode &) \o Value type. +\row \o void QDomNode::setNodeValue(const QString &) \o Value type. +\row \o void QDomNode::setPrefix(const QString &) \o Value type. +\row \o QDomNode::~QDomNode() \o Value type. +\row \o QDomNode QDomNodeList::item(int) const \o Value type. +\row \o uint QDomNodeList::length() const \o Value type. +\row \o QDomNodeList::~QDomNodeList() \o Value type. +\row \o QString QDomProcessingInstruction::data() const \o Value type. +\row \o void QDomProcessingInstruction::setData(const QString &) \o Value type. +\row \o QString QDomProcessingInstruction::target() const \o Value type. +\row \o int QEventLoop::enterLoop() \o Port to the new QAbstractEventDispatcher API. +\row \o int QEventLoop::exec() \o Port to the new QAbstractEventDispatcher API. +\row \o void QEventLoop::exit(int) \o Port to the new QAbstractEventDispatcher API. +\row \o void QEventLoop::exitLoop() \o Port to the new QAbstractEventDispatcher API. +\row \o bool QEventLoop::hasPendingEvents() const \o Port to the new QAbstractEventDispatcher API. +\row \o int QEventLoop::loopLevel() const \o Port to the new QAbstractEventDispatcher API. +\row \o bool QEventLoop::processEvents(ProcessEventsFlags) \o Port to the new QAbstractEventDispatcher API. +\row \o void QEventLoop::registerSocketNotifier(QSocketNotifier *) \o Port to the new QAbstractEventDispatcher API. +\row \o void QEventLoop::unregisterSocketNotifier(QSocketNotifier *) \o Port to the new QAbstractEventDispatcher API. +\row \o void QEventLoop::wakeUp() \o Port to the new QAbstractEventDispatcher API. +\row \o void QFrame::drawContents(QPainter *) \o Use Q3Frame or reimplement QFrame::paintEvent() instead. +\row \o void QFrame::drawFrame(QPainter *) \o Use Q3Frame or reimplement QFrame::paintEvent() instead. +\row \o void QFrame::frameChanged() \o Use Q3Frame or reimplement QFrame::resizeEvent() instead. +\row \o void QFrame::setFrameRect(const QRect &) \o Setter. +\row \o void QFrame::setFrameStyle(int) \o Setter. +\row \o void QFrame::setLineWidth(int) \o Setter. +\row \o void QFrame::setMargin(int) \o Setter. +\row \o void QFrame::setMidLineWidth(int) \o Setter. +\row \o void QGridLayout::setColStretch(int, int) \o Setter. +\row \o void QGridLayout::setRowStretch(int, int) \o Setter. +\row \o void QGroupBox::setAlignment(int) \o Setter. +\row \o void QGroupBox::setColumnLayout(int, Orientation) \o Setter. +\row \o void QGroupBox::setTitle(const QString &) \o Setter. +\row \o QHostAddress::~QHostAddress() \o Value type. +\row \o int QIODevice::getch() \o Port to the new QIODevice API. +\row \o int QIODevice::putch(int) \o Port to the new QIODevice API. +\row \o QByteArray QIODevice::readAll() \o Port to the new QIODevice API. +\row \o Q_LONG QIODevice::readLine(char *, Q_ULONG) \o Port to the new QIODevice API. +\row \o int QIODevice::ungetch(int) \o Port to the new QIODevice API. +\row \o void QIcon::setPixmap(const QString &, Size, Mode, State) \o Value type. +\row \o void QIcon::setPixmap(const QPixmap &, Size, Mode, State) \o Value type. +\row \o QIcon::~QIcon() \o Value type. +\row \o void QLabel::setAlignment(int) \o Setter. +\row \o void QLabel::setAutoResize(bool) \o Setter. +\row \o void QLabel::setBuddy(QWidget *) \o Setter. +\row \o void QLabel::setMovie(const QMovie &) \o Setter. +\row \o void QLabel::setNum(int) \o Setter. +\row \o void QLabel::setNum(double) \o Setter. +\row \o void QLabel::setPicture(const QPicture &) \o Setter. +\row \o void QLabel::setPixmap(const QPixmap &) \o Setter. +\row \o void QLabel::setText(const QString &) \o Setter. +\row \o QLayoutIterator QLayout::iterator() \o Port to the new QLayout API. +\row \o void QLayout::setAutoAdd(bool) \o Setter. +\row \o void QLayout::setMargin(int) \o Setter. +\row \o void QLayout::setMenuBar(QMenuBar *) \o Setter. +\row \o void QLayout::setSpacing(int) \o Setter. +\row \o QLayoutIterator QLayoutItem::iterator() \o Port to the new QLayoutItem API. +\row \o void QLayoutItem::setAlignment(int) \o Setter. +\row \o bool QLibrary::unload() \o Never used polymorphically in Qt. +\row \o void QLineEdit::clear() \o Connect to QLineEdit::textChanged() instead. +\row \o void QLineEdit::clearValidator() \o Never used polymorphically in Qt. +\row \o void QLineEdit::copy() const \o Never used polymorphically in Qt. +\row \o void QLineEdit::cut() \o Never used polymorphically in Qt. +\row \o void QLineEdit::deselect() \o Connect to QLineEdit::selectionChanged() instead. +\row \o void QLineEdit::insert(const QString &) \o Connect to QLineEdit::textChanged() instead. +\row \o void QLineEdit::paste() \o Connect to QLineEdit::textChanged() instead. +\row \o void QLineEdit::redo() \o Never used polymorphically in Qt. +\row \o void QLineEdit::selectAll() \o Connect to QLineEdit::selectionChanged() instead. +\row \o void QLineEdit::setAlignment(int) \o Setter. +\row \o void QLineEdit::setCursorPosition(int) \o Connect to QLineEdit::cursorPositionChanged() instead. +\row \o void QLineEdit::setDragEnabled(bool) \o Setter. +\row \o void QLineEdit::setEchoMode(EchoMode) \o Setter. +\row \o void QLineEdit::setFrame(bool) \o Setter. +\row \o void QLineEdit::setMaxLength(int) \o Setter. +\row \o void QLineEdit::setReadOnly(bool) \o Setter. +\row \o void QLineEdit::setSelection(int, int) \o Connect to QLineEdit::selectionChanged() instead. +\row \o void QLineEdit::setText(const QString &) \o Connect to QLineEdit::textChanged() instead. +\row \o void QLineEdit::setValidator(const QValidator *) \o Setter. +\row \o void QLineEdit::undo() \o Never used in a polymorphic way by Qt. +\row \o void QMainWindow::addDockWindow(QDockWindow *, Dock, bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::addDockWindow(QDockWindow *, const QString &, Dock, bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::customize() \o Port to the new QMainWindow API. +\row \o bool QMainWindow::isCustomizable() const \o Port to the new QMainWindow API. +\row \o void QMainWindow::moveDockWindow(QDockWindow *, Dock) \o Port to the new QMainWindow API. +\row \o void QMainWindow::moveDockWindow(QDockWindow *, Dock, bool, int, int) \o Port to the new QMainWindow API. +\row \o void QMainWindow::removeDockWindow(QDockWindow *) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setAppropriate(QDockWindow *, bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setCentralWidget(QWidget *) \o Setter. +\row \o void QMainWindow::setDockEnabled(QDockWindow *, Dock, bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setDockEnabled(Dock, bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setDockMenuEnabled(bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setDockWindowsMovable(bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setOpaqueMoving(bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setRightJustification(bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setUpLayout() \o Port to the new QMainWindow API. +\row \o void QMainWindow::setUsesBigPixmaps(bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setUsesTextLabel(bool) \o Port to the new QMainWindow API. +\row \o bool QMainWindow::showDockMenu(const QPoint &) \o Port to the new QMainWindow API. +\row \o void QMenuBar::activateItemAt(int) \o Port to the new QMenuBar API. +\row \o void QMenuBar::menuContentsChanged() \o Port to the new QMenuBar API. +\row \o void QMenuBar::menuDelPopup(QPopupMenu *) \o Port to the new QMenuBar API. +\row \o void QMenuBar::menuInsPopup(QPopupMenu *) \o Port to the new QMenuBar API. +\row \o void QMenuBar::menuStateChanged() \o Port to the new QMenuBar API. +\row \o void QMenuBar::setId(int, int) \o Port to the new QMenuBar API. +\row \o void QMenuBar::setSeparator(Separator) \o Port to the new QMenuBar API. +\row \o void QMenuBar::updateItem(int) \o Port to the new QMenuBar API. +\row \o QMutex::~QMutex() \o Value type. +\row \o bool QObject::checkConnectArgs(const char *, const QObject *, const char *) \o Reimplementing this function is no longer possible. +\row \o const char * QObject::className() const \o Reimplementing this function is no longer supported. +\row \o void QObject::insertChild(QObject *) \o Reimplement QObject::childEvent() instead and handle QEvent::ChildAdded events. +\row \o QVariant QObject::property(const char *) const \o Reimplementing this function is no longer supported. +\row \o void QObject::removeChild(QObject *) \o Reimplement QObject::childEvent() instead and handle QEvent::ChildRemoved events. +\row \o void QObject::setName(const char *) \o Setter. +\row \o bool QObject::setProperty(const char *, const QVariant &) \o Setter. +\row \o bool QPaintDevice::cmd(int , QPainter * , QPDevCmdParam *) \o Port to the new QPaintEngine API. +\row \o Qt::HANDLE QPaintDevice::handle() const \o Port to the new QPaintDevice API. +\row \o HDC QPaintDevice::handle() const \o Port to the new QPaintDevice API. +\row \o void QPopupMenu::activateItemAt(int) \o Port to the new QMenu API. +\row \o void QPopupMenu::menuContentsChanged() \o Port to the new QMenu API. +\row \o void QPopupMenu::menuDelPopup(QPopupMenu *) \o Port to the new QMenu API. +\row \o void QPopupMenu::menuInsPopup(QPopupMenu *) \o Port to the new QMenu API. +\row \o void QPopupMenu::menuStateChanged() \o Port to the new QMenu API. +\row \o void QPopupMenu::setActiveItem(int) \o Port to the new QMenu API. +\row \o void QPopupMenu::setCheckable(bool) \o Port to the new QMenu API. +\row \o void QPopupMenu::setId(int, int) \o Port to the new QMenu API. +\row \o void QPopupMenu::updateItem(int) \o Port to the new QMenu API. +\row \o int QPrinter::resolution() const \o Call QPrinter::setResolution() to change the resolution. +\row \o void QPrinter::setColorMode(ColorMode) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setCreator(const QString &) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setDocName(const QString &) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setFromTo(int, int) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setFullPage(bool) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setMinMax(int, int) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setNumCopies(int) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setOrientation(Orientation) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setOutputFileName(const QString &) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setOutputToFile(bool) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setPageOrder(PageOrder) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setPageSize(PageSize) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setPaperSource(PaperSource) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setPrintProgram(const QString &) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setPrinterName(const QString &) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setPrinterSelectionOption(const QString &) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setResolution(int) \o Subclass QPrintEngine instead. +\row \o void QProcess::addArgument(const QString &) \o Not used polymorphically in Qt. +\row \o void QProcess::closeStdin() \o Not used polymorphically in Qt. +\row \o bool QProcess::launch(const QByteArray & buf, QStringList *) \o Not used polymorphically in Qt. +\row \o bool QProcess::launch(const QString & buf, QStringList *) \o Not used polymorphically in Qt. +\row \o QString QProcess::readLineStderr() \o Not used polymorphically in Qt. +\row \o QString QProcess::readLineStdout() \o Not used polymorphically in Qt. +\row \o QByteArray QProcess::readStderr() \o Not used polymorphically in Qt. +\row \o QByteArray QProcess::readStdout() \o Not used polymorphically in Qt. +\row \o void QProcess::setArguments(const QStringList &) \o Not used polymorphically in Qt. +\row \o void QProcess::setWorkingDirectory(const QDir &) \o Not used polymorphically in Qt. +\row \o bool QProcess::start(QStringList *) \o Not used polymorphically in Qt. +\row \o void QProcess::writeToStdin(const QByteArray &) \o Not used polymorphically in Qt. +\row \o bool QProgressBar::setIndicator(QString &, int, int) \o Not used polymorphically in Qt. +\row \o void QProgressBar::setProgress(int) \o Not used polymorphically in Qt. +\row \o void QProgressBar::setTotalSteps(int) \o Not used polymorphically in Qt. +\row \o void QPushButton::setAutoDefault(bool) \o Not used polymorphically in Qt. +\row \o void QPushButton::setDefault(bool) \o Not used polymorphically in Qt. +\row \o void QPushButton::setIsMenuButton(bool) \o Not used polymorphically in Qt. +\row \o void QPushButton::setOn(bool) \o Connect to QPushButton::toggled(bool) instead. +\row \o void QRadioButton::setChecked(bool) \o Connect to QRadioButton::toggled(bool) instead. +\row \o uchar * QScreen::cache(int , int) \o Port to the new QScreen API. +\row \o void QScreen::set(unsigned int , unsigned int , unsigned int , unsigned) \o Port to the new QScreen API. +\row \o void QScreen::uncache(uchar *) \o Port to the new QScreen API. +\row \o void QScrollBar::setOrientation(Orientation) \o Setter. +\row \o void QScrollBar::setTracking(bool) \o Setter. +\row \o void QSignalMapper::setMapping(const QObject *, const QString &) \o Setter. +\row \o void QSignalMapper::setMapping(const QObject *, int) \o Setter. +\row \o void QSlider::rangeChange() \o Reimplement QSlider::sliderChange() instead. +\row \o void QSlider::setOrientation(Orientation) \o Setter. +\row \o void QSlider::setPalette(const QPalette &) \o Setter. +\row \o void QSlider::setTickInterval(int) \o Setter. +\row \o void QSlider::setTickmarks(TickSetting) \o Setter. +\row \o void QSlider::setTracking(bool) \o Setter. +\row \o void QSlider::setValue(int) \o Reimplement QSlider::sliderChange() instead. +\row \o void QSlider::valueChange() \o Reimplement QSlider::sliderChange() instead. +\row \o QString QSpinBox::cleanText() const \o Port to the new QSpinBox API. +\row \o void QSpinBox::interpretText() \o Port to the new QSpinBox API. +\row \o QString QSpinBox::prefix() const \o Port to the new QSpinBox API. +\row \o void QSpinBox::rangeChange() \o Reimplement QSpinBox::sliderChange() instead. +\row \o void QSpinBox::selectAll() \o Port to the new QSpinBox API. +\row \o void QSpinBox::setButtonSymbols(ButtonSymbols) \o Setter. +\row \o void QSpinBox::setPrefix(const QString &) \o Setter. +\row \o void QSpinBox::setSpecialValueText(const QString &) \o Setter. +\row \o void QSpinBox::setSuffix(const QString &) \o Setter. +\row \o void QSpinBox::setValidator(const QValidator *) \o Setter. +\row \o void QSpinBox::setValue(int) \o Connect to QSpinBox::valueChanged(). +\row \o void QSpinBox::setWrapping(bool) \o Setter. +\row \o void QSpinBox::stepDown() \o Reimplement QSpinBox::stepBy() instead. +\row \o void QSpinBox::stepUp() \o Reimplement QSpinBox::stepBy() instead. +\row \o QString QSpinBox::suffix() const \o Port to the new QSpinBox API. +\row \o void QSpinBox::updateDisplay() \o Port to the new QSpinBox API. +\row \o void QSpinBox::valueChange() \o Reimplement QSpinBox::sliderChange() instead. +\row \o void QSplitter::drawSplitter(QPainter *, QCOORD, QCOORD, QCOORD, QCOORD) \o Reimplement QStyle::drawPrimitive() instead and handle QStyle::PE_Splitter. +\row \o void QSplitter::setOpaqueResize(bool) \o Setter. +\row \o void QSplitter::setOrientation(Orientation) \o Setter. +\row \o void QSplitter::setResizeMode(QWidget *, ResizeMode) \o Setter. +\row \o void QSqlDatabase::setDatabaseName(const QString &) \o Setter. +\row \o void QSqlDatabase::setHostName(const QString &) \o Setter. +\row \o void QSqlDatabase::setPassword(const QString &) \o Setter. +\row \o void QSqlDatabase::setPort(int) \o Setter. +\row \o void QSqlDatabase::setUserName(const QString &) \o Setter. +\row \o QSqlQuery QSqlDriver::createQuery() const \o Port to the new QSqlDriver API. +\row \o QString QSqlDriver::nullText() const \o Port to the new QSqlDriver API. +\row \o QSqlRecord QSqlDriver::record(const QSqlQuery &) const \o Port to the new QSqlDriver API. +\row \o QSqlRecordInfo QSqlDriver::recordInfo(const QSqlQuery &) const \o Port to the new QSqlDriver API. +\row \o QSqlRecordInfo QSqlDriver::recordInfo(const QString &) const \o Port to the new QSqlDriver API. +\row \o void QSqlError::setDatabaseText(const QString &) \o Value type. +\row \o void QSqlError::setDriverText(const QString &) \o Value type. +\row \o void QSqlError::setNumber(int) \o Value type. +\row \o void QSqlError::setType(int) \o Value type. +\row \o QSqlError::~QSqlError() \o Value type. +\row \o void QSqlField::setName(const QString &) \o Value type. +\row \o void QSqlField::setNull() \o Value type. +\row \o void QSqlField::setReadOnly(bool) \o Value type. +\row \o void QSqlField::setValue(const QVariant &) \o Value type. +\row \o QVariant QSqlField::value() const \o Value type. +\row \o QSqlField::~QSqlField() \o Value type. +\row \o void QSqlFieldInfo::setCalculated(bool) \o Value type. +\row \o void QSqlFieldInfo::setGenerated(bool) \o Value type. +\row \o void QSqlFieldInfo::setTrim(bool) \o Value type. +\row \o QSqlFieldInfo::~QSqlFieldInfo() \o Value type. +\row \o void QSqlIndex::append(const QSqlField &) \o Value type. +\row \o void QSqlIndex::append(const QSqlField &, bool) \o Value type. +\row \o void QSqlIndex::setCursorName(const QString &) \o Value type. +\row \o void QSqlIndex::setDescending(int, bool) \o Value type. +\row \o void QSqlIndex::setName(const QString &) \o Value type. +\row \o QVariant QSqlQuery::value(int) const \o Exists as a non-virtual function. +\row \o void QSqlRecord::append(const QSqlField &) \o Value type. +\row \o void QSqlRecord::clear() \o Value type. +\row \o void QSqlRecord::clearValues(bool) \o Value type. +\row \o void QSqlRecord::insert(int, const QSqlField &) \o Value type. +\row \o void QSqlRecord::remove(int) \o Value type. +\row \o void QSqlRecord::setGenerated(const QString &, bool) \o Value type. +\row \o void QSqlRecord::setGenerated(int, bool) \o Value type. +\row \o void QSqlRecord::setNull(int) \o Value type. +\row \o void QSqlRecord::setNull(const QString &) \o Value type. +\row \o void QSqlRecord::setValue(const QString &, const QVariant &) \o Value type. +\row \o void QSqlRecord::setValue(int, const QVariant &) \o Value type. +\row \o QString QSqlRecord::toString(const QString &, const QString &) const \o Value type. +\row \o QStringList QSqlRecord::toStringList(const QString &) const \o Value type. +\row \o QVariant QSqlRecord::value(int) const \o Value type. +\row \o QVariant QSqlRecord::value(const QString &) const \o Value type. +\row \o QSqlRecord::~QSqlRecord() \o Value type. +\row \o void QStyle::polishPopupMenu(QPopupMenu *) \o Reimplement QStyle::polish(QWidget *) instead. +\row \o int QTabBar::addTab(QTab *) \o Reimplement QTabBar::tabInserted() instead. +\row \o int QTabBar::insertTab(QTab *, int) \o Reimplement QTabBar::tabInserted() instead. +\row \o void QTabBar::layoutTabs() \o Reimplement QTabBar::tabLayoutChange() instead. +\row \o void QTabBar::paint(QPainter *, QTab *, bool) const \o Reimplement QTabBar::paintEvent() instead. +\row \o void QTabBar::paintLabel(QPainter *, const QRect &, QTab *, bool) const \o Reimplement QTabBar::paintEvent() instead. +\row \o void QTabBar::removeTab(QTab *) \o Reimplement QTabBar::tabRemoved() instead. +\row \o QTab * QTabBar::selectTab(const QPoint &) const \o Reimplement QTabBar::mousePressEvent() instead. +\row \o void QTabBar::setCurrentTab(int) \o Connect to the QTabBar::currentChanged() signal. +\row \o void QTabBar::setCurrentTab(QTab *) \o Connect to the QTabBar::currentChanged() signal. +\row \o void QTabBar::setShape(Shape) \o Setter. +\row \o void QTabBar::setTabEnabled(int, bool) \o Setter. +\row \o void QTabWidget::addTab(QWidget *, const QString &) \o Reimplement QTabWidget::tabInserted() instead. +\row \o void QTabWidget::addTab(QWidget *, const QIcon &, const QString &) \o Reimplement QTabWidget::tabInserted() instead. +\row \o void QTabWidget::addTab(QWidget *, QTab *) \o Reimplement QTabWidget::tabInserted() instead. +\row \o void QTabWidget::insertTab(QWidget *, const QIcon &, const QString &, int) \o Reimplement QTabWidget::tabInserted() instead. +\row \o void QTabWidget::insertTab(QWidget *, const QString &, int) \o Reimplement QTabWidget::tabInserted() instead. +\row \o void QTabWidget::insertTab(QWidget *, QTab *, int) \o Reimplement QTabWidget::tabInserted() instead. +\row \o void QTabWidget::removePage(QWidget *) \o Reimplement QTabWidget::tabRemoved() instead. +\row \o void QTabWidget::showPage(QWidget *) \o Connect to QTabWidget::currentChanged() instead. +\row \o void QTextEdit::append(const QString &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::clear() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::clearParagraphBackground(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::copy() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o QPopupMenu * QTextEdit::createPopupMenu(const QPoint &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o QPopupMenu * QTextEdit::createPopupMenu() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::cut() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::del() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::doKeyboardAction(KeyboardAction) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::ensureCursorVisible() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o bool QTextEdit::find(const QString &, bool, bool, bool, int *, int *) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o bool QTextEdit::focusNextPrevChild(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o int QTextEdit::heightForWidth(int) const \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::insert(const QString &, bool, bool, bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::insertAt(const QString &, int, int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::insertParagraph(const QString &, int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::moveCursor(CursorAction, bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::paste() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::pasteSubType(const QCString &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::placeCursor(const QPoint &, QTextCursor *) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::redo() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::removeParagraph(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::removeSelectedText(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::removeSelection(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::scrollToAnchor(const QString &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::scrollToBottom() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::selectAll(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setAlignment(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setBold(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setColor(const QColor &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setCurrentFont(const QFont &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setCursorPosition(int, int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setFamily(const QString &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setItalic(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setLinkUnderline(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setMimeSourceFactory(QMimeSourceFactory *) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setModified(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setOverwriteMode(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setPaper(const QBrush &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setParagraphBackgroundColor(int, const QColor &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setPointSize(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setReadOnly(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setSelection(int, int, int, int, int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setSelectionAttributes(int, const QColor &, bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setStyleSheet(QStyleSheet *) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setTabStopWidth(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setText(const QString &, const QString &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setTextFormat(TextFormat) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setUnderline(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setUndoDepth(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setUndoRedoEnabled(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setVerticalAlignment(VerticalAlignment) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setWordWrap(WordWrap) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setWrapColumnOrWidth(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setWrapPolicy(WrapPolicy) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::sync() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::undo() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::zoomIn() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::zoomIn(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::zoomOut(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::zoomOut() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::zoomTo(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o QString QTimeEdit::sectionFormattedText(int) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setAutoAdvance(bool) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setHour(int) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setMaxValue(const QTime &) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setMinValue(const QTime &) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setMinute(int) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setRange(const QTime &, const QTime &) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setSecond(int) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setSeparator(const QString &) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setTime(const QTime &) \o Port to the new QDateTimeEdit API. +\row \o void QToolBar::clear() \o Setter. +\row \o void QToolBar::setLabel(const QString &) \o Setter. +\row \o void QToolBar::setStretchableWidget(QWidget *) \o Setter. +\row \o void QToolButton::setIconSet(const QIcon &) \o Setter. +\row \o void QToolButton::setOn(bool) \o Connect to QToolButton::toggled(bool) instead. +\row \o void QToolButton::setTextLabel(const QString &, bool) \o Setter. +\row \o void QToolButton::setToggleButton(bool) \o Setter. +\row \o void QToolButton::setUsesBigPixmap(bool) \o Setter. +\row \o void QToolButton::setUsesTextLabel(bool) \o Setter. +\row \o void QToolTip::maybeTip(const QPoint &) \o Port to the new QToolTip API. +\row \o void QUrl::addPath(const QString &) \o Value type. +\row \o bool QUrl::cdUp() \o Value type. +\row \o bool QUrl::parse(const QString &) \o Value type. +\row \o void QUrl::reset() \o Value type. +\row \o void QUrl::setEncodedPathAndQuery(const QString &) \o Value type. +\row \o void QUrl::setFileName(const QString &) \o Value type. +\row \o void QUrl::setHost(const QString &) \o Value type. +\row \o void QUrl::setPassword(const QString &) \o Value type. +\row \o void QUrl::setPath(const QString &) \o Value type. +\row \o void QUrl::setPort(int) \o Value type. +\row \o void QUrl::setProtocol(const QString &) \o Value type. +\row \o void QUrl::setQuery(const QString &) \o Value type. +\row \o void QUrl::setRef(const QString &) \o Value type. +\row \o void QUrl::setUser(const QString &) \o Value type. +\row \o QString QUrl::toString(bool, bool) const \o Value type. +\row \o QUrl::~QUrl() \o Value type. +\row \o QWaitCondition::~QWaitCondition() \o Value type. +\row \o bool QWhatsThis::clicked(const QString &) \o Port to the new QWhatsThis API. +\row \o QString QWhatsThis::text(const QPoint &) \o Port to the new QWhatsThis API. +\row \o QWhatsThis::~QWhatsThis() \o Port to the new QWhatsThis API. +\row \o void QWidget::adjustSize() \o Reimplement QWidget::sizeHint() instead. +\row \o bool QWidget::close(bool) \o Reimplement QWidget::closeEvent(). +\row \o void QWidget::create(WId, bool, bool) \o Not supported in Qt 4. +\row \o bool QWidget::customWhatsThis() const \o Not supported in Qt 4. +\row \o void QWidget::destroy(bool, bool) \o Not supported in Qt 4. +\row \o void QWidget::enabledChange(bool) \o Reimplement QWidget::changeEvent() and handle QEvent::EnabledChange. +\row \o void QWidget::fontChange(const QFont &) \o Reimplement QWidget::changeEvent() and handle QEvent::FontChange. +\row \o void QWidget::imComposeEvent(QIMEvent *) \o Reimplement QWidget::inputMethodEvent() instead. +\row \o void QWidget::imEndEvent(QIMEvent *) \o Reimplement QWidget::inputMethodEvent() instead. +\row \o void QWidget::imStartEvent(QIMEvent *) \o Reimplement QWidget::inputMethodEvent() instead. +\row \o void QWidget::move(int, int) \o Setter. +\row \o void QWidget::paletteChange(const QPalette &) \o Reimplement QWidget::changeEvent() and handle QEvent::PaletteChange and/or QEvent::ApplicationPaletteChange. +\row \o void QWidget::polish() \o Reimplement event() and handle the QEvent::Polish event type. +\row \o void QWidget::reparent(QWidget *, WFlags, const QPoint &, bool) \o Reimplement QWidget::event() and handle QEvent::Reparent. +\row \o void QWidget::resize(int, int) \o Reimplement QWidget::resizeEvent() instead. +\row \o void QWidget::setAcceptDrops(bool) \o Setter. +\row \o void QWidget::setActiveWindow() \o Reimplement QWidget::changeEvent() and handle QEvent::ActivationChange. +\row \o void QWidget::setAutoMask(bool) \o Setter. +\row \o void QWidget::setBackgroundColor(const QColor &) \o Setter. +\row \o void QWidget::setBackgroundMode(BackgroundMode) \o Setter. +\row \o void QWidget::setBackgroundOrigin(BackgroundOrigin) \o Setter. +\row \o void QWidget::setBackgroundPixmap(const QPixmap &) \o Setter. +\row \o void QWidget::setCaption(const QString &) \o Reimplement QWidget::changeEvent() and handle QEvent::WindowTitleChange. +\row \o void QWidget::setCursor(const QCursor &) \o Setter. +\row \o void QWidget::setEnabled(bool) \o Reimplement QWidget::changeEvent() and handle QEvent::EnabledChange. +\row \o void QWidget::setEraseColor(const QColor &) \o Setter. +\row \o void QWidget::setErasePixmap(const QPixmap &) \o Setter. +\row \o void QWidget::setFocus() \o Reimplement QWidget::focusInEvent() or QWidget::focusOutEvent(). +\row \o void QWidget::setFocusPolicy(FocusPolicy) \o Setter. +\row \o void QWidget::setFocusProxy(QWidget *) \o Setter. +\row \o void QWidget::setFont(const QFont &) \o Reimplement QWidget::changeEvent() and handle QEvent::FontChange and/or QEvent::ApplicationFontChange. +\row \o void QWidget::setGeometry(int, int, int, int) \o Setter. +\row \o void QWidget::setGeometry(const QRect &) \o Setter. +\row \o void QWidget::setIcon(const QPixmap &) \o Reimplement QWidget::changeEvent() and handle QEvent::WindowIconChange. +\row \o void QWidget::setIconText(const QString &) \o Reimplement QWidget::changeEvent() and handle QEvent::IconTextChange. +\row \o void QWidget::setKeyCompression(bool) \o Setter. +\row \o void QWidget::setMask(const QRegion &) \o Setter. +\row \o void QWidget::setMask(const QBitmap &) \o Setter. +\row \o void QWidget::setMaximumSize(int, int) \o Setter. +\row \o void QWidget::setMicroFocusHint(int, int, int, int, bool, QFont *) \o Setter. +\row \o void QWidget::setMinimumSize(int, int) \o Setter. +\row \o void QWidget::setMouseTracking(bool) \o Reimplement QWidget::changeEvent() and handle QEvent::MouseTrackingChange. +\row \o void QWidget::setPalette(const QPalette &) \o Reimplement QWidget::changeEvent() and handle QEvent::PaletteChange and/or QEvent::ApplicationPaletteChange. +\row \o void QWidget::setPaletteBackgroundColor(const QColor &) \o Setter. +\row \o void QWidget::setPaletteBackgroundPixmap(const QPixmap &) \o Setter. +\row \o void QWidget::setSizeIncrement(int, int) \o Setter. +\row \o void QWidget::setSizePolicy(QSizePolicy) \o Setter. +\row \o void QWidget::setUpdatesEnabled(bool) \o Setter. +\row \o void QWidget::setWFlags(WFlags) \o Setter. +\row \o void QWidget::show() \o Reimplement QWidget::showEvent(). +\row \o void QWidget::showMaximized() \o Reimplement QWidget::changeEvent() and handle QEvent::WindowStateChange. +\row \o void QWidget::showMinimized() \o Reimplement QWidget::changeEvent() and handle QEvent::WindowStateChange. +\row \o void QWidget::showNormal() \o Reimplement QWidget::changeEvent() and handle QEvent::WindowStateChange. +\row \o void QWidget::styleChange(QStyle &) \o Reimplement QWidget::changeEvent() and handle QEvent::StyleChange. +\row \o void QWidget::unsetCursor() \o Setter. +\row \o void QWidget::windowActivationChange(bool) \o Reimplement QWidget::changeEvent() and handle QEvent::ActivationChange. diff --git a/doc/src/porting/porting4-renamedclasses.qdocinc b/doc/src/porting/porting4-renamedclasses.qdocinc new file mode 100644 index 0000000..ef315a1 --- /dev/null +++ b/doc/src/porting/porting4-renamedclasses.qdocinc @@ -0,0 +1,3 @@ +\row \o QIconSet \o QIcon +\row \o QWMatrix \o QMatrix +\row \o QGuardedPtr \o QPointer diff --git a/doc/src/porting/porting4-renamedenumvalues.qdocinc b/doc/src/porting/porting4-renamedenumvalues.qdocinc new file mode 100644 index 0000000..9519da1 --- /dev/null +++ b/doc/src/porting/porting4-renamedenumvalues.qdocinc @@ -0,0 +1,234 @@ +\row \o IO_Append \o QIODevice::Append +\row \o IO_ReadOnly \o QIODevice::ReadOnly +\row \o IO_ReadWrite \o QIODevice::ReadWrite +\row \o IO_Translate \o QIODevice::Text +\row \o IO_Truncate \o QIODevice::Truncate +\row \o IO_WriteOnly \o QIODevice::WriteOnly +\row \o IO_Raw \o QIODevice::Unbuffered +\row \o QAccessible::Moveable \o QAccessible::Movable +\row \o QApplication::CustomColors \o QApplication::CustomColor +\row \o QApplication::NormalColors \o QApplication::NormalColor +\row \o QButton::NoChange \o QCheckBox::NoChange +\row \o QButton::Off \o QCheckBox::Off +\row \o QButton::On \o QCheckBox::On +\row \o QChar::Single \o QChar::NoDecomposition +\row \o QChar::byteOrderMark \o QChar::ByteOrderMark +\row \o QChar::byteOrderSwapped \o QChar::ByteOrderSwapped +\row \o QChar::nbsp \o QChar::Nbsp +\row \o QChar::null \o QChar::Null +\row \o QChar::replacement \o QChar::ReplacementCharacter +\row \o QComboBox::AfterCurrent \o QComboBox::InsertAfterCurrent +\row \o QComboBox::AtBottom \o QComboBox::InsertAtBottom +\row \o QComboBox::AtCurrent \o QComboBox::InsertAtCurrent +\row \o QComboBox::AtTop \o QComboBox::InsertAtTop +\row \o QComboBox::BeforeCurrent \o QComboBox::InsertBeforeCurrent +\row \o QComboBox::NoInsertion \o QComboBox::NoInsert +\row \o QDir::DefaultFilter \o QDir::NoFilter +\row \o QDir::DefaultSort \o QDir::NoSort +\row \o QEvent::Accel \o QEvent::Shortcut +\row \o QEvent::AccelOverride \o QEvent::ShortcutOverride +\row \o QEvent::CaptionChange \o QEvent::WindowTitleChange +\row \o QEvent::ChildInserted \o QEvent::ChildAdded +\row \o QEvent::IMCompose \o QEvent::InputMethodCompose +\row \o QEvent::IMEnd \o QEvent::InputMethodEnd +\row \o QEvent::IMStart \o QEvent::InputMethodStart +\row \o QEvent::IconChange \o QEvent::WindowIconChange +\row \o QEvent::LayoutHint \o QEvent::LayoutRequest +\row \o QEvent::Reparent \o QEvent::ParentChange +\row \o QFileInfo::ExeGroup \o QFile::ExeGroup +\row \o QFileInfo::ExeOther \o QFile::ExeOther +\row \o QFileInfo::ExeOwner \o QFile::ExeOwner +\row \o QFileInfo::ExeUser \o QFile::ExeUser +\row \o QFileInfo::ReadGroup \o QFile::ReadGroup +\row \o QFileInfo::ReadOther \o QFile::ReadOther +\row \o QFileInfo::ReadOwner \o QFile::ReadOwner +\row \o QFileInfo::ReadUser \o QFile::ReadUser +\row \o QFileInfo::WriteGroup \o QFile::WriteGroup +\row \o QFileInfo::WriteOther \o QFile::WriteOther +\row \o QFileInfo::WriteOwner \o QFile::WriteOwner +\row \o QFileInfo::WriteUser \o QFile::WriteUser +\row \o QFrame::GroupBoxPanel \o QFrame::StyledPanel +\row \o QFrame::LineEditPanel \o QFrame::StyledPanel +\row \o QFrame::MenuBarPanel \o QFrame::StyledPanel +\row \o QFrame::PopupPanel \o QFrame::StyledPanel +\row \o QFrame::TabWidgetPanel \o QFrame::StyledPanel +\row \o QFrame::ToolBarPanel \o QFrame::StyledPanel +\row \o QImage::ScaleFree \o Qt::IgnoreAspectRatio +\row \o QImage::ScaleMax \o Qt::KeepAspectRatioByExpanding +\row \o QImage::ScaleMin \o Qt::KeepAspectRatio +\row \o Qt::Identical \o QKeySequence::ExactMatch +\row \o Qt::NoMatch \o QKeySequence::NoMatch +\row \o Qt::PartialMatch \o QKeySequence::PartialMatch +\row \o QLayout::Auto \o QLayout::SetDefaultConstraint +\row \o QLayout::Fixed \o QLayout::SetFixedSize +\row \o QLayout::FreeResize \o QLayout::SetNoConstraint +\row \o QLayout::Minimum \o QLayout::SetMinimumSize +\row \o QMacStyle::SizeNone \o QMacStyle::SizeDefault +\row \o QSettings::Global \o QSettings::SystemScope +\row \o QSettings::User \o QSettings::UserScope +\row \o QSize::ScaleFree \o Qt::IgnoreAspectRatio +\row \o QSize::ScaleMax \o Qt::KeepAspectRatioByExpanding +\row \o QSize::ScaleMin \o Qt::KeepAspectRatio +\row \o QSizePolicy::Horizontal \o QSizePolicy::Horizontally +\row \o QSizePolicy::Vertical \o QSizePolicy::Vertically +\row \o QSlider::Above \o QSlider::TicksAbove +\row \o QSlider::Below \o QSlider::TicksBelow +\row \o QSlider::Both \o QSlider::TicksBothSides +\row \o QSlider::Left \o QSlider::TicksLeft +\row \o QSlider::NoMarks \o QSlider::NoTicks +\row \o QSlider::Right \o QSlider::TicksRight +\row \o QSocket::Closing \o Q3Socket::Closing +\row \o QSocket::Connected \o Q3Socket::Connected +\row \o QSocket::Connecting \o Q3Socket::Connecting +\row \o QSocket::Connection \o Q3Socket::Connection +\row \o QSocket::ErrConnectionRefused \o Q3Socket::ErrConnectionRefused +\row \o QSocket::ErrHostNotFound \o Q3Socket::ErrHostNotFound +\row \o QSocket::ErrSocketRead \o Q3Socket::ErrSocketRead +\row \o QSocket::HostLookup \o QAbstractSocket::HostLookupState +\row \o QSocket::Idle \o QAbstractSocket::UnconnectedState +\row \o QSqlError::Connection \o QSqlError::ConnectionError +\row \o QSqlError::None \o QSqlError::NoError +\row \o QSqlError::Statement \o QSqlError::StatementError +\row \o QSqlError::Transaction \o QSqlError::TransactionError +\row \o QSqlError::Unknown \o QSqlError::UnknownError +\row \o QStyle::CC_ListView \o QStyle::CC_Q3ListView +\row \o QStyle::SH_UnderlineAccelerator \o QStyle::SH_UnderlineShortcut +\row \o QStyle::Style_Active \o QStyle::State_Active +\row \o QStyle::Style_AutoRaise \o QStyle::State_AutoRaise +\row \o QStyle::Style_Bottom \o QStyle::State_Bottom +\row \o QStyle::Style_Children \o QStyle::State_Children +\row \o QStyle::Style_Default \o QStyle::State_None +\row \o QStyle::Style_Down \o QStyle::State_DownArrow +\row \o QStyle::Style_Editing \o QStyle::State_Editing +\row \o QStyle::Style_Enabled \o QStyle::State_Enabled +\row \o QStyle::Style_FocusAtBorder \o QStyle::State_FocusAtBorder +\row \o QStyle::Style_HasFocus \o QStyle::State_HasFocus +\row \o QStyle::Style_Horizontal \o QStyle::State_Horizontal +\row \o QStyle::Style_Item \o QStyle::State_Item +\row \o QStyle::Style_MouseOver \o QStyle::State_MouseOver +\row \o QStyle::Style_NoChange \o QStyle::State_NoChange +\row \o QStyle::Style_None \o QStyle::State_None +\row \o QStyle::Style_Off \o QStyle::State_Off +\row \o QStyle::Style_On \o QStyle::State_On +\row \o QStyle::Style_Open \o QStyle::State_Open +\row \o QStyle::Style_Raised \o QStyle::State_Raised +\row \o QStyle::Style_Rectangle \o QStyle::State_Rectangle +\row \o QStyle::Style_Selected \o QStyle::State_Selected +\row \o QStyle::Style_Sibling \o QStyle::State_Sibling +\row \o QStyle::Style_Sunken \o QStyle::State_Sunken +\row \o QStyle::Style_Top \o QStyle::State_Top +\row \o QStyle::Style_Up \o QStyle::State_Up +\row \o QTabBar::RoundedAbove \o QTabBar::RoundedNorth +\row \o QTabBar::RoundedBelow \o QTabBar:: RoundedSouth +\row \o QTabBar::TriangularAbove \o QTabBar:: TriangularNorth +\row \o QTabBar::TriangularBelow \o QTabBar:: TriangularSouth +\row \o QTextEdit::MovePgDown \o QTextEdit::MovePageDown +\row \o QTextEdit::MovePgUp \o QTextEdit::MovePageUp +\row \o QToolButton::Right \o QToolButton::BesideIcon +\row \o QToolButton::Under \o QToolButton::BelowIcon +\row \o QValidator::Valid \o QValidator::Intermediate +\row \o QVariant::IconSet \o QCoreVariant::Icon +\row \o QWidget::ClickFocus \o Qt::ClickFocus +\row \o QWidget::NoFocus \o Qt::NoFocus +\row \o QWidget::StrongFocus \o Qt::StrongFocus +\row \o QWidget::TabFocus \o Qt::TabFocus +\row \o QWidget::WheelFocus \o Qt::WheelFocus +\row \o Qt::AlignAuto \o Qt::AlignLeft +\row \o Qt::AltButton \o Qt::AltModifier +\row \o Qt::Ascending \o Qt::AscendingOrder +\row \o Qt::Bottom \o Qt::DockBottom +\row \o Qt::BottomLeft \o Qt::BottomLeftCorner +\row \o Qt::BottomRight \o Qt::BottomRightCorner +\row \o Qt::BreakAnywhere \o Qt::TextWrapAnywhere +\row \o Qt::ControlButton \o Qt::ControlModifier +\row \o Qt::CustomPattern \o Qt::TexturePattern +\row \o Qt::Descending \o Qt::DescendingOrder +\row \o Qt::DontClip \o Qt::TextDontClip +\row \o Qt::DontPrint \o Qt::TextDontPrint +\row \o Qt::ExpandTabs \o Qt::TextExpandTabs +\row \o Qt::IncludeTrailingSpaces \o Qt::TextIncludeTrailingSpaces +\row \o Qt::KeyButtonMask \o Qt::KeyboardModifierMask +\row \o Qt::Key_BackSpace \o Qt::Key_Backspace +\row \o Qt::Key_BackTab \o Qt::Key_Backtab +\row \o Qt::Key_MediaPrev \o Qt::Key_MediaPrevious +\row \o Qt::Key_Next \o Qt::Key_PageDown +\row \o Qt::Key_Prior \o Qt::Key_PageUp +\row \o Qt::Key_aacute \o Qt::Key_Aacute +\row \o Qt::Key_acircumflex \o Qt::Key_Acircumflex +\row \o Qt::Key_adiaeresis \o Qt::Key_Adiaeresis +\row \o Qt::Key_ae \o Qt::Key_AE +\row \o Qt::Key_agrave \o Qt::Key_Agrave +\row \o Qt::Key_aring \o Qt::Key_Aring +\row \o Qt::Key_atilde \o Qt::Key_Atilde +\row \o Qt::Key_ccedilla \o Qt::Key_Ccedilla +\row \o Qt::Key_eacute \o Qt::Key_Eacute +\row \o Qt::Key_ecircumflex \o Qt::Key_Ecircumflex +\row \o Qt::Key_ediaeresis \o Qt::Key_Ediaeresis +\row \o Qt::Key_egrave \o Qt::Key_Egrave +\row \o Qt::Key_eth \o Qt::Key_ETH +\row \o Qt::Key_iacute \o Qt::Key_Iacute +\row \o Qt::Key_icircumflex \o Qt::Key_Icircumflex +\row \o Qt::Key_idiaeresis \o Qt::Key_Idiaeresis +\row \o Qt::Key_igrave \o Qt::Key_Igrave +\row \o Qt::Key_ntilde \o Qt::Key_Ntilde +\row \o Qt::Key_oacute \o Qt::Key_Oacute +\row \o Qt::Key_ocircumflex \o Qt::Key_Ocircumflex +\row \o Qt::Key_odiaeresis \o Qt::Key_Odiaeresis +\row \o Qt::Key_ograve \o Qt::Key_Ograve +\row \o Qt::Key_oslash \o Qt::Key_Ooblique +\row \o Qt::Key_otilde \o Qt::Key_Otilde +\row \o Qt::Key_thorn \o Qt::Key_THORN +\row \o Qt::Key_uacute \o Qt::Key_Uacute +\row \o Qt::Key_ucircumflex \o Qt::Key_Ucircumflex +\row \o Qt::Key_udiaeresis \o Qt::Key_Udiaeresis +\row \o Qt::Key_ugrave \o Qt::Key_Ugrave +\row \o Qt::Key_yacute \o Qt::Key_Yacute +\row \o Qt::Keypad \o Qt::KeypadModifier +\row \o Qt::Left \o Qt::DockLeft +\row \o Qt::MV_10_DOT_0 \o QSysInfo::MV_10_0 +\row \o Qt::MV_10_DOT_1 \o QSysInfo::MV_10_1 +\row \o Qt::MV_10_DOT_2 \o QSysInfo::MV_10_2 +\row \o Qt::MV_10_DOT_3 \o QSysInfo::MV_10_3 +\row \o Qt::MV_10_DOT_4 \o QSysInfo::MV_10_4 +\row \o Qt::MV_9 \o QSysInfo::MV_9 +\row \o Qt::MV_CHEETAH \o QSysInfo::MV_10_0 +\row \o Qt::MV_JAGUAR \o QSysInfo::MV_10_2 +\row \o Qt::MV_PANTHER \o QSysInfo::MV_10_3 +\row \o Qt::MV_PUMA \o QSysInfo::MV_10_1 +\row \o Qt::MV_TIGER \o QSysInfo::MV_10_4 +\row \o Qt::MV_Unknown \o QSysInfo::MV_Unknown +\row \o Qt::MetaButton \o Qt::MetaModifier +\row \o Qt::Minimized \o Qt::DockMinimized +\row \o Qt::NoAccel \o Qt::TextHideMnemonic +\row \o Qt::Overline \o Qt::TextOverline +\row \o Qt::Right \o Qt::DockRight +\row \o Qt::ShiftButton \o Qt::ShiftModifier +\row \o Qt::ShowPrefix \o Qt::TextShowMnemonic +\row \o Qt::SingleLine \o Qt::TextSingleLine +\row \o Qt::StrikeOut \o Qt::TextStrikeOut +\row \o Qt::Top \o Qt::DockTop +\row \o Qt::TopLeft \o Qt::TopLeftCorner +\row \o Qt::TopRight \o Qt::TopRightCorner +\row \o Qt::TornOff \o Qt::DockTornOff +\row \o Qt::Underline \o Qt::TextUnderline +\row \o Qt::Unmanaged \o Qt::DockUnmanaged +\row \o Qt::WNorthWestGravity \o Qt::WStaticContents +\row \o Qt::WRepaintNoErase \o Qt::WNoAutoErase +\row \o Qt::WStyle_Dialog \o Qt::WType_Dialog +\row \o Qt::WStyle_NoBorderEx \o Qt::WStyle_NoBorder +\row \o Qt::WType_Modal \o (Qt::WType_Dialog | Qt::WShowModal) +\row \o Qt::WV_2000 \o QSysInfo::WV_2000 +\row \o Qt::WV_2003 \o QSysInfo::WV_2003 +\row \o Qt::WV_32s \o QSysInfo::WV_32s +\row \o Qt::WV_95 \o QSysInfo::WV_95 +\row \o Qt::WV_98 \o QSysInfo::WV_98 +\row \o Qt::WV_CE \o QSysInfo::WV_CE +\row \o Qt::WV_CENET \o QSysInfo::WV_CENET +\row \o Qt::WV_CE_based \o QSysInfo::WV_CE_based +\row \o Qt::WV_DOS_based \o QSysInfo::WV_DOS_based +\row \o Qt::WV_Me \o QSysInfo::WV_Me +\row \o Qt::WV_NT \o QSysInfo::WV_NT +\row \o Qt::WV_NT_based \o QSysInfo::WV_NT_based +\row \o Qt::WV_XP \o QSysInfo::WV_XP +\row \o Qt::WordBreak \o Qt::TextWordWrap +\row \o Qt::IbeamCursor \o Qt::IBeamCursor diff --git a/doc/src/porting/porting4-renamedfunctions.qdocinc b/doc/src/porting/porting4-renamedfunctions.qdocinc new file mode 100644 index 0000000..3e59a82 --- /dev/null +++ b/doc/src/porting/porting4-renamedfunctions.qdocinc @@ -0,0 +1,6 @@ +\row \o QRegExp::search() \o QRegExp::indexIn() +\row \o QPixmap::convertFromImage \o QPixmap::fromImage() (static function) +\row \o QStyle::querySubControl() \o QStyle::hitTestComplexControl() +\row \o QStyle::querySubControlMetrics() \o QStyle::subControlRect() +\row \o QStyle::unPolish() \o QStyle::unpolish() +\row \o QThread::currentThread() \o QThread::currentThreadId() diff --git a/doc/src/porting/porting4-renamedstatic.qdocinc b/doc/src/porting/porting4-renamedstatic.qdocinc new file mode 100644 index 0000000..156ab73 --- /dev/null +++ b/doc/src/porting/porting4-renamedstatic.qdocinc @@ -0,0 +1,3 @@ +\row \o QPixmap::fromMimeSource \o qPixmapFromMimeSource +\row \o QImage::inputFormats \o QImageReader::supportedImageFormats +\row \o QImage::outputFormats \o QImageWriter::supportedImageFormats diff --git a/doc/src/porting/porting4-renamedtypes.qdocinc b/doc/src/porting/porting4-renamedtypes.qdocinc new file mode 100644 index 0000000..fc8f604 --- /dev/null +++ b/doc/src/porting/porting4-renamedtypes.qdocinc @@ -0,0 +1,26 @@ +\row \o QApplication::ColorMode \o QApplication::ColorSpec +\row \o QButton::ToggleState \o QCheckBox::ToggleState +\row \o QCursorShape \o Qt::CursorShape +\row \o QFile::FilterSpec \o QFile::Filters +\row \o QFile::PermissionSpec \o QFile::Permission +\row \o QFile::SortSpec \o QFile::SortFlags +\row \o QFile::Status \o QFile::Error +\row \o QFileInfo::PermissionSpec \o QFile::Permission +\row \o QGrid::Direction \o Qt::Orientation +\row \o QGridWidget::Direction \o Qt::Orientation +\row \o QIODevice::Offset \o qlonglong +\row \o QImage::ScaleMode \o Qt::AspectRatioMode +\row \o QSize::ScaleMode \o Qt::AspectRatioMode +\row \o QSocket::Error \o Q3Socket::Error +\row \o QSocket::State \o Q3Socket::State +\row \o QStyle::SCFlags \o QStyle::SubControls +\row \o QStyle::SFlags \o QStyle::State +\row \o QTS \o QTextStream +\row \o QUrlDrag \o QUriDrag +\row \o QWidget::FocusPolicy \o Qt::FocusPolicy +\row \o Q_LLONG \o qlonglong +\row \o Q_ULLONG \o qulonglong +\row \o Qt::Dock \o Qt::ToolBarDock +\row \o Qt::MacintoshVersion \o QSysInfo::MacVersion +\row \o Qt::TextFlags \o Qt::TextFlag +\row \o Qt::WindowsVersion \o QSysInfo::WinVersion diff --git a/doc/src/porting/porting4.qdoc b/doc/src/porting/porting4.qdoc new file mode 100644 index 0000000..f4bcfcc --- /dev/null +++ b/doc/src/porting/porting4.qdoc @@ -0,0 +1,4244 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group porting + \title Porting Guides + \brief Guides related to porting Qt applications and libraries. + \ingroup best-practices + + A number of guides and documents are available that cover porting issues, + from detailed coverage of API differences between Qt 3 and Qt 4 to + platform and tool-specific documentation. + + \generatelist{related} +*/ + +/*! + \page porting4.html + \title Porting to Qt 4 + \contentspage {Porting Guides}{Contents} + \previouspage Porting Guides + \nextpage Porting to Qt 4 - Virtual Functions + \ingroup porting + \brief An overview of issues and techniques to consider when porting from Qt 3 to Qt 4. + +\omit + ### QFileInfo::PermissionSpec -> QFile::Permission(s?) + ### refer to porting4-renamedfunctions.qdoc + ### QApplication library mutex is gone + ### no integral conversion for containers? strings? + ### QVector etc. are initialized to 0 by default? + ### How to port from Qt 2.3 to Qt 4. + ### missing sort() functions? + ### QToolTipGroup + ### QServerSocket -> Q3ServerSocket + + ### remove these when the classes are re-ported + + ### QApplication::eventLoop() + + \row \o void QCheckListItem::paintCell(QPainter *, const QColorGroup &, int, int, int)\row \o void Q3CheckListItem::paintCell(QPainter *, const QPalette &, int, int, int) + \row \o void QCheckListItem::paintFocus(QPainter *, const QColorGroup &, const QRect &) \o void Q3CheckListItem::paintFocus(QPainter *, const QPalette &, const QRect &) + \row \o QDataTable: a whole bunch of virtual functions have a different signature + + < Function: void QIconViewItem::paintFocus(QPainter *, const QColorGroup &) + > Function: void QIconViewItem::paintFocus(QPainter *, const QPalette &) + + < Function: void QIconViewItem::paintItem(QPainter *, const QColorGroup &) + > Function: void QIconViewItem::paintItem(QPainter *, const QPalette &) + + < Function: bool QUrlOperator::checkValid() + + < Function: void QWSInputMethod::setFont(const QFont &) + + ### OpenMode or OpenMode + + ### QWSDecoration +\endomit + + This document describes the process of porting applications from + Qt 3 to Qt 4. + If you haven't yet made the decision about porting, or are unsure + about whether it is worth it, take a look at the \l{What's New in + Qt 4}{key features} offered by Qt 4. See also + \l{Moving from Qt 3 to Qt 4} for tips on how to write Qt 3 code + that is easy to port to Qt 4. + + \bold{Other porting guides:} + + \list + \o \l{Moving from Qt 3 to Qt 4} \mdash covers some high level topics relevant + to developers porting from Qt 3 to Qt 4. + \o \l{Porting to Qt 4 - Drag and Drop} \mdash covers differences in the + way drag and drop is handled between Qt 3 and Qt 4. + \o \l{Porting UI Files to Qt 4} \mdash describes the new format used to + describe forms created with \QD. + \o \l{Porting to Graphics View} \mdash provides a class-by-class overview + of the differences between Qt 3's canvas API and Qt 4's Graphics + View framework. + \o \l{qt3to4 - The Qt 3 to 4 Porting Tool} \mdash provides an overview + of a tool aimed at helping developers start the process of porting an + application to Qt 4. + \endlist + + The Qt 4 series is not binary compatible with the 3 series. This + means programs compiled for Qt 3 must be recompiled to work with + Qt 4. Qt 4 is also not completely \e source compatible with 3, + however nearly all points of incompatibility cause compiler + errors or run-time messages (rather than mysterious results). Qt + 4 includes many additional features and discards obsolete + functionality. Porting from Qt 3 to Qt 4 requires some effort, + but once completed the considerable additional power and + flexibility of Qt 4 is available for use in your applications. + + To port code from Qt 3 to Qt 4: + + \list 1 + + \o Briefly read the porting notes below to get an idea of what to expect. + + \o Be sure that your code compiles and runs well on all your target + platforms with Qt 3. + + \o Add the line \c{QT += qt3support} to your \c .pro file if you use + \c qmake; otherwise, edit your makefile or project file to + link against the Qt3Support library and add \c -DQT3_SUPPORT to your + compiler flags. (You might also need to specify other + libraries. See \l{What's New in Qt 4} for details.) + + \o Run the \l qt3to4 porting tool. The tool will go through your + source code and adapt it to Qt 4. + + \o Follow the instructions in the \l{Porting UI Files to Qt 4} + page to port Qt Designer files. + + \o Recompile with Qt 4. For each error, search below for related + identifiers (e.g., function names, class names). This document + mentions all relevant identifiers to help you get the information + you need at the cost of being a little verbose. + + \endlist + + The \l qt3to4 porting tool replaces occurrences of Qt 3 classes + that don't exist anymore in Qt 4 with the corresponding Qt 3 + support class; for example, \c QListBox is turned into \c + Q3ListBox. + + At some point, you might want to stop linking against the Qt 3 + support library (\l{Qt3Support}) and take advantage of Qt 4's + new features. The instructions below explain how to do that for + each compatibility class. + + In addition to the Qt3Support classes (such as \c Q3Action, \c + Q3ListBox, and \c Q3ValueList), Qt 4 provides compatibility + functions when it's possible for an old API to cohabit with the + new one. For example, QString provides a + QString::simplifyWhiteSpace() compatibility function that's + implemented inline and that simply calls QString::simplified(). + \bold{The compatibility functions are not documented here; instead, + they are documented for each class.} + + If you have the line \c{QT += qt3support} in your \c .pro file, \c + qmake will automatically define the \c QT3_SUPPORT symbol, turning + on compatibility function support. You can also define the symbol + manually (e.g., if you don't want to link against the \c + Qt3Support library), or you can define \c QT3_SUPPORT_WARNINGS + instead, telling the compiler to emit a warning when a + compatibility function is called. (This works only with GCC 3.2+ + and MSVC 7.) + + If you get stuck, ask on the + \l{http://qt.nokia.com/lists/qt-interest/}{qt-interest} + mailing list. If you are a licensed customer, you can also contact + Qt's technical support team. + +\omit + ### what to do with slots that aren't slots anymore + ### what to do with virtual functions that aren't virtual anymore + ### what to do with virtual functions that changed signature +\endomit + +\omit + ### <qtl.h> -- stuff that vanished? + ### implicit sharing + ### uint -> int indexes +\endomit + + Table of contents: + + \tableofcontents{4} + +\omit + \section1 Header Files + + ### New style of headers + + \table + \header \o Old header \o New header + \row \o \c{<qtl.h>} \o \c{<qalgorithms.h>} or \c{<QtAlgorithms>} + \endtable + + ### Some headers don't include each other anymore... +\endomit + + \section1 Casting and Object Types + + In Qt 3, it was possible to use the \c qt_cast() function to determine + whether instances of QObject subclasses could be safely cast to derived + types of those subclasses. For example, if a QFrame instance is passed + to a function whose signature specifies a QWidget pointer as its argument, + \c qt_cast() could be used to obtain a QFrame pointer so that the + instance's functions can be accessed. + + In Qt 4, much of this functionality is provided by the qobject_cast() + function, and additional functions also provide similar functionality for + certain non-QObject types: + + \table + \header \o Qt 3 function \o Qt 4 function + \row \o T *qt_cast<T *>(QObject *) \o \l{qobject_cast()}{T *qobject_cast<T *>(QObject *)} + \row \o \o \l{qgraphicsitem_cast()}{T qgraphicsitem_cast<T>(QGraphicsItem *)} + \row \o \o \l{qstyleoption_cast()}{T qstyleoption_cast<T>(QStyleOption *)} + \row \o \o \l{qvariant_cast()}{T qvariant_cast<T>(const QVariant &)} + \row \o \o \l{qdbus_cast()}{T qdbus_cast(const QDBusArgument &)} + \endtable + +\omit + \section1 Global Functions + + \table + \header \o Qt 3 function \o Qt 4 function + \row \o cstrcmp() \o strcmp() + \row \o cstrcpy() \o strcpy() + \row \o cstrlen() \o strlen() + \row \o cstrncmp() \o strncmp() + \row \o qmemmove() \o memmove() + \endtable + + qGLVersion() ### + + copyBlt() ### + bitBlt() + + #ifdef compat classes: + * QLayoutIterator + * QColorGroup + * QMenuItem + + QWidget visibleRect property compat + QWidget::BackgroundOrigin compat +\endomit + + \section1 Type Names + + The table below lists the classes that have been renamed in Qt 4. + If you compile your applications with \c QT3_SUPPORT defined, the + old names will be available. + + Whenever you see an occurrence of the name on the left, you can + safely replace it with the Qt 4 equivalent in your program. The + \l qt3to4 tool performs the conversion automatically. + + \table + \header \o Qt 3 class name \o Qt 4 class name + \input porting/porting4-renamedclasses.qdocinc + \endtable + + The table below lists the enums and typedefs that have been + renamed in Qt 4. If you compile your applications with \c + QT3_SUPPORT defined, the old names will be available. + + Whenever you see an occurrence of the name on the left, you can + safely replace it with the Qt 4 equivalent in your program. The + \l qt3to4 tool performs the conversion + automatically. + + \table + \header \o Qt 3 type name \o Qt 4 type name + \input porting/porting4-renamedtypes.qdocinc + \endtable + + \omit + ### + \row \o QButton::ToggleState \o Use QCheckBox::ToggleState instead. + \endomit + + \section1 Enum Values + + The table below lists the enum values that have been renamed in + Qt 4. If you compile your applications with \c QT3_SUPPORT defined, + the old names will be available. + + Whenever you see an occurrence of the name on the left, you can + safely replace it with the Qt 4 equivalent in your program. The + \l qt3to4 tool performs the conversion automatically. + + \table + \header \o Qt 3 enum value name \o Qt 4 enum value name + \input porting/porting4-renamedenumvalues.qdocinc + \endtable + + In addition, the following \l{Qt::WindowFlags}{window flags} have + been either replaced with \l{Qt::WidgetAttribute}{widget + attributes} or have been deprecated: + + \table + \header \o Qt 3 type \o Qt 4 equivalent + \row \o Qt::WDestructiveClose \o Use QWidget::setAttribute(Qt::WA_DeleteOnClose) instead. + \row \o Qt::WStaticContents \o{1,2} Use QWidget::setAttribute(Qt::WA_StaticContents) instead. + \row \o Qt::WNorthWestGravity + \row \o Qt::WNoAutoErase \o{1,3} Use QWidget::setAttribute(Qt::WA_NoBackground) instead. + \row \o Qt::WResizeNoErase + \row \o Qt::WRepaintNoErase + \row \o Qt::WPaintClever \o Unnecessary in Qt 4. + \omit ### Check with Matthias \endomit + \row \o Qt::WMacNoSheet \o Unnecessary in Qt 4. + \omit ### Check with Sam \endomit + \endtable + + In Qt 4.1, the widget flags used to determine window modality were + replaced by a single enum that can be used to specify the modal + behavior of top-level widgets: + + \table + \header \o Qt 3 type \o Qt 4 equivalent + \row \o Qt::WShowModal \o Use QWidget::setWindowModality(Qt::ApplicationModal) instead. + \row \o Qt::WGroupLeader \o Use QWidget::setWindowModality(Qt::WindowModal) + for each child dialog of the group leader, but do not change the modality + of the group leader itself. + \endtable + + \target properties + \section1 Properties + + Some properties have been renamed in Qt 4, to make Qt's API more + consistent and more intuitive. For example, QWidget's \c caption + property has been renamed \c windowTitle to make it clear that it + refers to the title shown in the window's title bar. + + In addition, the property system has been extended to allow + properties to be redefined in subclasses with the \l Q_PROPERTY() + macro, removing the need for a \c Q_OVERRIDE() macro. + + The table below lists the Qt properties that have been renamed in + Qt 4. Occurrences of these in \e{Qt Designer} UI files are + automatically converted to the new name by \c uic. + + \table + \header \o Qt 3 name \o Qt 4 name + \row \o QButton::accel \o QButton::shortcut + \row \o QButton::on \o QButton::checked + \row \o QButton::toggleButton \o QAbstractButton::checkable + \row \o QDial::lineStep \o QDial::singleStep + \row \o QDial::maxValue \o QDial::maximum + \row \o QDial::minValue \o QDial::minimum + \row \o QDialog::modal \o QDialog::isModal + \row \o QLineEdit::edited \o QLineEdit::modified + \row \o QLineEdit::hasMarkedText \o QLineEdit::hasSelectedText + \row \o QLineEdit::markedText \o QLineEdit::selectedText + \row \o QObject::name \o QObject::objectName + \row \o QProgressDialog::progress \o QProgressDialog::value + \row \o QProgressDialog::totalSteps \o QProgressDialog::maximum + \row \o QProgressDialog::wasCancelled \o QProgressDialog::wasCanceled + \row \o QPushButton::iconSet \o QPushButton::icon + \row \o QScrollBar::draggingSlider \o QScrollBar::sliderDown + \row \o QScrollBar::lineStep \o QScrollBar::singleStep + \row \o QScrollBar::maxValue \o QScrollBar::maximum + \row \o QScrollBar::minValue \o QScrollBar::minimum + \row \o QSlider::lineStep \o QSlider::singleStep + \row \o QSlider::maxValue \o QSlider::maximum + \row \o QSlider::minValue \o QSlider::minimum + \row \o QSpinBox::lineStep \o QSpinBox::singleStep + \row \o QSpinBox::maxValue \o QSpinBox::maximum + \row \o QSpinBox::minValue \o QSpinBox::minimum + \row \o QTabBar::currentTab \o QTabBar::currentIndex + \row \o QTabWidget::currentPage \o QTabWidget::currentWidget + \row \o QToolButton::iconSet \o QToolButton::icon + \row \o QToolButton::textLabel \o QToolButton::text + \row \o QWidget::caption \o QWidget::windowTitle + \row \o QWidget::icon \o QWidget::windowIcon + \row \o QWidget::iconText \o QWidget::windowIconText + \endtable + + A handful of properties in Qt 3 are no longer properties in Qt 4, + but the access functions still exist as part of the Qt 4 API. + These are not used by \e{Qt Designer}; the only case where you + need to worry about them is in highly dynamic applications that + use Qt's meta-object system to access properties. Here's the list + of these properties with the read and write functions that you + can use instead: + + \table + \header \o Qt 3 property \o Qt 4 read function \o Qt 4 write function + \row \o QSqlDatabase::connectOptions \o QSqlDatabase::connectOptions() \o QSqlDatabase::setConnectOptions() + \row \o QSqlDatabase::databaseName \o QSqlDatabase::databaseName() \o QSqlDatabase::setDatabaseName() + \row \o QSqlDatabase::hostName \o QSqlDatabase::hostName() \o QSqlDatabase::setHostName() + \row \o QSqlDatabase::password \o QSqlDatabase::password() \o QSqlDatabase::setPassword() + \row \o QSqlDatabase::port \o QSqlDatabase::port() \o QSqlDatabase::setPort() + \row \o QSqlDatabase::userName \o QSqlDatabase::userName() \o QSqlDatabase::setUserName() + \endtable + + Some properties have been removed from Qt 4, but the associated + access functions are provided if \c QT3_SUPPORT is defined to help + porting to Qt 4. When converting Qt 3 UI files to Qt 4, \c uic + generates calls to the Qt 3 compatibility functions. Note that + this only applies to the properties of the Qt3Support library, + i.e. \c QT3_SUPPORT properties of the other libraries must be + ported manually when converting Qt 3 UI files to Qt 4. + + The table below lists these properties with the read and write + functions that you can use instead. The documentation for the + individual functions explains how to replace them with + non-compatibility Qt 4 functions. + + \table + \header \o Qt 3 property \o Qt 4 read function (\c QT3_SUPPORT)\o Qt 4 write function (\c QT3_SUPPORT) + \row \o QMenuBar::separator \o QMenuBar::separator() \o QMenuBar::setSeparator() + \row \o QPushButton::menuButton \o QPushButton::isMenuButton() \o N/A + \row \o QTabWidget::margin \o QTabWidget::margin() \o QTabWidget::setMargin() + \row \o QTextEdit::textFormat \o QTextEdit::textFormat() \o QTextEdit::setTextFormat() + \row \o QWidget::backgroundBrush \o QWidget::backgroundBrush() \o N/A + \row \o QWidget::backgroundMode \o QWidget::backgroundMode() \o QWidget::setBackgroundMode() + \row \o QWidget::backgroundOrigin \o QWidget::backgroundOrigin() \o QWidget::setBackgroundOrigin() + \row \o QWidget::colorGroup \o QWidget::colorGroup() \o QWidget::setColorGroup() + \row \o QWidget::customWhatsThis \o QWidget::customWhatsThis() \o QWidget::setCustomWhatsThis() + \row \o QWidget::inputMethodEnabled \o QWidget::inputMethodEnabled() \o QWidget::setInputMethodEnabled() + \row \o QWidget::ownCursor \o QWidget::ownCursor() \o N/A + \row \o QWidget::ownFont \o QWidget::ownFont() \o N/A + \row \o QWidget::ownPalette \o QWidget::ownPalette() \o N/A + \row \o QWidget::paletteBackgroundColor \o QWidget::paletteBackgroundColor() \o QWidget::setPaletteBackgroundColor() + \row \o QWidget::paletteBackgroundPixmap \o QWidget::paletteBackgroundPixmap() \o QWidget::setPaletteBackgroundPixmap() + \row \o QWidget::paletteForegroundColor \o QWidget::paletteForegroundColor() \o QWidget::setPaletteForegroundColor() + \row \o QWidget::underMouse \o QWidget::underMouse() \o N/A + \endtable + + The following Qt 3 properties and their access functions are no + longer available in Qt 4. In most cases, Qt 4 provides similar + functionality. + + \table + \header \o Qt 3 property \o Qt 4 equivalent + \row \o QButton::autoRepeat \o N/A + \row \o QButton::autoResize \o Call QWidget:setFixedSize(QWidget::sizeHint()) whenever you change the contents. + \row \o QButton::exclusiveToggle \o See \l QAbstractButton::autoExclusive. + \row \o QButton::pixmap \o Use QAbstractButton::icon instead. + \row \o QButton::toggleState \o Use QCheckBox::setState() and QCheckBox::state() instead. + \row \o QButton::toggleType \o Use QCheckBox::setTristate() instead. + \row \o QComboBox::autoResize \o Call QWidget:setFixedSize(QWidget::sizeHint()) whenever you change the contents. + \row \o QFrame::contentsRect \o Use Q3Frame::contentsRect() instead. + \row \o QFrame::margin \o Use QWidget::setContentsMargins() instead. + \row \o QTabBar::keyboardFocusTab \o N/A + \row \o QToolButton::offIconSet \o Use the \l{QIcon::Off}{off component} of QAbstractButton::icon instead. + \row \o QToolButton::onIconSet \o Use the \l{QIcon::On}{on component} of QAbstractButton::icon instead. + \row \o QWidget::microFocusHint \o N/A + \row \o QMimeSource::serialNumber () \o N/A + \endtable + +\omit + \section1 Inheritance Chain + + ### QMenuBar, etc. + + \section1 Null vs. Empty + + ### +\endomit + + \section1 Explicit Sharing + + Qt 4 is the first version of Qt that contains no \link + http://qt.nokia.com/doc/3.3/shclass.html explicitly shared + \endlink classes. All classes that were explicitly shared in Qt 3 + are \e implicitly shared in Qt 4: + + \list + \o QImage + \o QBitArray + \o QByteArray + \o Q3PointArray + \endlist + + This means that if you took a copy of an instance of the class + (using operator=() or the class's copy constructor), any + modification to the copy would affect the original and vice + versa. Needless to say, this behavior is rarely desirable. + + Fortunately, nearly all Qt 3 applications don't rely on explicit + sharing. When porting, you typically only need to remove calls to + detach() and/or copy(), which aren't necessary anymore. + + If you deliberately rely on explicit sharing in your application, + you can use pointers or references to achieve the same result in + Qt 4. + + \oldcode + void asciify(QByteArray array) + { + for (int i = 0; i < (int)array.size(); ++i) { + if ((uchar)array[i] >= 128) + array[i] = '?'; + } + } + \newcode + void asciify(QByteArray &array) + { + for (int i = 0; i < array.size(); ++i) { + if ((uchar)array[i] >= 128) + array[i] = '?'; + } + } + \endcode + + (Notice the \c & in the parameter declaration.) + +\omit + \section1 Qt Designer UI Files + + ### +\endomit + + \section1 Painting and Redrawing Widgets + + When implementing custom widgets in Qt 3, it was possible to use + QPainter to draw on a widget outside paint events. This made it + possible to integrate Qt applications with third party libraries + and tools that impose their own rendering models. For example, + a widget might be repainted in a slot using data obtained from + an external source. + + In Qt 4, it is only possible to paint on a widget from within its + \l{QWidget::}{paintEvent()} handler function. This restriction simplifies + Qt's interaction with native window systems, improves the performance + of applications by reducing the number of redraw operations, and + also enables features to be implemented to improve the appearance of + widgets, such as a backing store. + + Generally, we recommend redesigning applications to perform all + painting operations in \l{QWidget::}{paintEvent()} functions, deferring + actual painting until the next time this function is called. + Applications can post paint events to trigger repaints, and it may be + possible to examine your widget's internal state to determine which + part of the widget needs to be repainted. + + If asynchronous repaints are used extensively by your application, + and it is not practical to redesign the rendering model to perform + all painting operations from within a widget's \l{QWidget::}{paintEvent()} + function, it may be necessary to consider using an intermediate painting + step. In this approach, one or more images can be updated asynchronously + and painted on the widget in the paint event. To avoid excessive + buffering, it may be worthwhile disabling the backing store by setting + the widget's Qt::WA_PaintOnScreen widget attribute. + + On certain platforms, the Qt::WA_PaintOutsidePaintEvent widget attribute + can be set to allow a widget to be painted from outside paint events. + + \note Setting widget attributes to disable key features of Qt's widget + rendering model may also cause other features to be disabled. + + \section1 Compatibility Signals and Slots + + When \c QT3_SUPPORT is defined, the default connection type for signals + and slots is the Qt::AutoCompatConnection type. This allows so-called + \e compatibility signals and slots (defined in Qt 3 support mode to provide + Qt 3 compatibility features) to be connected to other signals and + slots. + + However, if Qt is compiled with debugging output enabled, and the + developer uses other connection types to connect to compatibility + signals and slots (perhaps by building their application without Qt 3 + support enabled), then Qt will output warnings to the console to + indicate that compatibility connections are being made. This is intended + to be used as an aid in the process of porting a Qt 3 application to Qt 4. + + \section1 QAccel + + The \c QAccel class has been renamed Q3Accel and moved to the + Qt3Support module. In new applications, you have three options: + + \list 1 + \o You can use QAction and set a key sequence using QAction::setShortcut(). + \o You can use QShortcut, a class that provides similar + functionality to Q3Accel. + \o You can use QWidget::grabShortcut() and process "shortcut" + events by reimplementing QWidget::event(). + \endlist + + The Q3Accel class also supports multiple accelerators using the + same object, by calling Q3Accel::insertItem() multiple times. In + Qt 4, the solution is to create multiple QShortcut objects. + + \section1 QAccessibleInterface + + The QAccessibleInterface class has undergone some API changes in + Qt 4, to make it more consistent with the rest of the Qt API. + + If you have classes that inherit QAccessibleInterface or one of + its subclasses (QAccessibleObject, QAccessibleWidget, etc.), you + must port them the new QAccessibleInterface API. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} + for a list of QAccessibleInterface virtual member functions in + Qt 3 that are no longer virtual in Qt 4. + + \section1 QAccessibleTitleBar + + The \c QAccessibleTitleBar has been renamed Q3AccessibleTitleBar + and moved to the Qt3Support library. + + \target qaction.section + \section1 QAction + + The QAction class has been redesigned in Qt 4 to integrate better + with the rest of the menu system. It unifies the old \c QMenuItem + class and the old \c QAction class into one class, avoiding + unnecessary data duplication and the need to learn two different + APIs. + + The old \c QAction and \c QActionGroup classes have been renamed + Q3Action and Q3ActionGroup and moved to Qt3Support. In addition, + the new QAction class has compatibility functions to ease + transition to Qt 4. Note that when using Q3ToolBar and + Q3PopupMenu, their actions must be \l {Q3Action}s. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} + for a list of QAction virtual member functions in Qt 3 that are + no longer virtual in Qt 4. + + \section1 QActionGroup + + The QAction class has been completely redesigned in Qt 4 to + integrate better with the rest of the menu system. See the + \l{#qaction.section}{section on QAction} for details. + + \section1 QApplication + + The QApplication class has been split into two classes: + QCoreApplication and QApplication. The new QApplication class + inherits QCoreApplication and adds GUI-related functionality. In + practice, this has no consequences for existing Qt applications. + + In addition, the following API changes were made: + + \list 1 + \o QApplication::allWidgets() and QApplication::topLevelWidgets() + used to return a pointer to a QWidgetList. Now they return a + QWidgetList. + + Also, QWidgetList has changed from being a typedef for + QPtrList<QWidget> to being a typedef for QList<QWidget *>. + See the \l{#qwidgetlist.section}{section on QWidgetList} below + for details. + + \oldcode + QWidgetList *list = QApplication::topLevelWidgets(); + QWidgetListIt it(*list); + QWidget *widget; + while ((widget = it.current())) { + if (widget->inherits("MainWindow")) + ((MainWindow *)widget)->updateRecentFileItems(); + ++it; + } + delete list; + \newcode + QWidgetList list = QApplication::topLevelWidgets(); + for (int i = 0; i < list.size(); ++i) { + if (MainWindow *mainWin = qobject_cast<MainWindow *>(list.at(i))) + mainWin->updateRecentFileItems(); + } + \endcode + \o QApplication::setMainWidget() is no longer used. When all an application's + windows are closed, the application will exit normally. + \endlist + + \section1 QAquaStyle + + The \c QAquaStyle class first appeared in Qt 3.0, when the Qt for + Mac OS X port was first released. It emulated Apple's "Aqua" theme. + In Qt 3.1, QAquaStyle was obsoleted by QMacStyle, which uses Appearance + Manager to perform its drawing. + + The \c QAquaStyle class is no longer provided in Qt 4. Use + QMacStyle instead. + + \target qasciidict.section + \section1 QAsciiCache<T> + + \c QAsciiCache<T> has been renamed Q3AsciiCache<T> and moved to + the Qt3Support library. It has been replaced by + QCache<QByteArray, T>. + + For details, read the \l{#qcache.section}{section on QCache<T>}, + mentally substituting QByteArray for QString. + + \section1 QAsciiDict<T> + + QAsciiDict<T> and QAsciiDictIterator<T> have been renamed + Q3AsciiDict<T> and Q3AsciiDictIterator<T> and moved to the + Qt3Support library. They have been replaced by the + more modern QHash<Key, T> and QMultiHash<Key, T> classes and + their associated iterator classes. + + When porting old code that uses Q3AsciiDict<T> to Qt 4, there are + four classes that you can use: + + \list + \o QMultiHash<QByteArray, T *> + \o QMultiHash<QByteArray, T> + \o QHash<QByteArray, T *> + \o QHash<QByteArray, T> + \endlist + + For details, read the \l{#qdict.section}{section on QDict<T>}, + mentally substituting QByteArray for QString. + + \section1 QAsyncIO + + The \c QAsyncIO class was used internally in Qt 2.x in + conjunction with QImageConsumer. It was obsoleted in Qt 3.0. + + \input porting/porting4-obsoletedmechanism.qdocinc + + \section1 QBackInsertIterator + + The undocumented \c QBackInsertIterator class has been removed + from the Qt library. If you need it in your application, feel + free to copy the source code from the Qt 3 \c <qtl.h> header + file. + + \section1 QBitArray + + In Qt 3, QBitArray inherited from QByteArray. In Qt 4, QBitArray + is a totally independent class. This makes very little difference + to the user, except that the new QBitArray doesn't provide any of + QByteArray's byte-based API anymore. These calls will result in a + compile-time error, except calls to QBitArray::truncate(), whose + parameter was a number of \e bytes in Qt 3 and a number of bits + in Qt 4. + + QBitArray was an explicitly shared class in Qt 3. See \l{Explicit + Sharing} for more information. + + The \c QBitVal class has been renamed QBitRef. + + \section1 QButton + + The \c QButton class has been replaced by QAbstractButton in Qt + 4. Classes like QPushButton and QRadioButton inherit from + QAbstractButton. As a help when porting older Qt applications, + the Qt3Support library contains a Q3Button class + implemented in terms of the new QAbstractButton. + + If you used the \c QButton class as a base class for your own + button type and want to port your code to the newer + QAbstractButton, you need to be aware that QAbstractButton has no + equivalent for the Q3Button::drawButton(QPainter *) virtual + function. The solution is to reimplement QWidget::paintEvent() in + your QAbstractButton subclass as follows: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 0 + + \table + \header \o Q3Button function \o QAbstractButton equivalent + \row \o Q3Button::autoResize() \o Call QWidget:setFixedSize(QWidget::sizeHint()) whenever you change the contents. + \row \o Q3Button::isExclusiveToggle() \o Use QAbstractButton::group() or QAbstractButton::autoExclusive() instead. + \row \o Q3Button::pixmap() const \o QAbstractButton::icon() + \row \o Q3Button::setAutoResize() \o N/A + \row \o Q3Button::setPixmap(const QPixmap &) \o QAbstractButton::setIcon(const QIcon &) + \row \o Q3Button::setState(ToggleState) \o See remark below + \row \o Q3Button::setToggleType(ToggleType) \o See remark below + \row \o Q3Button::state() \o See remark below + \row \o Q3Button::stateChanged(int) \o See remark below + \row \o Q3Button::toggleType() \o See remark below + \endtable + + Remarks: + + \list 1 + \o In Qt 3, \c QButton had a "toggle type", which could be + QButton::SingleShot, QButton::Toggle, or QButton::Tristate. + The new QAbstractButton class doesn't support "tristate" + directly; this feature is implemented in QCheckBox instead. + The two other "toggle types" (\c QButton::SingleShot and \c + QButton::Toggle) are replaced by a QAbstractButton::checkable + property. + \o In Qt 3, QButton had a "toggle state", which could be \c + QButton::Off, \c QButton::NoChange, or \c QButton::On. In Qt + 4, this mechanism has been moved to QCheckBox. + \endlist + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of \c QButton virtual member functions in Qt 3 that aren't + virtual in Qt 4. + + See \l{#properties}{Properties} for a list of \c QButton properties + in Qt 3 that have changed in Qt 4. + + \section1 QButtonGroup + + The \c QButtonGroup class has been completely redesigned in Qt 4. + For compatibility, the old \c QButtonGroup class has been renamed + Q3ButtonGroup and has been moved to Qt3Support. + Likewise, the \c QHButtonGroup and \c QVButtonGroup convenience + subclasses have been renamed \c Q3HButtonGroup and \c Q3VButtonGroup and + moved to the Qt3Support library. + + The old \c QButtonGroup, as well as Q3ButtonGroup, can be used in two ways: + + \list 1 + \o The button group is the parent widget of a number of buttons, + i.e. the button group is the parent argument in the button + constructor. The buttons are assigned identifiers 0, 1, 2, etc., + in the order they are created. A Q3ButtonGroup can display a frame + and a title because it inherits Q3GroupBox. + \o The button group is an invisible widget and the contained + buttons have some other parent widget. In this usage, each + button must be manually inserted, using + Q3ButtonGroup::insert(), into the button group and given an + ID number. + \endlist + + Unlike Q3ButtonGroup, the new QButtonGroup doesn't inherit + QWidget. It is very similar to a "hidden Q3ButtonGroup". + + If you use a Q3ButtonGroup, Q3HButtonGroup, or Q3VButtonGroup as + a widget and want to port to Qt 4, you can replace it with + QGroupBox. In Qt 4, radio buttons with the same parent are + automatically part of an exclusive group, so you normally don't + need to do anything else. See also the + \l{#qgroupbox.section}{section on QGroupBox} below. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QButtonGroup virtual member functions in Qt 3 that are no + longer virtual in Qt 4. + + \target qbytearray.section + \section1 QByteArray + + In Qt 3, QByteArray was simply a typedef for QMemArray<char>. In + Qt 4, QByteArray is a class in its own right, with a higher-level + API in the style of QString. + + Here are the main issues to be aware of when porting to Qt 4: + + \list 1 + \o The QMemArray(int size) constructor has been replaced with + QByteArray(int size, char ch). The second argument specifies + which character should be used for initializing the array; + pass '\\0' if you have no specific needs. + + \oldcode + QByteArray ba(64); + \newcode + QByteArray ba(64, '\0'); + \endcode + + \o QMemArray::at() returned a non-const reference, whereas the + new QByteArray::at() returns a const value. Code like + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 1 + + will no longer compile. Instead, use QByteArray::operator[]: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 2 + + \o The QMemArray::contains(char) function has been renamed + QByteArray::count(char). In addition, there now exists a + QByteArray::contains(char) function that returns a boolean + value. Replace old calls to contains() with either count() or + contains(), depending on whether you care about the specific + number of occurrences of a character in the byte array or + only care about whether the array contains that character or + not. + + \o The new QByteArray has no assign() function. Calls to + QMemArray::assign(const QMemArray &) can be replaced by calls + to QByteArray::operator=(). Calls to QMemArray::assign(const + T *, uint) have no equivalent in Qt 4; if you use it, the + solution is either to use QByteArray::fromRawData() and to + call free() yourself to avoid a memory leak, or to use the + QByteArray(const char *, int) constructor, which will take a + deep copy of the data. + + \o QMemArray::bsearch() and QMemArray::sort() have no equivalent + in the new QByteArray class. Use \l qBinaryFind() and \l qSort() + if you need that functionality. + \endlist + + QByteArray was an explicitly shared class in Qt 3. See + \l{Explicit Sharing} for more information. + + \target qcache.section + \section1 QCache<T> + + QCache<T> has been renamed Q3Cache<T> and moved to Qt3Support. + The new QCache class has a different API, and takes different + template parameters: QCache<Key, T>. + + When porting to Qt 4, QCache<QString, T> is the obvious + substitute for Q3Cache<T>. The following table summarizes the API + differences. + + \table + \header \o Q3Cache<T> function \o QCache<QString, T> equivalent + \row \o Q3Cache::Q3Cache(int maxCost, int size, bool caseSensitive) \o See remark below + \row \o Q3Cache::autoDelete() \o N/A + \row \o Q3Cache::count() \o QCache::count() or QCache::size() (equivalent) + \row \o Q3Cache::setAutoDelete() \o See remark below + \row \o Q3Cache::size() \o N/A + \row \o Q3Cache::statistics() \o N/A + \row \o Q3Cache::operator=() \o See remark below + \endtable + + Remarks: + + \list 1 + \o Q3Cache requires the user to allocate a specific number of + buckets by passing a prime number (17 by default) to the + constructor. In contrast, the new QCache's hash table + automatically grows and shrinks as needed, and the + constructor doesn't take a prime number. + + \o Q3Cache supportes case-insensitive lookups by passing false as + second argument to the constructor. This feature has no + equivalent in QMultiHash. Instead, call QString::toLower() + before you insert or lookup a key in the hash. + + \o The Q3Cache::insert() function returns a \c bool value that + indicates whether or not the item actually was inserted in + the cache. If the item wasn't inserted, it was the caller's + responsibility to delete the item. The new QCache::insert() + function returns \c void and either adds it to the cache or + deletes it right away. Old code like + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 3 + + becomes + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 4 + + \o The new QCache class \e always takes ownership of the items + it stores (i.e. auto-delete is always on). If you use Q3Cache + with auto-delete turned off (the rarely useful default), you + cannot use QCache as a direct substitute. One unelegant trick + that works well in practice is to use QCache<QString, T *> + instead of QCache<QString, T>. In that case, QCache owns the + pointers, not the objects that the pointers refer to. For + example, + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 5 + + becomes + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 6 + + An alternative is to stick to using Q3Cache. + \endlist + + QCacheIterator<T> has been renamed Q3CacheIterator<T> and moved + to the Qt3Support library. The new QCache class + doesn't offer any iterator types. + + \section1 QCanvas + + The canvas module classes have been + renamed and moved to the Qt3Support library. + + \table + \header \o Qt 3 class name \o Compatibility class in Qt 4 + \row \o \c QCanvas \o Q3Canvas + \row \o \c QCanvasEllipse \o Q3CanvasEllipse + \row \o \c QCanvasItem \o Q3CanvasItem + \row \o \c QCanvasItemList \o Q3CanvasItemList + \row \o \c QCanvasLine \o Q3CanvasLine + \row \o \c QCanvasPixmap \o Q3CanvasPixmap + \row \o \c QCanvasPixmapArray \o Q3CanvasPixmapArray + \row \o \c QCanvasPolygon \o Q3CanvasPolygon + \row \o \c QCanvasPolygonalItem \o Q3CanvasPolygonalItem + \row \o \c QCanvasRectangle \o Q3CanvasRectangle + \row \o \c QCanvasSpline \o Q3CanvasSpline + \row \o \c QCanvasSprite \o Q3CanvasSprite + \row \o \c QCanvasText \o Q3CanvasText + \row \o \c QCanvasView \o Q3CanvasView + \endtable + + \l{The Graphics View Framework} replaces QCanvas. For more on porting to + Graphics View, see \l{Porting to Graphics View}. + + \section1 QColor + + In Qt 4, QColor is a value type like QPoint or QRect. Graphics + system-specific code has been implemented in QColormap. + + The \c QColor::maxColors() function has been replaced + by QColormap::size(). + + The \c QColor::numBitPlanes() function has been replaced + by QColormap::depth(). + + The \c QColor::setNamedColor() function no longer supports + the named color in the same way as Qt 3. Qt 4's + \l{QColor::}{setNamedColor()} uses the new W3C convention + as stated + \l{http://www.w3.org/TR/SVG/types.html#ColorKeywords}{here}. + + \table + \header \o{4,1} Predefined Qt Colors + \row \o Qt::color0 \o Qt::color1 \o Qt::black \o Qt::white + \row \o Qt::darkGray \o Qt::gray \o Qt::lightGray \o Qt::red + \row \o Qt::green \o Qt::blue \o Qt::cyan \o Qt::magenta + \row \o Qt::yellow \o Qt::darkRed \o Qt::darkGreen \o Qt::darkBlue + \row \o Qt::darkCyan \o Qt::darkMagenta \o Qt::darkYellow \o Qt::transparent + \endtable + + The predefined colors listed in the table above were static + QColor objects in Qt 3. In Qt 4, they are enum values of type + Qt::GlobalColor. Thanks to the implicit QColor(Qt::GlobalColor) + constructor, the enum values are automatically converted to + \l{QColor}s in most contexts. Occasionally, you might need a + cast. + + \oldcode + QColor lightCyan = Qt::cyan.light(180); + \newcode + QColor lightCyan = QColor(Qt::cyan).light(180); + \endcode + + \section1 QColorGroup + + In Qt 3, a QPalette consisted of three QColorGroup objects. In Qt + 4, the (rarely used) QColorGroup abstraction has been eliminated. + For source compatibility, a QColorGroup class is available when + \c QT3_SUPPORT is defined. + + The new QPalette still works in terms of color groups, specified + through enum values (QPalette::Active, QPalette::Disabled, and + QPalette::Inactive). It also has the concept of a \e current + color group, which you can set using + QPalette::setCurrentColorGroup(). + + The QPalette object returned by QWidget::palette() returns a + QPalette initialized with the correct current color group for the + widget. This means that if you had code like + + \badcode + painter.setBrush(colorGroup().brush(QColorGroup::Text)); + \endcode + + you can simply replace colorGroup() with palette(): + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 7 + + \section1 QColorDrag + + The \c QColorDrag class has been renamed Q3ColorDrag and moved to + the Qt3Support library. In Qt 4, use QMimeData + instead and call QMimeData::setColor() to set the color. + + \section1 QComboBox + + In Qt 3, the list box used to display the contents of a \c QComboBox + widget could be accessed by using the \c listBox() function. In Qt 4, + the standard list box is provided by a QListView widget, and can be + accessed with the \l{QComboBox::view()}{view()} function. + + \omit ### \endomit + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QComboBox virtual member functions in Qt 3 that are no longer + virtual in Qt 4. + + \section1 QCString + + In Qt 3, QCString inherited from QByteArray. The main drawback + of this approach is that the user had the responsibility of + ensuring that the string is '\\0'-terminated. Another important + issue was that conversions between \c QCString and QByteArray often + gave confusing results. (See the + \l{http://qt.nokia.com/doc/qq/qq05-achtung.html#qcstringisastringofchars}{Achtung! + Binary and Character Data} article in \e{Qt Quarterly} for an + overview of the pitfalls.) + + Qt 4 solves that problem by merging the QByteArray and \c QCString + classes into one class called QByteArray. Most functions that + were in \c QCString previously have been moved to QByteArray. The + '\\0' issue is handled by having QByteArray allocate one extra + byte that it always sets to '\\0'. For example: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 8 + + The Qt3Support library contains a class called + Q3CString that inherits from the new QByteArray class and that + extends it to provide an API that is as close to the old \c QCString + class as possible. Note that the following functions aren't + provided by Q3CString: + + \list + \o QCString::find(const QRegExp &, int) + \o QCString::findRev(const QRegExp &, int) + \o QCString::contains(const QRegExp &) + \o QCString::replace(const QRegExp &, const char *) + \endlist + + The following functions have lost their last parameter, which + specified whether the search was case sensitive or not: + + \list + \o QByteArray::find(char, int) + \o QByteArray::find(const char *, int) + \o QByteArray::findRev(char, int) + \o QByteArray::findRev(const char *, int) + \o QByteArray::contains(char) + \o QByteArray::contains(const char *) + \endlist + + In both cases, the solution is to convert the \c QCString to a + QString and use the corresponding QString functions instead. + + Also be aware that \c QCString::size() (inherited from + QByteArray) used to return the size of the character data \e + including the '\\0'-terminator, whereas the new + QByteArray::size() is just a synonym for QByteArray::length(). + This brings QByteArray in line with QString. + + When porting to Qt 4, occurrences of \c QCString should be + replaced with QByteArray or QString. The following table + summarizes the API differences between the Q3CString + class and the Qt 4 QByteArray and QString classes: + + \table + \header \o Q3CString function \o Qt 4 equivalent + \row \o Q3CString::Q3CString(const char *, uint) \o See remark below + \row \o Q3CString::Q3CString(int) \o QByteArray::QByteArray(int, char) + \row \o Q3CString::leftJustify() \o QString::leftJustified() + \row \o Q3CString::length() \o QByteArray::length() or QByteArray::size() (equivalent) + \row \o Q3CString::lower() \o QByteArray::toLower() + \row \o Q3CString::rightJustify() \o QString::rightJustified() + \row \o Q3CString::setExpand() \o See remark below + \row \o Q3CString::simplifyWhiteSpace() \o QByteArray::simplified() + \row \o Q3CString::sprintf() \o QString::sprintf() + \row \o Q3CString::stripWhiteSpace() \o QByteArray::trimmed() + \row \o Q3CString::toDouble() \o QString::toDouble() + \row \o Q3CString::toFloat() \o QString::toFloat() + \row \o Q3CString::toInt() \o QString::toInt() + \row \o Q3CString::toLong() \o QString::toLong() + \row \o Q3CString::toShort() \o QString::toShort() + \row \o Q3CString::toUInt() \o QString::toUInt() + \row \o Q3CString::toULong() \o QString::toULong() + \row \o Q3CString::toUShort() \o QString::toUShort() + \row \o Q3CString::upper() \o QByteArray::toUpper() + \endtable + + Remarks: + + \list 1 + \o Q3CString(const char *str, uint max) constructs a string of + length strlen(str) or \e max - 1, whichever is shorter. + QByteArray(const char *data, int size) constructs a byte + array containing exactly \e size bytes. + + \oldcode + QCString str1("Hello", 4); // "Hel" + QCString str2("Hello world!", n); + \newcode + QByteArray str1("Hello", 3); + QByteArray str2("Hello world!"); + str2.truncate(n - 1); + \endcode + + \o Q3CString::setExpand(uint index, char ch) has no equivalent in + Qt 4. + + \oldcode + QCString str("Hello world"); + str.setExpand(16, '\n'); // "Hello world \n" + \newcode + QByteArray str("Hello world"); + while (str.size() < 16) + str += ' '; + str += '\n'; + \endcode + \endlist + + Since the old \c QCString class inherited from QByteArray, + everything that is said in the \l{#qbytearray.section}{QByteArray + section} applies for \c QCString as well. + + \section1 QCustomEvent + + In Qt 3, developers could create a custom event by constructing + a new QCustomEvent, and send relevant data to other components in + the application by passing a void pointer, either on construction or + using the setData() function. Objects could receive custom events + by reimplementing the \l{QObject::customEvent()}{customEvent()} + function, and access the stored data using the event's data() + function. + + In Qt 4, custom events are created by subclassing + QEvent. Event-specific data can be stored in a way that is + appropriate for your application. Custom events are still + delivered to each object's + \l{QObject::customEvent()}{customEvent()} handler function, but as + QEvent objects rather than as deprecated QCustomEvent objects. + + \section1 QDataBrowser + + The \c QDataBrowser class has been renamed Q3DataBrowser and + moved to the Qt3Support library. In Qt 4.2, you should use the + QDataWidgetMapper class to create data-aware forms. + + See \l{QtSql Module} for an overview of the new SQL + classes. + + \section1 QDataPump + + The \c QDataPump class was used internally in Qt 2.x in + conjunction with QImageConsumer. It was obsoleted in Qt 3.0. + + \input porting/porting4-obsoletedmechanism.qdocinc + + \section1 QDataSink + + The \c QDataSink class was used internally in Qt 2.x in conjunction + with QImageConsumer. It was obsoleted in Qt 3.0. + + \input porting/porting4-obsoletedmechanism.qdocinc + + \section1 QDataSource + + The \c QDataSource class was used internally in Qt 2.x in + conjunction with QImageConsumer. It was obsoleted in Qt 3.0. + \input porting/porting4-obsoletedmechanism.qdocinc + + \section1 QDataTable + + The \c QDataTable class has been renamed Q3DataTable and moved to + the Qt3Support library. In Qt 4.2, you should use the + QDataWidgetMapper class to create data-aware forms. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QDataView + + The \c QDataView class has been renamed Q3DataView and moved to + the Qt3Support library. In Qt 4.2, you should use the + QDataWidgetMapper class to create data-aware forms. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QDateEdit + + The QDateEdit class in Qt 4 is a convenience class based on + QDateTimeEdit. The old class has been renamed Q3DateEdit and moved + to the Qt3Support library. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of \c QDateEdit virtual member functions in Qt 3 that are + no longer virtual in Qt 4. + + \section1 QDateTimeEditBase + + The \c QDateTimeEditBase class has been renamed + Q3DateTimeEditBase and moved to Qt3Support. Use QDateTimeEdit or + QAbstractSpinBox instead. + + \section1 QDateTimeEdit + + The old \c QDateTimeEdit class has been renamed + Q3DateTimeEditBase and moved to Qt3Support. The new QDateTimeEdit + in Qt 4 has been rewritten from scratch to provide a more + flexible and powerful API. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QDateTimeEdit virtual member functions in Qt 3 that are no + longer virtual in Qt 4. + + \section1 QDeepCopy<T> + + The \c QDeepCopy<T> class in Qt 3 provided a means of ensuring that + implicitly shared and explicitly shared classes referenced unique + data. This was necessary because the reference counting in Qt's + container classes was done in a thread-unsafe manner. + + With Qt 4, \c QDeepCopy<T> has been renamed Q3DeepCopy<T> and + moved to the Qt3Support library. Removing it from + existing code is straightforward. + + \oldcode + QString str1 = "I am a string"; + QDeepCopy<QString> str2 = str1; + QString str3 = QDeepCopy<QString>(str2); + \newcode + QString str1 = "I am a string"; + QString str2 = str1; + QString str3 = str2; + \endcode + + \section1 QDial + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QDial virtual member functions in Qt 3 that are no longer + virtual in Qt 4. + + See \l{#properties}{Properties} for a list of QDial properties in + Qt 3 that have changed in Qt 4. + + \target qdict.section + \section1 QDict<T> + + \c QDict<T> has been renamed Q3Dict<T> and moved to Qt3Support. + It has been replaced by the more modern QHash<Key, T> and + QMultiHash<Key, T> classes. + + When porting old code that uses QDict<T> to Qt 4, there are four + classes that you can use: + + \table + \header \o Qt 4 class \o When to use it + \row \o QMultiHash<QString, T *> + + \o Since Q3Dict<T> is pointer-based and allows duplicate + keys, this is usually the most straightforward conversion. + + \row \o QMultiHash<QString, T> + + \o If type \c T is an \l{assignable data type}, you can use + \c T as the value type rather than \c{T *}. This often + leads to nicer code. + + \row \o QHash<QString, T *> + + \o{1,2} If you don't use duplicate keys, you can use QHash + instead of QMultiHash. QMultiHash inherits from QHash. + + \row \o QHash<QString, T> + \endtable + + The APIs of Q3Dict<T> and QMultiHash<QString, T *> are quite + similar. The main issue is that Q3Dict supports auto-delete + whereas QMultiHash doesn't. + + \omit + (See \l{What's Wrong with + Auto-Delete} for an explanation of why the Qt 4 containers don't + offer that feature.) + \endomit + + The following table summarizes the API differences between the + two classes: + + \table + \header \o Q3Dict function \o QMultiHash equivalent + \row \o Q3Dict::Q3Dict(int size, bool caseSensitive) \o See remarks below + \row \o Q3Dict::autoDelete() \o N/A + \row \o Q3Dict::count() \o QMultiHash::count() or QMultiHash::size() (equivalent) + \row \o Q3Dict::find(const QString &) \o QMultiHash::value(const QString &) + \row \o Q3Dict::remove(const QString &) \o QMultiHash::take(const QString &) + \row \o Q3Dict::resize(uint) \o QMultiHash::reserve(int) + \row \o Q3Dict::setAutoDelete() \o See discussion below + \row \o Q3Dict::size() \o QMultiHash::capacity() + \row \o Q3Dict::statistics() \o N/A + \row \o Q3Dict::operator[](const QString &) \o See remark below + \endtable + + Remarks: + + \list 1 + \o Q3Dict requires the user to allocate a specific number of + buckets by passing a prime number (17 by default) to the + constructor and/or calling Q3Dict::resize() later on. In + contrast, QMultiHash's hash table automatically grows and + shrinks as needed, and the constructor doesn't take a prime + number. + + \o Q3Dict supportes case-insensitive lookups by passing false as + second argument to the constructor. This feature has no + equivalent in QMultiHash. Instead, call QString::toLower() + before you insert or lookup a key in the hash. + + \o Q3Dict::size() and QMultiHash::size() have different semantics. + The former returns the number of buckets in the container, whereas + the latter returns the number of \e items in the container. + + \o If there are multiple items with the same key, + Q3Dict::remove() removes only the most recently inserted item, + whereas QMultiHash::remove() removes all items that share a + particular key. To remove only the most recently inserted item, + call QMultiHash::take(). + + \o Q3Dict has only one [] operator (Q3Dict::operator[]()), + providing const access to an item's value. QMultiHash also + has a non-const overload that can be used on the left side of + the assignment operator. If you use the [] operator on a + non-const QHash with an unexisting item, QHash will created + an element and initialize it to be a null pointer. For that + reason, Q3Dict::operator[] should be converted to + QMultiHash::value(), not QMultiHash::operator[]. + + \endlist + + If you use Q3Dict's auto-delete feature (by calling + Q3Dict::setAutoDelete(true)), you need to do some more work. You + have two options: Either you call \c delete yourself whenever you + remove an item from the container, or you use + QMultiHash<QString, T> instead of QMultiHash<QString, T *> (i.e. + store values directly instead of pointers to values). Here, we'll + see when to call \c delete. + + The following table summarizes the idioms that you need to watch + out for if you want to call \c delete yourself. + + \table + \header \o Q3Dict idiom \o QMultiHash idiom + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 9 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 10 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 11 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 12 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 13 + + (also called from Q3Dict's destructor) + + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 14 + + In 99% of cases, the following idiom also works: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 15 + + However, it may lead to crashes if \c hash is referenced from + the value type's destructor, because \c hash contains + dangling pointers until clear() is called. + \endtable + + Be aware that Q3Dict's destructor automatically calls clear(). If + you have a Q3Dict data member in a custom class and use the + auto-delete feature, you will need to call \c delete on all the + items in the container from your class destructor to avoid a + memory leak. + + Finally, \c QDictIterator<T> (renamed Q3DictIterator<T>) must + also be ported. There are no fewer than four iterator classes + that can be used as a replacement: QHash::const_iterator, + QHash::iterator, QHashIterator, and QMutableHashIterator. The + most straightforward class to use when porting is + QHashIterator<QString, T *>. The following table summarizes the + API differences: + + \table + \header \o Q3DictIterator functions \o Qt 4 equivalent + \row \o Q3DictIterator::count() \o QHash::count() or QHash::size() + \row \o Q3DictIterator::current() \o QHashIterator::value() + \row \o Q3DictIterator::currentKey() \o QHashIterator::key() + \row \o Q3DictIterator::isEmpty() \o QHash::isEmpty() + \row \o Q3DictIterator::toFirst() \o QHashIterator::toFront() + \row \o Q3DictIterator::operator()() \o QHashIterator::value() + \row \o Q3DictIterator::operator*() \o QHashIterator::value() + \row \o Q3DictIterator::operator++() \o See remark below + \endtable + + Be aware that QHashIterator has a different way of iterating than + Q3DictIterator. A typical loop with Q3DictIterator looks like this: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 16 + + Here's the equivalent QHashIterator loop: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 17 + + See \l{Java-style iterators} for details. + + \section1 QDir + + The following functions used to have a boolean \c{acceptAbsPath} + parameter that defaulted to true: + + \list + \i QDir::filePath() + \i QDir::absFilePath() + \i QDir::cd() + \i QDir::mkdir() + \i QDir::rmdir() + \i QDir::remove() + \i QDir::rename() + \i QDir::exists() + \endlist + + In Qt 3, if \c acceptAbsPath is true, a file name starting with + '/' is be returned without change; if \c acceptAbsPath is false, + an absolute path is prepended to the file name. For example: + + \table + \header \i Current directory \i File name \i \c acceptAbsPath \i File path + \row \i{1,2} /home/tsmith \i{1,2} index.html \i true \i /home/tsmith/index.html + \row \i false \i /home/tsmith/index.html + \row \i{1,2} /home/tsmith \i{1,2} /index.html \i true \i /index.html + \row \i false \i /home/tsmith/index.html + \endtable + + In Qt 4, this parameter is no longer available. If you use it + in your code, you can check that QDir::isRelativePath() returns + false instead. + + \oldcode + QDir dir("/home/tsmith"); + QString path = dir.filePath(fileName, false); + \newcode + QDir dir("/home/tsmith"); + QString path; + if (dir.isRelativePath(fileName)) + path = dir.filePath(fileName); + else + path = fileName; + \endcode + + QDir::encodedEntryList() has been removed. + + fileInfoList(), entryInfoList(), and drives() now return a QList<QFileInfo> + and not a QPtrList<QFileInfo> *. Code using these methods will not work with + the Qt3Support library and must be adapted instead. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QDir virtual member functions in Qt 3 that are no longer + virtual in Qt 4. + + QDir::match() now always matches case insensitively. + + QDir::homeDirPath() has been removed. Use QDir::home() instead, and + extract the path separately. + + \section1 QDns + + Qt 3 used its own implementation of the DNS protocol and provided + a low-level \c QDns class. Qt 4's QHostInfo class uses the system's \c + gethostbyname() function from a thread instead. + + The old \c QDns class has been renamed Q3Dns and moved to the + Qt3Support library. The new QHostInfo class has a + radically different API: It consists mainly of two static + functions, one of which is blocking (QHostInfo::fromName()), the + other non-blocking (QHostInfo::lookupHost()). See the QHostInfo + class documentation for details. + + \section1 QDockArea + + The \c QDockArea class has been renamed Q3DockArea and moved to + the Qt3Support library. In Qt 4, QMainWindow handles + the dock and toolbar areas itself. See the QMainWindow + documentation for details. + + \section1 QDockWindow + + The old \c QDockWindow class has been renamed Q3DockWindow and + moved to the Qt3Support library. In Qt 4, there is a + new QDockWidget class with a different API. See the class + documentation for details. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QDockWidget virtual member functions in Qt 3 that are no + longer virtual in Qt 4. + + \note \l{Q3DockWindow}'s + \l{Q3DockWindow::setHorizontallyStretchable()}{horizontallyStretchable} + property can be achieved in QDockWidget with + \l{QWidget#Size Hints and Size Policies}{size policies}. + + \section1 QDragObject + + The \c QDragObject class has been renamed Q3DragObject and + moved to the Qt3Support library. In Qt 4, it has been + replaced by the QMimeData class. See the class documentation for + details. + + Note that the Q3DragObject::DragCopyOrMove drag and drop mode is + interpreted differently to Qt 3's QDragObject::DragCopyOrMove mode. + In Qt 3, a move operation was performed by default, and the user had + to hold down the \key{Ctrl} key to perform a copy operation. + In Qt 4, a copy operation is performed by default; the user has to + hold down the \key{Shift} key to perform a move operation. + + See \l{Porting to Qt 4 - Drag and Drop} for a comparison between + the drag and drop APIs in Qt 3 and Qt 4. + + \section1 QDropSite + + The \c QDropSite class has been renamed Q3DropSite and moved to + the Qt3Support library. + + The QDropSite class has been obsolete ever since Qt 2.0. The only + thing it does is call QWidget::setAcceptDrops(true). + + \oldcode + class MyWidget : public QWidget, public QDropSite + { + public: + MyWidget(const QWidget *parent) + : QWidget(parent), QDropSite(this) + { + } + ... + } + \newcode + class MyWidget : public QWidget + { + public: + MyWidget(const QWidget *parent) + : QWidget(parent) + { + setAcceptDrops(true); + } + ... + } + \endcode + + See \l{Porting to Qt 4 - Drag and Drop} for a comparison between + the drag and drop APIs in Qt 3 and Qt 4. + + \section1 QEditorFactory + + The \c QEditorFactory class has been renamed Q3EditorFactory and + moved to the Qt3Support library. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QEventLoop + + In Qt 3, \c QEventLoop combined the Qt event loop and the event + dispatching. In Qt 4, these tasks are now assigned to two + distinct classes: QEventLoop and QAbstractEventDispatcher. + + If you subclassed QEventLoop to integrate with another library's + event loop, you must subclass QAbstractEventDispatcher instead. See + the class documentation for details. + + Developers using \c{QEventLoop::loopLevel()} in Qt 3 should use + QCoreApplication::loopLevel() instead. Note that this function is + marked as obsolete, but it is expected to be available for the + lifetime of Qt 4. + \omit ### mention virtual functions that aren't virtual anymore \endomit + + \omit + \section1 QFile + + The QFile::readLine(QString&, Q_ULONG) method from qt3 has been removed + in qt4, but this change in the QFile interface is not documented in the + porting documentation as of qt-4.0.0-b1. + \endomit + + \section1 QFileDialog + + The QFileDialog class in Qt 4 has been totally rewritten. It + provides most of the functionality of the old \c QFileDialog + class, but with a different API. Some functionality, such as the + ability to preview files, is expected to be added in a later Qt 4 + release. + + The old \c QFileDialog, \c QFileIconProvider, and \c QFilePreview + classes has been renamed Q3FileDialog, Q3FileIconProvider, and + Q3FilePreview and have been moved to Qt3Support. You can use them + if you need some functionality not provided yet by the new + QFileDialog class. + + The following table lists which functions have been renamed or + removed in Qt 4. + + \table + \header \o Old function \o Qt 4 equivalent + \row \o Q3FileDialog::addFilter(const QString &) \o See remark below + \row \o Q3FileDialog::addLeftWidget(QWidget *) \o N/A + \row \o Q3FileDialog::addRightWidget(QWidget *) \o N/A + \row \o Q3FileDialog::addToolButton(QAbstractButton *, bool separator) \o N/A + \row \o Q3FileDialog::addWidgets(QLabel *, QWidget *, QPushButton *) \o N/A + \row \o Q3FileDialog::dir() \o QFileDialog::directory() + \row \o Q3FileDialog::dirPath() \o QFileDialog::directory().path() + \row \o Q3FileDialog::iconProvider() \o N/A + \row \o Q3FileDialog::isContentsPreviewEnabled() \o N/A + \row \o Q3FileDialog::isInfoPreviewEnabled() \o N/A + \row \o Q3FileDialog::previewMode() \o N/A + \row \o Q3FileDialog::rereadDir() \o N/A + \row \o Q3FileDialog::resortDir() \o N/A + \row \o Q3FileDialog::selectAll(bool) \o N/A + \row \o Q3FileDialog::setContentsPreview(QWidget *, Q3FilePreview *) \o N/A + \row \o Q3FileDialog::setContentsPreviewEnabled(bool) \o N/A + \row \o Q3FileDialog::setDir(const QString &) \o QFileDialog::setDirectory(const QString &) + \row \o Q3FileDialog::setFilters(const char **) \o Q3FileDialog::setFilters(const QStringList &) + \row \o Q3FileDialog::setIconProvider(Q3FileIconProvider *) \o N/A + \row \o Q3FileDialog::setInfoPreview(QWidget *, Q3FilePreview *) \o N/A + \row \o Q3FileDialog::setInfoPreviewEnabled(bool) \o N/A + \row \o Q3FileDialog::setPreviewMode(PreviewMode) \o N/A + \row \o Q3FileDialog::setSelectedFilter(const QString &) \o QFileDialog::selectFilter(const QString &) + \row \o Q3FileDialog::setSelectedFilter(int) \o See remark below + \row \o Q3FileDialog::setSelection(const QString &) \o QFileDialog::selectFile(const QString &) + \row \o Q3FileDialog::setShowHiddenFiles(bool) \o showHidden() + \row \o Q3FileDialog::setUrl(const QUrlOperator &) \o N/A + \row \o Q3FileDialog::showHiddenFiles() \o N/A + \row \o Q3FileDialog::url() \o QUrl::fromLocalFile(QFileDialog::directory()) + \header \o Old signals \o Qt 4 equivalent + \row \o Q3FileDialog::fileHighlighted(const QString &) \o N/A + \row \o Q3FileDialog::fileSelected(const QString &) \o QFileDialog::filesSelected(const QStringList &) + \row \o Q3FileDialog::dirEntered(const QString &) \o N/A + \row \o Q3FileDialog::filterSelected(const QString &) \o N/A + \endtable + + Remarks: + + \list 1 + \o The Q3FileDialog::addFilter(const QString &) function has no + direct equivalent in the new QFileDialog. Use + QFileDialog::setFilters() instead. + + \oldcode + fileDialog->addFilter(tr("JPEG files (*.jpg *.jpeg)")); + \newcode + QStringList filters = fileDialog->filters(); + filters << tr("JPEG files (*.jpg *.jpeg)"); + fileDialog->setFilters(filters); + \endcode + + \o The Q3FileDialog::setSelectedFilter(int) overload has no direct + equivalent in the new QFileDialog. Use + QFileDialog::selectFilter(const QString &) instead. + + \oldcode + fileDialog->setSelectedFilter(3); + \newcode + fileDialog->selectFilter(fileDialog->filters().at(3)); + \endcode + \endlist + + There are no equivalent virtual functions to the two + Q3FileDialog::setSelectedFilter() virtual functions in the QFileDialog + API. In addition, these functions have been renamed or removed, as + described above. + + \section1 QFocusData + + The QFocusData class is not available in Qt 4. Some of its + functionality is available via the QWidget::nextInFocusChain() + and QWidget::focusNextPrevChild() functions. + + \section1 QFocusEvent + + The setReason() function is no longer present in Qt 4. It is + necessary to define the reason when constructing a focus event. + + \section1 QFont + + \c QFont::Script has been moved to QFontDatabase::WritingSystem. + + \section1 QFrame + + The QFrame class has been made more lightweight in Qt 4, by + reducing the number of properties and virtual functions. The + reduction in the number of virtual functions is significant + because QFrame is the base class of many Qt classes. + + Here's an overview of the changes: + + \list + \o QFrame no longer has a \c margin property (which wasn't + honored by Qt's layout managers anyway). + + \o QFrame no longer has a frameChanged() function, reimplement + QFrame::resizeEvent() instead. + + \o QFrame used to have drawFrame(QPainter *) and + drawContents(QPainter *) virtual functions. These are now + gone. In Qt 4, the frame is drawn by the QFrame::paintEvent() + function. If you want to change the way QFrame paints itself, + reimplement this function. To draw the contents of the frame, + reimplement QFrame:paintEvent() and call the base class + implementation of the function before you use the + \l {QWidget::}{contentsRect()} function inherited from QWidget, + to retrieve the rectangle to paint on. + + \endlist + + To help with porting, the Qt3Support library contains a Q3Frame + class that inherits QFrame and provides a similar API to the old + QFrame class. If you derived from QFrame in your application, you + might want to use Q3Frame as a base class as a first step in the + porting process, and later move on to the new QFrame class. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QFrame virtual member functions in Qt 3 that are no longer + virtual in Qt 4. + + \section1 QFtp + + QFtp no longer inherits from QNetworkProtocol. See the + \l{#qnetworkprotocol.section}{section on QNetworkProtocol} for + details. + + The old \c QFtp class has been renamed Q3Ftp and moved to the + Qt3Support library. + + \target qglayoutiterator.section + \section1 QGLayoutIterator + + The QGLayoutIterator class no longer exists in Qt 4. This makes + only a difference if you implemented custom layout managers + (i.e., QLayout subclasses). + + The new approach is much simpler: It consists in reimplementing + QLayout::itemAt() and QLayout::takeAt(). These functions operate + on indexes, eliminating the need for a layout iterator class. + + \section1 QGrid + + The \c QGrid class is now only available as Q3Grid in Qt 4. You + can achieve the same result as \c QGrid by creating a QWidget + with a grid layout: + + \oldcode + QGrid *grid = new QGrid(2, Qt::Horizontal); + QPushButton *child1 = new QPushButton(grid); + QPushButton *child2 = new QPushButton(grid); + QPushButton *child3 = new QPushButton(grid); + QPushButton *child4 = new QPushButton(grid); + \newcode + QWidget *grid = new QWidget; + QPushButton *child1 = new QPushButton(grid); + QPushButton *child2 = new QPushButton(grid); + QPushButton *child3 = new QPushButton(grid); + QPushButton *child4 = new QPushButton(grid); + + QVBoxLayout *layout = new QVBoxLayout; + layout->addWidget(child1, 0, 0); + layout->addWidget(child2, 0, 1); + layout->addWidget(child3, 1, 0); + layout->addWidget(child4, 1, 1); + grid->setLayout(layout); + \endcode + + \section1 QGridLayout + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QGridLayout virtual member functions in Qt 3 that are no + longer virtual in Qt 4. + + \section1 QGridView + + The \c QGridView class has been renamed Q3GridView and moved to + the Qt3Support library. In Qt 4, we recommend that + you use QTableView or QAbstractItemView for presenting tabular + data. + + See \l{Model/View Programming} for an overview of the new item + view classes. + + \target qgroupbox.section + \section1 QGroupBox + + The QGroupBox class has been redesigned in Qt 4. Many of the + features of the old \c QGroupBox class can be obtained by using + the Q3GroupBox class from the Qt3Support library. + + The new QGroupBox is more lightweight. It doesn't attempt to + duplicate functionality already provided by QGridLayout, and it + does not inherit from QFrame. As a result, the following members + have been removed: + + \list + \o Q3GroupBox::setColumns(), Q3GroupBox::columns() + \o Q3GroupBox::setOrientation(), Q3GroupBox::orientation() + \o Q3GroupBox::setInsideMargin(), Q3GroupBox::insideMargin() + \o Q3GroupBox::addSpace() + \endlist + + Naturally, the \c columns and \c orientation properties have also + been removed. + + If you rely on some of the missing functionality in your + application, you can use Q3GroupBox instead of QGroupBox as a + help to porting. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QGroupBox virtual member functions in Qt 3 that are no + longer virtual in Qt 4. + + \section1 QHBox + + The \c QHBox class is now only available as Q3HBox in Qt 4. You + can achieve the same result as \c QHBox by creating a QWidget + with an horizontal layout: + + \oldcode + QHBox *hbox = new QHBox; + QPushButton *child1 = new QPushButton(hbox); + QPushButton *child2 = new QPushButton(hbox); + \newcode + QWidget *hbox = new QWidget; + QPushButton *child1 = new QPushButton; + QPushButton *child2 = new QPushButton; + + QHBoxLayout *layout = new QHBoxLayout; + layout->addWidget(child1); + layout->addWidget(child2); + hbox->setLayout(layout); + \endcode + + Note that child widgets are not automatically placed into the widget's + layout; you will need to manually add each widget to the QHBoxLayout. + + \section1 QHeader + + The \c QHeader class has been renamed Q3Header and moved to + the Qt3Support library. In Qt 4, it is replaced + by the QHeaderView class. + + See \l{Model/View Programming} for an overview of the new item + view classes. + + \section1 QHGroupBox + + The \c QHGroupBox class has been renamed Q3HGroupBox and moved to + the Qt3Support library. + Qt 4 does not provide a specific replacement class for \c QHGroupBox + since QGroupBox is designed to be a generic container widget. As a + result, you need to supply your own layout for any child widgets. + + See \l{#QGroupBox} for more information about porting code that uses + group boxes. + + \section1 QHttp + + QHttp no longer inherits from QNetworkProtocol. See the See the + \l{#qnetworkprotocol.section}{section on QNetworkProtocol} for + details. + + The old \c QHttp, \c QHttpHeader, \c QHttpRequestHeader, and \c + QHttpResponseHeader classes have been renamed Q3Http, + Q3HttpHeader, Q3HttpRequestHeader, and Q3HttpResponseHeader and + have been moved to the Qt3Support library. + + \section1 QIconFactory + + The QIconFactory class is no longer part of Qt. It has been replaced by + the QIconEngine class. + + \section1 QIconSet + + The QIconSet class is no longer part of Qt. It has been replaced by + the QIcon class. + + \section1 QIconView + + The \c QIconView, \c QIconViewItem, \c QIconDrag, and \c + QIconDragItem classes has been renamed Q3IconView, + Q3IconViewItem, Q3IconDrag, and Q3IconDragItem and moved to the + Qt3Support library. New Qt applications should use + QListWidget or its base class QListView instead, and call + QListView::setViewMode(QListView::IconMode) to obtain an "icon + view" look. + + See \l{Model/View Programming} for an overview of the new item + view classes. + + \omit + ### + + \section1 QImage + + QImage::fromMimeSource(const QString &) -> qImageFromMimeSource(const QString &) + \endomit + + \section1 QImageDrag + + The \c QImageDrag class has been renamed Q3ImageDrag and moved to + the Qt3Support library. In Qt 4, use QMimeData + instead and call QMimeData::setImage() to set the image. + + See \l{Porting to Qt 4 - Drag and Drop} for a comparison between + the drag and drop APIs in Qt 3 and Qt 4. + + \section1 QImageIO + + The \c QImageIO class has been split into two classes: + QImageReader and QImageWriter. The table below shows the + correspondance between the two APIs: + + \table + \header \o Qt 3 function \o Qt 4 equivalents + \row \o QImageIO::description() \o QImageWriter::text() + \row \o QImageIO::fileName() \o QImageReader::fileName() and QImageWriter::fileName() + \row \o QImageIO::format() \o QImageReader::format() and QImageWriter::format() + \row \o QImageIO::gamma() \o QImageWriter::gamma() + \row \o QImageIO::image() \o Return value of QImageReader::read() + \row \o QImageIO::inputFormats() \o QImageReader::supportedImageFormats() + \row \o QImageIO::ioDevice() \o QImageReader::device() and QImageWriter::device() + \row \o QImageIO::outputFormats() \o QImageWriter::supportedImageFormats() + \row \o QImageIO::parameters() \o N/A + \row \o QImageIO::quality() \o QImageWriter::quality() + \row \o QImageIO::read() \o QImageReader::read() + \row \o QImageIO::setDescription() \o QImageWriter::setText() + \row \o QImageIO::setFileName() \o QImageReader::setFileName() and QImageWriter::setFileName() + \row \o QImageIO::setFormat() \o QImageReader::setFormat() and QImageWriter::setFormat() + \row \o QImageIO::setGamma() \o QImageWriter::setGamma() + \row \o QImageIO::setIODevice() \o QImageReader::setDevice() and QImageWriter::setDevice() + \row \o QImageIO::setImage() \o Argument to QImageWriter::write() + \row \o QImageIO::setParameters() \o N/A + \row \o QImageIO::setQuality() \o QImageWriter::setQuality() + \row \o QImageIO::setStatus() \o N/A + \row \o QImageIO::status() \o QImageReader::error() and QImageWriter::error() + \row \o QImageIO::write() \o QImageWriter::write() + \endtable + + \section1 QIntCache<T> + + QIntCache<T> has been moved to Qt3Support. It has been replaced + by QCache<int, T>. + + For details, read the \l{#qcache.section}{section on QCache<T>}, + mentally substituting \c int for QString. + + \section1 QIntDict<T> + + QIntDict<T> and QIntDictIterator<T> have been moved to + Qt3Support. They have been replaced by the more modern QHash<Key, + T> and QMultiHash<Key, T> classes and their associated iterator + classes. + + When porting old code that uses QIntDict<T> to Qt 4, there are + four classes that you can use: + + \list + \o QMultiHash<int, T *> + \o QMultiHash<int, T> + \o QHash<int, T *> + \o QHash<int, T> + \endlist + + For details, read the \l{#qdict.section}{section on QDict<T>}, + mentally substituting \c int for QString. + + \target qiodevice.section + \section1 QIODevice + + The QIODevice class's API has been simplified to make it easier + to subclass and to make it work more smoothly with asynchronous + devices such as QTcpSocket and QProcess. + + The following virtual functions have changed name or signature: + + \table + \header \o Qt 3 function \o Comment + \row \o QIODevice::at() const \o Renamed QIODevice::pos(). + \row \o QIODevice::at(Offset) \o Renamed QIODevice::seek(). + \row \o QIODevice::open(int) \o The parameter is now of type QIODevice::OpenMode. + \row \o QIODevice::readBlock(char *, Q_ULONG) \o QIODevice::read(char *, qint64) + \row \o QIODevice::writeBlock(const char *, Q_ULONG) \o QIODevice::write(const char *, qint64) + \endtable + + \note QIODevice::open(QIODevice::OpenMode) is no longer pure virtual. + + The following functions are no longer virtual or don't exist anymore: + + \table + \row \o QIODevice::getch() \o Renamed QIODevice::getChar() and implemented in terms of QIODevice::readData(). + \row \o QIODevice::putch(int) \o Renamed QIODevice::putChar() and implemented in terms of QIODevice::writeData(). + \row \o QIODevice::readAll() \o Implemented in terms of QIODevice::readData(). + \row \o QIODevice::readLine(char *, Q_ULONG) \o Implemented in terms of QIODevice::readData() + \row \o QIODevice::ungetch(int) \o Renamed QIODevice::ungetChar() and simulated using an internal unget buffer. + \endtable + + The \c IO_xxx flags have been revised, and the protected setFlags() + function removed. Most of the flags have been + eliminated because errors are best handled by implementing certain + functions in QIODevice subclasses rather than through the base classes. + The file access flags, such as \c IO_ReadOnly and \c IO_WriteOnly, have + been moved to the QIODevice class to avoid polluting the global + namespace. The table below shows the correspondence between the + Qt 3 \c IO_xxx flags and the Qt 4 API: + + \table + \header \o Qt 3 constant \o Qt 4 equivalent + \row \o IO_Direct \o Use !QIODevice::isSequential() instead (notice the \e not). + \row \o IO_Sequential \o Use QIODevice::isSequential() instead. + \row \o IO_Combined \o N/A + \row \o IO_TypeMask \o N/A + \row \o IO_Raw \o QIODevice::Unbuffered + \row \o IO_Async \o N/A + \row \o IO_ReadOnly \o QIODevice::ReadOnly + \row \o IO_WriteOnly \o QIODevice::WriteOnly + \row \o IO_ReadWrite \o QIODevice::ReadWrite + \row \o IO_Append \o QIODevice::Append + \row \o IO_Truncate \o QIODevice::Truncate + \row \o IO_Translate \o QIODevice::Text + \row \o IO_ModeMask \o N/A + \row \o IO_Open \o Use QIODevice::isOpen() instead. + \row \o IO_StateMask \o N/A + \row \o IO_Ok \o N/A + \row \o IO_ReadError \o N/A + \row \o IO_WriteError \o N/A + \row \o IO_FatalError \o N/A + \row \o IO_ResourceError \o N/A + \row \o IO_OpenError \o N/A + \row \o IO_ConnectError \o N/A + \row \o IO_AbortError \o N/A + \row \o IO_TimeOutError \o N/A + \row \o IO_UnspecifiedError \o N/A + \endtable + + \section1 QIODeviceSource + + The QIODeviceSource class was used internally in Qt 2.x in + conjunction with QImageConsumer. It was obsoleted in Qt 3.0. + \input porting/porting4-obsoletedmechanism.qdocinc + + \section1 QLabel + + QLabel doesn't enable word-wrap automatically anymore when rich + text is used. You can enable it by calling + QLabel::setWordWrap() or by setting the + \l{QLabel::wordWrap}{wordWrap} property. The reason for this + change is that the old behavior was confusing to many users. + + Also, QLabel no longer offers an \c autoResize property. Instead, + you can call QWidget::setFixedSize() on the label, with + QLabel::sizeHint() as the argument, whenever you change the + contents of the QLabel. + + See also \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} + for a list of QLabel virtual member functions in Qt 3 that are no + longer virtual in Qt 4. + + \section1 QLayout + + In Qt 4, margins are always handled by layouts; there is no + QLayout::setSupportsMargin() function anymore. + + The deleteAllItems() function is now only available if + \c QT3_SUPPORT is defined. If you maintain a QList of layout + items, you can use qDeleteAll() to remove all the items in one + go. + + In Qt 3, it was possible to change the resizing behavior for layouts + in top-level widgets by adjusting the layout's \c resizeMode property. + In Qt 4, this property has been replaced by the QLayout::sizeConstraint + property which provides more control over how the layout behaves when + resized. + + See also the \l{#qlayoutiterator.section}{section on + QLayoutIterator} and the \l{#qglayoutiterator.section}{section on + QGLayoutIterator}. + + \target qlayoutiterator.section + \section1 QLayoutIterator + + The QLayoutIterator class is obsoleted in Qt 4. It is available + only if \c QT3_SUPPORT is defined. It can be replaced by the + QLayout::itemAt() and QLayout::takeAt() functions, which operate + on indexes. + + \oldcode + QLayoutIterator it = layout()->iterator(); + QLayoutItem *child; + while ((child = it.current()) != 0) { + if (child->widget() == myWidget) { + it.takeCurrent(); + return; + ++it; + } + \newcode + int i = 0; + QLayoutItem *child; + while ((child = layout()->itemAt(i)) != 0) { + if (child->widget() == myWidget) { + layout()->takeAt(i); + return; + } + ++i; + } + \endcode + + \section1 QLineEdit + + See \l{#properties}{Properties} for a list of QLineEdit + properties in Qt 3 that have changed in Qt 4. + + The default value of QLineEdit's \l{QLineEdit::dragEnabled()}{dragEnabled} + property was \c true in Qt 3. In Qt 4, the default value is \c false. + + Note that QLineEdit in Qt 4 is no longer a subclass of QFrame. + If you need to visually style a line edit with a frame, we recommend + either using a QFrame as a container for a QLineEdit or customizing + the line edit with a \l{Qt Style Sheets}{style sheet}. + + \section1 QListBox + + The \c QListBox, \c QListBoxItem, \c QListBoxText, and \c + QListBoxPixmap classes have been renamed Q3ListBox, + Q3ListBoxItem, Q3ListBoxText, and Q3ListBoxPixmap and have been + moved to the Qt3Support library. New Qt applications + should use QListWidget or its base class QListView instead. + + See \l{Model/View Programming} for an overview of the new item + view classes. + + \section1 QListView + + The \c QListView, \c QListViewItem, \c QCheckListItem, and \c + QListViewItemIterator classes have been renamed Q3ListView, + Q3ListViewItem, Q3CheckListItem, and Q3ListViewItemIterator, and + have been moved to the Qt3Support library. New Qt + applications should use one of the following four classes + instead: QTreeView or QTreeWidget for tree-like structures; + QListWidget or the new QListView class for one-dimensional lists. + + See \l{Model/View Programming} for an overview of the new item + view classes. + + \section1 QLocalFs + + The \c QLocalFs class is no longer part of the public Qt API. It + has been renamed Q3LocalFs and moved to Qt3Support. Use QDir, + QFileInfo, or QFile instead. + + \section1 QMainWindow + + The QMainWindow class has been redesigned in Qt 4 to provide a + more modern look and feel and more flexibility. The API has + changed to reflect that. The old \c QMainWindow class has been + renamed Q3MainWindow and moved to Qt3Support. See the QMainWindow + class documentation for details. + + \omit ### More detail \endomit + + \target qmemarray.section + \section1 QMemArray<T> + + QMemArray<T> has been moved to Qt3Support. It has been replaced + by the QVector<T> class. + + The following table summarizes the API differences between the + two classes. + + \table + \row \o QMemArray::assign(const QMemArray<T> &) \o QVector::operator=() + \row \o QMemArray::assign(const T *, uint) \o See remark below + \row \o QMemArray::duplicate(const QMemArray &) \o QVector::operator=() + \row \o QMemArray::duplicate(const T *, uint) \o See remark below + \row \o QMemArray::setRawData(const T *, uint) \o N/A + \row \o QMemArray::resetRawData(const T *, uint) \o N/A + \row \o QMemArray::find(const T &, uint) \o QVector::indexOf(const T &, int) + \row \o QMemArray::contains(const T &) \o QVector::count(const T &) + \row \o QMemArray::sort() \o \l qSort() + \row \o QMemArray::bsearch(const T &d) \o \l qBinaryFind() + \row \o QMemArray::at(uint) \o QVector::operator[]() + \row \o QMemArray::operator const T *() \o QVector::constData() + \endtable + + Remarks: + + \list 1 + \o QMemArray::assign(const T *, uint) and QMemArray::duplicate(const T *, uint) + can be replaced by QVector::resize() and qCopy(). + + \oldcode + QMemArray<QSize> array; + ... + array.assign(data, size); + \newcode + QVector<QSize> vector; + ... + vector.resize(size); + qCopy(data, data + size, vector.begin()); + \endcode + + \o QMemArray is an explicitly shared class, whereas QVector is + implicitly shared. See \l{Explicit Sharing} for more + information. + \endlist + + \section1 QMenuBar + + In Qt 3, QMenuBar inherited from QFrame and QMenuData; in Qt 4, it is + a direct subclass of QWidget. Applications that provided customized + menu bars will need to take advantage of the styling features described + in the \l{Qt Style Sheets} document. + + It is not possible to add widgets to menu bars in Qt 4. + + \section1 QMenuData + + In Qt 4, the QMenu class provides a menu widget that can be used in all + the places where menus are used in an application. Unlike \c QMenuData, + QMenu is designed around the concept of actions, provided by the QAction + class, instead of the identifiers used in Qt 3. + + In Qt 3, it was possible to insert widgets directly into menus by using + a specific \c QMenuData::insertItem() overload. In Qt 4.2 and later, + the QWidgetAction class can be used to wrap widgets for use in Qt 4's + action-based APIs. + + \section1 QMessageBox + + The QMessageBox::iconPixmap() function used to return a "const + QPixmap *". In Qt 4, it returns a QPixmap. + + \section1 QMimeSourceFactory + + The \c QMimeSourceFactory has been renamed Q3MimeSourceFactory + and moved to the Qt3Support library. New Qt applications should + use Qt 4's \l{Resource System} instead. + + \section1 QMovie + + The QMovie API has been revised in Qt 4 to make it more + consistent with the other Qt classes (notably QImageReader). The + table below summarizes the changes. + + \table + \header \o Qt 3 function \o Qt 4 equivalent + \row \o QMovie::connectResize() \o Connect to QMovie::resized() + \row \o QMovie::connectStatus() \o Connect to QMovie::stateChanged() + \row \o QMovie::connectUpdate() \o Connect to QMovie::updated() + \row \o QMovie::disconnectResize() \o Disconnect from QMovie::resized() + \row \o QMovie::disconnectStatus() \o Disconnect from QMovie::stateChanged() + \row \o QMovie::disconnectUpdate() \o Disconnect from QMovie::updated() + \row \o QMovie::finished() \o Use QMovie::state() instead + \row \o QMovie::frameImage() \o Use QMovie::currentImage() instead + \row \o QMovie::frameNumber() \o Use QMovie::currentFrameNumber() instead + \row \o QMovie::framePixmap() \o Use QMovie::currentPixmap() instead + \row \o QMovie::getValidRect() \o Use frameRect() instead + \row \o QMovie::isNull() \o Use QMovie::isValid() instead + \row \o QMovie::pause() \o Use QMovie::setPaused(true) instead + \row \o QMovie::paused() \o Use QMovie::state() instead + \row \o QMovie::pushData() \o N/A + \row \o QMovie::pushSpace() \o N/A + \row \o QMovie::restart() \o Use QMovie::jumpToFrame(0) instead + \row \o QMovie::running() \o Use QMovie::state() instead + \row \o QMovie::step() \o Use QMovie::jumpToFrame() and QMovie::setPaused() instead + \row \o QMovie::step() \o Use QMovie::jumpToNextFrame() instead + \row \o QMovie::steps() \o Use QMovie::currentFrameNumber() and QMovie::frameCount() instead + \row \o QMovie::unpause() \o Use QMovie::setPaused(false) instead + \endtable + + \section1 QMultiLineEdit + + The \c QMultiLineEdit class in Qt 3 was a convenience QTextEdit + subclass that provided an interface compatible with Qt 2's + QMultiLineEdit class. In Qt 4, it is called Q3MultiLineEdit, it + inherits Q3TextEdit, and it is part of Qt3Support. Use QTextEdit + in new code. + + \target qnetworkprotocol.section + \section1 QNetworkProtocol + + The QNetworkProtocol, QNetworkProtocolFactoryBase, + QNetworkProtocolFactory<T>, and QNetworkOperation classes are no + longer part of the public Qt API. They have been renamed + Q3NetworkProtocol, Q3NetworkProtocolFactoryBase, + Q3NetworkProtocolFactory<T>, and Q3NetworkOperation and have been + moved to the Qt3Support library. + + In Qt 4 applications, you can use classes like QFtp and + QNetworkAccessManager directly to perform file-related actions on + a remote host. + + \section1 QObject + + QObject::children() now returns a QObjectList instead of a + pointer to a QObjectList. See also the comments on QObjectList + below. + + Use QObject::findChildren() (or qFindChildren() if you need MSVC 6 + compatibility) instead of QObject::queryList(). For example: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 18 + + QObject::killTimers() has been removed because it was unsafe to + use in subclass. (A subclass normally doesn't know whether the + base class uses timers or not.) + + The \c QObject::name property has been renamed + QObject::objectName. + + \c QObject::objectTrees() has been removed. If you are primarly + interested in widgets, use QApplication::allWidgets() or + QApplication::topLevelWidgets(). + + \section1 QObjectDictionary + + The QObjectDictionary class is a synonym for + QAsciiDict<QMetaObject>. See the \l{#qasciidict.section}{section + on QAsciiDict<T>}. + + \section1 QObjectList + + In Qt 3, the QObjectList class was a typedef for + QPtrList<QObject>. In Qt 4, it is a typedef for QList<QObject *>. + See the \l{#qptrlist.section}{section on QPtrList<T>}. + + \section1 QPaintDevice + + To reimplement painter backends one previously needed to reimplement + the virtual function QPaintDevice::cmd(). This function is taken out + and should is replaced with the function QPaintDevice::paintEngine() + and the abstract class QPaintEngine. QPaintEngine provides virtual + functions for all drawing operations that can be performed on a + painter backend. + + bitBlt() and copyBlt() are now only compatibility functions. Use + QPainter::drawPixmap() instead. + + \section1 QPaintDeviceMetrics + + All functions that used to be provided by the \c + QPaintDeviceMetrics class have now been moved to QPaintDevice. + + \oldcode + QPaintDeviceMetrics metrics(widget); + int deviceDepth = metrics.depth(); + \newcode + int deviceDepth = widget->depth(); + \endcode + + For compatibility, the old \c QPaintDeviceMetrics class has been + renamed Q3PaintDeviceMetrics and moved to Qt3Support. + + \section1 QPainter + + The QPainter class has undergone some changes in Qt 4 because of + the way rectangles are drawn. In Qt 4, the result of drawing a + QRect with a pen width of 1 pixel is 1 pixel wider and 1 pixel + taller than in Qt 3. + + For compatibility, we provide a Q3Painter class in Qt3Support + that provides the old semantics. See the Q3Painter documentation + for details and for the reasons why we had to make this change. + + The \l{http://qt.nokia.com/doc/3.3/qpainter.html#CoordinateMode-enum}{QPainter::CoordinateMode} + enum has been removed in Qt 4. All clipping + operations are now defined using logical coordinates and are subject + to transformation operations. + + The + \l{http://qt.nokia.com/doc/3.3/qpainter.html#RasterOP-enum}{QPainter::RasterOP} + enum has been replaced with QPainter::CompositionMode. + + \section1 QPicture + + In Qt 3, a QPicture could be saved in the SVG file format. In Qt + 4, the SVG support is provided by the QtSvg module, which + includes classes for \e displaying the contents of SVG files. + + If you would like to generate SVG files, you can use the Q3Picture + compatibility class or the QSvgGenerator class introduced in Qt 4.3. + + \section1 QPixmap + + The mask() function has been changed to return a reference to a QBitmap + rather than a pointer. As a result, it is no longer possible simply to + test for a null pointer when determining whether a pixmap has a mask. + Instead, you need to explicitly test whether the mask bitmap is null or + not. + + \oldcode + if (pixmap.mask()) + widget->setMask(*pixmap.mask()); + \newcode + if (!pixmap.mask().isNull()) + widget->setMask(pixmap.mask()); + \endcode + + The \c QPixmap::setOptimization() and \c QPixmap::setDefaultOptimization() + mechanism is no longer available in Qt 4. + +\omit + QPixmap::fromMimeSource(const QString &) -> qPixmapFromMimeSource(const QString &) +\endomit + + \section1 QPointArray + + The \c QPointArray class has been renamed QPolygon in Qt 4 and + has undergone significant changes. In Qt 3, \c QPointArray + inherited from QMemArray<QPoint>. In Qt 4, QPolygon inherits from + QVector<QPoint>. Everything mentioned in the + \l{#qmemarray.section}{section on QMemArray<T>} apply for + QPointArray as well. + + The Qt3Support library contains a Q3PointArray class + that inherits from QPolygon and provides a few functions that + existed in \c QPointArray but no longer exist in QPolygon. These + functions include Q3PointArray::makeArc(), + Q3PointArray::makeEllipse(), and Q3PointArray::cubicBezier(). + In Qt 4, we recommend that you use QPainterPath for representing + arcs, ellipses, and Bezier curves, rather than QPolygon. + + The QPolygon::setPoints() and QPolygon::putPoints() functions + return \c void in Qt 4. The corresponding Qt 3 functions returned + a \c bool indicating whether the array was successfully resized + or not. This can now be checked by checking QPolygon::size() + after the call. + +\omit + X11 Specific: + + ::appDisplay() -> QX11Info::display() + QPaintDevice::x11Display() -> QX11Info::display() + QPaintDevice::x11AppDisplay() -> QX11Info::display() + QPaintDevice::x11Screen() -> QX11Info::appScreen() + QPaintDevice::x11AppScreen() -> ??? + QPaintDevice::x11Depth() -> QX11Info::appDepth() + QPaintDevice::x11ColorMap() -> QX11Info::appColorMap() + QPaintDevice::x11DefaultColorMap() -> ??? + QPaintDevice::x11Visual() -> QX11Info::appVisual() + QPaintDevice::x11DefaultVisual() -> ??? + + QPaintDevice::x11AppDpiX() -> QX11Info::appDpiX() + QPaintDevice::x11AppDpiY() -> QX11Info::appDpiY() + QPaintDevice::x11SetAppDpiX() -> QX11Info::setAppDpiX() + QPaintDevice::x11SetAppDpiY() -> QX11Info::setAppDpiY() + + QPaintDevice::x11AppDepth() -> ??? + QPaintDevice::x11AppCells() -> ??? + QPaintDevice::x11AppRootWindow() -> ??? + QPaintDevice::x11AppColorMap() -> ??? + QPaintDevice::x11AppDefaultColorMap() -> ??? + QPaintDevice::x11AppVisual() -> ??? + QPaintDevice::x11AppDefaultVisual() -> ??? + + End of X11 Specific +\endomit + + \section1 QPopupMenu + + For most purposes, QPopupMenu has been replaced by QMenu in Qt + 4. For compatibility with older applications, Q3PopupMenu provides + the old API and features that are specific to pop-up menus. Note + that, when using Q3PopupMenu, the menu's actions must be \l + {Q3Action}s. + + In Qt 3, it was common practice to add entries to pop-up menus using the + insertItem() function, maintaining identifiers for future use; for + example, to dynamically change menu items. + In Qt 4, menu entries are completely represented + by actions for consistency with other user interface components, such as + toolbar buttons. Create new menus with the QMenu class, and use the + overloaded QMenu::addAction() functions to insert new entries. + If you need to manage a set of actions created for a particular menu, + we suggest that you construct a QActionGroup and add them to that. + + The \l{Main Window Examples} provided + show how to use Qt's action system to construct menus, toolbars, and other + common user interface elements. + + \section1 QPrinter + + The QPrinter class now expects printing to be set up from a + QPrintDialog. + + \section1 QProcess + + The QProcess class has undergone major improvements in Qt 4. It + now inherits QIODevice, which makes it possible to combine + QProcess with a QTextStream or a QDataStream. + + The old \c QProcess class has been renamed Q3Process and moved to + the Qt3Support library. + + \section1 QProgressBar + + The QProgressBar API has been significantly improved in Qt 4. The + old \c QProgressBar API is available as Q3ProgressBar in the + Qt3Support library. + + \section1 QProgressDialog + + The QProgressDialog API has been significantly improved in Qt 4. + The old \c QProgressDialog API is available as Q3ProgressDialog + in the Qt3Support library. + + See \l{#properties}{Properties} for a list of QProgressDialog + properties in Qt 3 that have changed in Qt 4. + + \section1 QPtrCollection<T> + + The \c QPtrCollection<T> abstract base class has been renamed + Q3PtrCollection<T> moved to the Qt3Support library. + There is no direct equivalent in Qt 4. + + \omit + ### + The QPtrCollection entry is unsatisfactory. The xref is missing + its list and saying "no direct equivalent" with so suggestions + seems feeble. + \endomit + + See \l{Generic Containers} for a list of Qt 4 containers. + + \section1 QPtrDict<T> + + \c QPtrDict<T> and \c QPtrDictIterator<T> have been renamed + Q3PtrDict<T> and Q3PtrDictIterator<T> and have been moved to the + Qt3Support library. They have been replaced by the + more modern QHash<Key, T> and QMultiHash<Key, T> classes and + their associated iterator classes. + + When porting old code that uses Q3PtrDict<T> to Qt 4, there are + four classes that you can use: + + \list + \o QMultiHash<void *, T *> + \o QMultiHash<void *, T> + \o QHash<void *, T *> + \o QHash<void *, T> + \endlist + + (You can naturally use other types than \c{void *} for the key + type, e.g. \c{QWidget *}.) + + To port Q3PtrDict<T> to Qt 4, read the \l{#qdict.section}{section + on QDict<T>}, mentally substituting \c{void *} for QString. + + \target qptrlist.section + \section1 QPtrList<T> + + QPtrList<T>, QPtrListIterator<T>, and QPtrListStdIterator<T> have + been moved to the Qt3Support library. They have been + replaced by the more modern QList and QLinkedList classes and + their associated iterator classes. + + When porting to Qt 4, you have the choice of using QList<T> or + QLinkedList<T> as alternatives to QValueList<T>. QList<T> has an + index-based API and provides very fast random access + (QList::operator[]), whereas QLinkedList<T> has an iterator-based + API. + + The following table summarizes the API differences between + QPtrList<T> and QList<T *>: + + \table + \header \o QPtrList function \o QList equivalent + \row \o QPtrList::contains(const T *) \o QList::count(T *) + \row \o QPtrList::containsRef(const T *) \o QList::count(T *) + \row \o QPtrList::find(const T *) \o See remark below + \row \o QPtrList::findRef(const T *) \o See remark below + \row \o QPtrList::getFirst() \o QList::first() + \row \o QPtrList::getLast() \o QList::last() + \row \o QPtrList::inSort(const T *) \o N/A + \row \o QPtrList::remove(const T *) \o QList::removeAll(T *) + \row \o QPtrList::remove(uint) \o QList::removeAt(int) + \row \o QPtrList::removeNode(QLNode *) \o N/A + \row \o QPtrList::removeRef(const T *) \o QList::removeAll(T *) + \row \o QPtrList::sort() \o See remark below + \row \o QPtrList::takeNode(QLNode *) \o N/A + \row \o QPtrList::toVector(QGVector *) \o See remark below + \endtable + + Remarks: + + \list 1 + \o QPtrList::toVector(QGVector *) can be replaced by + QVector::resize() and qCopy(). + + \oldcode + QPtrList<QWidget> list; + ... + QPtrVector<QWidget> vector; + list.toVector(&vector); + \newcode + QList<QWidget *> list; + ... + QVector<QWidget *> vector; + vector.resize(list.size()); + qCopy(list.begin(), list.end(), vector.begin()); + \endcode + + \o QPtrList::sort() relied on the virtual compareItems() to + sort items. In Qt 4, you can use \l qSort() instead and pass + your "compare item" function as an argument. + + \o QPtrList::find(const T *) returns an iterator, whereas + QList::indexOf(T *) returns an index. To convert an index + into an iterator, add the index to QList::begin(). + + \o QPtrList::removeFirst() and QPtrList::removeLast() return a \c + bool that indicates whether the element was removed or not. + The corresponding QList functions return \c void. You can + achieve the same result by calling QList::isEmpty() before + attempting to remove an item. + \endlist + + If you use QPtrList's auto-delete feature (by calling + QPtrList::setAutoDelete(true)), you need to do some more work. + You have two options: Either you call \c delete yourself whenever + you remove an item from the container, or you can use QList<T> + instead of QList<T *> (i.e. store values directly instead of + pointers to values). Here, we'll see when to call \c delete. + + \omit + (See \l{What's Wrong with Auto-Delete} for an explanation of why + the Qt 4 containers don't offer that feature.) + \endomit + + The following table summarizes the idioms that you need to watch + out for if you want to call \c delete yourself. + + \table + \header \o QPtrList idiom \o QList idiom + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 19 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 20 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 21 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 22 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 23 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 24 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 25 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 26 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 27 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 28 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 29 + (removes the current item) + + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 30 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 31 + + (also called from QPtrList's destructor) + + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 32 + + In 99% of cases, the following idiom also works: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 33 + + However, it may lead to crashes if \c list is referenced from + the value type's destructor, because \c list contains + dangling pointers until clear() is called. + \endtable + + Be aware that QPtrList's destructor automatically calls clear(). + If you have a QPtrList data member in a custom class and use the + auto-delete feature, you will need to call \c delete on all the + items in the container from your class destructor to avoid a + memory leak. + + QPtrList had the concept of a "current item", which could be used + for traversing the list without using an iterator. When porting + to Qt 4, you can use the Java-style QListIterator<T *> (or + QMutableListIterator<T *>) class instead. The following table + summarizes the API differences: + + \table + \header \o QPtrList function \o QListIterator equivalent + \row \o QPtrList::at() \o N/A + \row \o QPtrList::current() \o QMutableListIterator::value() + \row \o QPtrList::currentNode() \o N/A + \row \o QPtrList::findNext(const T *) \o QListIterator::findNext(const T *) + \row \o QPtrList::findNextRef(const T *) \o QListIterator::findNext(const T *) + \row \o QPtrList::first() \o QPtrList::toFront() + \row \o QPtrList::last() \o QPtrList::toBack() + \row \o QPtrList::next() \o QPtrList::next() + \row \o QPtrList::prev() \o QPtrList::previous() + \row \o QPtrList::remove() \o QMutableListIterator::remove() + \row \o QPtrList::take() \o QMutableListIterator::remove() + \endtable + + Be aware that QListIterator has a different way of iterating than + QPtrList. A typical loop with QPtrList looks like this: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 34 + + Here's the equivalent QListIterator loop: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 35 + + Finally, QPtrListIterator<T> must also be ported. There are no + fewer than four iterator classes that can be used as a + replacement: QList::const_iterator, QList::iterator, + QListIterator, and QMutableListIterator. The most straightforward + class to use when porting is QMutableListIterator<T *> (if you + modify the list through the iterator) or QListIterator<T *> (if + you don't). The following table summarizes the API differences: + + \table + \header \o QPtrListIterator function \o Qt 4 equivalent + \row \o QPtrListIterator::atFirst() \o !QListIterator::hasPrevious() (notice the \c{!}) + \row \o QPtrListIterator::atLast() \o !QListIterator::hasNext() (notice the \c{!}) + \row \o QPtrListIterator::count() \o QList::count() or QList::size() + \row \o QPtrListIterator::current() \o QMutableListIterator::value() + \row \o QPtrListIterator::isEmpty() \o QList::isEmpty() + \row \o QPtrListIterator::toFirst() \o QListIterator::toFront() + \row \o QPtrListIterator::toLast() \o QListIterator::toBack() + \row \o QPtrListIterator::operator() \o QMutableListIterator::value() + \row \o QPtrListIterator::operator*() \o QMutableListIterator::value() + \endtable + + Again, be aware that QListIterator has a different way of + iterating than QPtrList. A typical loop with QPtrList looks like + this: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 36 + + Here's the equivalent QListIterator loop: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 37 + + Finally, QPtrListStdIterator<T> must also be ported. This is + easy, because QList also provides STL-style iterators + (QList::iterator and QList::const_iterator). + + \section1 QPtrQueue<T> + + QPtrQueue has been moved to the Qt3Support library. + It has been replaced by the more modern QQueue class. + + The following table summarizes the differences between + QPtrQueue<T> and QQueue<T *>: + + \table + \header \o QPtrQueue function \o QQueue equivalent + \row \o QPtrQueue::autoDelete() \o See discussion below + \row \o QPtrQueue::count() \o QQueue::count() or QQueue::size() (equivalent) + \row \o QPtrQueue::current() \o QQueue::head() + \row \o QPtrQueue::remove() \o QQueue::dequeue() + \row \o QPtrQueue::setAutoDelete() \o See discussion below + \endtable + + If you use QPtrQueue's auto-delete feature (by calling + QPtrQueue::setAutoDelete(true)), you need to do some more work. + You have two options: Either you call \c delete yourself whenever + you remove an item from the container, or you can use QQueue<T> + instead of QQueue<T *> (i.e. store values directly instead of + pointers to values). Here, we will show when to call \c delete. + + \omit + (See \l{What's Wrong with Auto-Delete} for an explanation of why + the Qt 4 containers don't offer that feature.) + \endomit + + \table + \header \o QPtrQueue idiom \o QQueue idiom + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 38 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 39 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 40 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 41 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 42 + + (also called from QPtrQueue's destructor) + + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 43 + + In 99% of cases, the following idiom also works: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 44 + + However, it may lead to crashes if \c queue is referenced + from the value type's destructor, because \c queue contains + dangling pointers until clear() is called. + \endtable + + \section1 QPtrStack<T> + + QPtrStack has been moved to the Qt3Support library. + It has been replaced by the more modern QStack class. + + The following table summarizes the differences between + QPtrStack<T> and QStack<T *>: + + \table + \header \o QPtrStack function \o QStack equivalent + \row \o QPtrStack::autoDelete() \o See discussion below + \row \o QPtrStack::count() \o QStack::count() or QStack::size() (equivalent) + \row \o QPtrStack::current() \o QStack::top() + \row \o QPtrStack::remove() \o QStack::pop() + \row \o QPtrStack::setAutoDelete() \o See discussion below + \endtable + + If you use QPtrStack's auto-delete feature (by calling + QPtrStack::setAutoDelete(true)), you need to do some more work. + You have two options: Either you call \c delete yourself whenever + you remove an item from the container, or you can use QStack<T> + instead of QStack<T *> (i.e. store values directly instead of + pointers to values). Here, we will show when to call \c delete. + + \omit + (See \l{What's Wrong with Auto-Delete} for an explanation of why + the Qt 4 containers don't offer that feature.) + \endomit + + \table + \header \o QPtrStack idiom \o QStack idiom + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 45 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 46 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 47 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 48 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 49 + + (also called from QPtrStack's destructor) + + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 50 + + In 99% of cases, the following idiom also works: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 51 + + However, it may lead to crashes if \c stack is referenced + from the value type's destructor, because \c stack contains + dangling pointers until clear() is called. + \endtable + + \section1 QPtrVector<T> + + QPtrVector<T> has been moved to Qt3Support. It has been replaced + by the more modern QVector class. + + When porting to Qt 4, you can use QVector<T *> as an alternative + to QPtrVector<T>. The APIs of QPtrVector<T> and QVector<T *> are + somewhat similar. The main issue is that QPtrVector supports + auto-delete whereas QVector doesn't. + + \omit + (See \l{What's Wrong with Auto-Delete} for an explanation of why + the Qt 4 containers don't offer that feature.) + \endomit + + The following table summarizes the API differences between the + two classes: + + \table + \header \o QPtrVector function \o QVector equivalent + \row \o QPtrVector::autoDelete() \o See discussion below + \row \o QPtrVector::bsearch(const T *) \o \l qBinaryFind() + \row \o QPtrVector::contains(const T *) \o QVector::count(T *) + \row \o QPtrVector::containsRef(const T *) \o QVector::count(T *) + \row \o QPtrVector::count() \o See remark below + \row \o QPtrVector::insert(uint, T *) \o See remark below + \row \o QPtrVector::isNull() \o N/A + \row \o QPtrVector::remove(uint) \o See remark below + \row \o QPtrVector::setAutoDelete() \o See discussion below + \row \o QPtrVector::sort() \o \l qSort() + \row \o QPtrVector::take(uint) \o See remark below + \row \o QPtrVector::toList(QGList *) \o QList::QList(const QVector &) + \endtable + + Remarks: + + \list 1 + \o QPtrVector::insert(uint, T *) sets an item to store a certain + pointer value. This is \e not the same as QVector::insert(int, T *), + which creates space for the item by moving following items by + one position. Use \c{vect[i] = ptr} to set a QVector item to + a particular value. + \o QPtrVector::remove(uint) sets an item to be 0. This is \e not + the same as QVector::removeAt(int), which entirely erases the + item, reducing the size of the vector. Use \c{vect[i] = 0} to + set a QVector item to 0. + \o Likewise, QPtrVector::take(uint) sets an item to be 0 and + returns the previous value of the item. Again, this is easy to + achieve using QVector::operator[](). + \o QPtrVector::count() returns the number of non-null items in + the vector, whereas QVector::count() (like QVector::size()) + returns the number of items (null or non-null) in the vector. + Fortunately, it's not too hard to simulate QPtrVector::count(). + + \oldcode + int numValidItems = vect.count(); + \newcode + int numValidItems = vect.size() - vect.count(0); + \endcode + \endlist + + If you use QVector's auto-delete feature (by calling + QVector::setAutoDelete(true)), you need to do some more work. You + have two options: Either you call \c delete yourself whenever you + remove an item from the container, or you use QVector<T> instead + of QVector<T *> (i.e. store values directly instead of pointers + to values). Here, we'll see when to call \c delete. + + The following table summarizes the idioms that you need to watch + out for if you want to call \c delete yourself. + + \table + \header \o QPtrVector idiom \o QVector idiom + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 52 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 53 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 54 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 55 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 56 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 57 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 58 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 59 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 60 + + (also called from QPtrVector's destructor) + + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 61 + + In 99% of cases, the following idiom also works: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 62 + + However, it may lead to crashes if \c vect is referenced from + the value type's destructor, because \c vect contains + dangling pointers until clear() is called. + \endtable + + Be aware that QPtrVector's destructor automatically calls + clear(). If you have a QPtrVector data member in a custom class + and use the auto-delete feature, you will need to call \c delete + on all the items in the container from your class destructor to + avoid a memory leak. + + \section1 QPushButton + + See \l{#properties}{Properties} for a list of QPushButton + properties in Qt 3 that have changed in Qt 4. + + \section1 QRangeControl + + In Qt 3, various "range control" widgets (QDial, QScrollBar, + QSlider, and QSpin) inherited from both QWidget and + \c QRangeControl. + + In Qt 4, \c QRangeControl has been replaced with the new + QAbstractSlider and QAbstractSpinBox classes, which inherit from + QWidget and provides similar functionality. Apart from eliminating + unnecessary multiple inheritance, the new design allows + QAbstractSlider to provide signals, slots, and properties. + + The old \c QRangeControl class has been renamed Q3RangeControl + and moved to the Qt3Support library, together with + the (undocumented) \c QSpinWidget class. + + If you use \c QRangeControl as a base class in your application, + you can switch to use QAbstractSlider or QAbstractSpinBox instead. + + \oldcode + class VolumeControl : public QWidget, public QRangeControl + { + ... + protected: + void valueChange() { + update(); + emit valueChanged(value()); + } + void rangeChange() { + update(); + } + void stepChange() { + update(); + } + }; + \newcode + class VolumeControl : public QAbstractSlider + { + ... + protected: + void sliderChange(SliderChange change) { + update(); + if (change == SliderValueChange) + emit valueChanged(value()); + } + }; + \endcode + + \section1 QRegExp + + The search() and searchRev() functions have been renamed to indexIn() + and lastIndexIn() respectively. + + \section1 QRegion + + The following changes have been made to QRegion in Qt 4: + + \list + \o There is no longer any difference between a \e null region and + an \e empty region. Use isEmpty() in most places where you + would have used a null QRegion. + \o QRegion::rects() used to return a QMemArray<QRect>. It now returns + a QVector<QRect>. + \endlist + + \section1 QScrollBar + + See \l{#properties}{Properties} for a list of QScrollBar + properties in Qt 3 that have changed in Qt 4. + + \section1 QScrollView + + The \c QScrollView class has been renamed Q3ScrollView and moved + to the Qt3Support library. It has been replaced by + the QAbstractScrollArea and QScrollArea classes. + + Note that Qt 4 in general uses the QScrollArea::widget() function + where Qt 3 used QScrollView::viewport(). The rationale for this is + that it is no longer possible to draw directly on a scroll + area. The QScrollArea::widget() function returns the widget set on + the scroll area. + + \c QScrollView was designed to work around the 16-bit limitation + on widget coordinates found on most window systems. In Qt 4, this + is done transparently for \e all widgets, so there is no longer a + need for such functionality in \c QScrollView. For that reason, + the new QAbstractScrollArea and QScrollArea classes are much more + lightweight, and concentrate on handling scroll bars. + + \section1 QServerSocket + + The \c QServerSocket class has been renamed Q3ServerSocket and + moved to the Qt3Support library. In Qt 4, it has been + replaced by QTcpServer. + + With Q3ServerSocket, connections are accepted by reimplementing a + virtual function (Q3ServerSocket::newConnection()). With + QTcpServer, on the other hand, you don't need to subclass. + Instead, simply connect to the QTcpServer::newConnection() + signal. + + \section1 QSettings + + The QSettings class has been rewritten to be more robust and to + respect existing standards (e.g., the INI file format). The API + has also been extensively revised. The old API is still provided + when Qt 3 support is enabled. + + Since the format and location of settings have changed between Qt + 3 and Qt 4, the Qt 4 version of your application won't recognize + settings written using Qt 3. + + \section1 QShared + + The \c QShared class has been obsoleted by the more powerful + QSharedData and QSharedDataPointer as a means of creating custom + implicitly shared classes. It has been renamed Q3Shared moved to + the Qt3Support library. + + An easy way of porting to Qt 4 is to include this class into your + project and to use it instead of \c QShared: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 63 + + If possible, we recommend that you use QSharedData and + QSharedDataPointer instead. They provide thread-safe reference + counting and handle all the reference counting behind the scenes, + eliminating the risks of forgetting to increment or decrement the + reference count. + + \section1 QSignal + + The QSignal class has been renamed to Q3Signal and moved to the + Qt3Support library. The preferred approach is to create your own + QObject subclass with a signal that has the desired signature. + Alternatively, you can call QMetaObject::invokeMethod() if you + want to invoke a slot. + + \section1 QSimpleRichText + + QSimpleRichText has been obsoleted by QTextDocument. It has + bene renamed Q3SimpleRichText and moved to the Qt3Support + library. + + Previously, you would do the following with Q3SimpleRichText: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 63a + + However, with QTextDocument, you use the following code instead: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 63b + + See \l{Rich Text Processing} for an overview of the Qt 4 rich + text classes. + + \section1 QSlider + + The QSlider::sliderStart() and QSlider::sliderRect() functions + have been removed. + + The slider's rect can now be retrieved using the code snippet below: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 63c + + In addition, the direction of a vertical QSlider has changed, + i.e. the bottom is now the minimum, and the top the maximum. You + can use the QAbstractSlider::invertedAppearance property to + control this behavior. + + See \l{#properties}{Properties} for a list of QSlider properties + in Qt 3 that have changed in Qt 4. + + \section1 QSocket + + The \c QSocket class has been renamed Q3Socket and moved to the + Qt3Support library. In Qt 4, it has been replaced by + the QTcpSocket class, which inherits most of its functionality + from QAbstractSocket. + + \section1 QSocketDevice + + The \c QSocketDevice class has been renamed Q3SocketDevice and + moved to the Qt3Support library. In Qt 4, there is no + direct equivalent to Q3SocketDevice: + + \list \o If you use Q3SocketDevice in a thread to perform blocking + network I/O (a technique encouraged by the \e{Qt Quarterly} + article \l{http://qt.nokia.com/doc/qq/qq09-networkthread.html} + {Unblocking Networking}), you can now use QTcpSocket, QFtp, or + QNetworkAccessManager, which can be used from non-GUI threads. + + \o If you use Q3SocketDevice for UDP, you can now use QUdpSocket instead. + + \o If you use Q3SocketDevice for other uses, Qt 4 offers no + alternative right now. However, there is a \c QAbstractSocketEngine + internal class that offers a low-level socket API similar to + Q3SocketDevice. Should the need for such functionality arise in + Qt 4 applications, we will consider making this class public in a + future release. + \endlist + + \section1 QSortedList + + The QSortedList<T> class has been deprecated since Qt 3.0. In Qt + 4, it has been moved to the Qt3Support library. + + In new code, we recommend that you use QList<T> instead and use + \l qSort() to sort the items. + + \section1 QSplitter + + The function setResizeMode() has been moved into Qt3Support. Set + the stretch factor in the widget's size policy to get equivalent + functionality. + + The obsolete function drawSplitter() has been removed. Use + QStyle::drawPrimitive() to acheive similar functionality. + + \section1 QSpinBox + + See \l{#properties}{Properties} for a list of QSpinBox properties + in Qt 3 that have changed in Qt 4. + + \section1 QSqlCursor + + The \c QSqlCursor class has been renamed Q3SqlCursor and moved to + the Qt3Support library. In Qt 4, you can use + QSqlQuery, QSqlQueryModel, or QSqlTableModel, depending on + whether you want a low-level or a high-level interface for + accessing databases. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QSqlDatabase + + QSqlDatabase is now a smart pointer that is passed around by + value. Simply replace all QSqlDatabase pointers by QSqlDatabase + objects. + + \section1 QSqlEditorFactory + + The \c QSqlEditorFactory class has been renamed + Q3SqlEditorFactory and moved to Qt3Support. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QSqlError + + The enum \c{Type} was renamed to \c{ErrorType}, The values were renamed as well: + + \list + \o None - use NoError instead + \o Connection - use ConnectionError instead + \o Statement - use StatementError instead + \o Transaction - use TransactionError instead + \o Unknown - use UnknownError instead + \endlist + + \section1 QSqlFieldInfo + + The QSqlFieldInfo class has been moved to Qt3Support. Its + functionality is now provided by the QSqlField class. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QSqlForm + + The \c QSqlForm class has been renamed Q3SqlForm and moved to the + Qt3Support library. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QSqlPropertyMap + + The \c QSqlPropertyMap class has been renamed Q3SqlPropertyMap + moved to the Qt3Support library. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QSqlQuery + + QSqlQuery::prev() was renamed to QSqlQuery::previous(). + QSqlQuery::prev() remains, but it just calls previous(). + QSqlQuery no longer has any virtual methods, i.e., exec(), + value(), seek(), next(), prev(), first(), last(), and the + destructor are no longer virtual. + + \section1 QSqlRecord + + QSqlRecord behaves like a vector now, QSqlRecord::insert() will + actually insert a new field instead of replacing the existing + one. + + \section1 QSqlRecordInfo + + The QSqlRecordInfo class has been moved to Qt3Support. Its + functionality is now provided by the QSqlRecord class. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QSqlSelectCursor + + The \c QSqlSelectCursor class has been renamed Q3SqlSelectCursor + and moved to the Qt3Support library. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QStoredDrag + + The \c QStoredDrag class has been renamed Q3StoredDrag and moved + to the Qt3Support library. In Qt 4, use QMimeData + instead and call QMimeData::setData() to set the data. + + See \l{Porting to Qt 4 - Drag and Drop} for a comparison between + the drag and drop APIs in Qt 3 and Qt 4. + + \section1 QStr(I)List + + The QStrList and QStrIList convenience classes have been + deprecated since Qt 2.0. In Qt 4, they have been moved to the + Qt3Support library. If you used any of these, we + recommend that you use QStringList or QList<QByteArray> instead. + + \section1 QStr(I)Vec + + The QStrVec and QStrIVec convenience classes have been deprecated + since Qt 2.0. In Qt 4, they have been moved to Qt3Support. If you + used any of these, we recommend that you use QStringList or + QList<QByteArray> instead. + + \section1 QString + + Here are the main issues to be aware of when porting QString to + Qt 4: + + \list 1 + \o The QString::QString(QChar) constructor performed implicit + conversion in Qt 3. Now, you will need a cast to convert a + QChar to a QString. + + \o The QString::QString(const QByteArray &) constructor used to + stop at the first '\\0' it encountered, for compatibility + with Qt 1. This quirk has now been fixed; in Qt 4, the + resulting QString always has the same length as the + QByteArray that was passed to the constructor. + + \o The QString::null static constant has been deprecated in Qt + 4. For compatibility, Qt 4 provides a QString::null symbol + that behaves more or less the same as the old constant. The + new idiom is to write QString() instead of QString::null, or + to call clear(). + + \oldcode + str1 = QString::null; + if (str2 == QString::null) + do_something(QString::null); + \newcode + str1.clear(); + if (str2.isNull()) + do_something(QString()); + \endcode + + In new code, we recommend that you don't rely on the + distinction between a null string and a (non-null) empty + string. See \l{Distinction Between Null and Empty Strings} + for details. + + \o QString::latin1() and QString::ascii() have been replaced + with QString::toLatin1() and QString::toAscii(), which return + a QByteArray instead of a (non-reentrant) \c{const char *}. + For consistency, QString::utf8() and QString::local8Bit(), + which already returned a QByteArray (actually a \c QCString), + have been renamed QString::toUtf8() and + QString::toLocal8Bit(). + + To obtain a \c{const char *} pointer to ASCII or Latin-1 data, + use QString::toAscii() or QString::toLatin1() to obtain a + QByteArray containing the data, then call QByteArray::constData() + to access the character data directly. Note that the pointer + returned by this function is only valid for the lifetime of the + byte array; you should avoid taking a pointer to the data + contained in temporary objects. + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 64 + + In the above example, the \c goodData pointer is valid for the lifetime + of the \c asciiData byte array. If you need to keep a copy of the data + in a non-Qt data structure, use standard C memory allocation and string + copying functions to do so \e before destroying the byte array. + + \o QString::at() returned a non-const reference, whereas the + new QString::at() returns a const value. Code like + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 65 + + will no longer compile. Instead, use QString::operator[]: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 66 + + \o The QString::contains(\e x) function (where \e x is a + character or a string) has been renamed QString::count(\e x). + In addition, there now exists a set of QString::contains() + functions that returns a boolean value. Replace old calls to + contains() with either count() or contains(), depending on + whether you care about the specific number of occurrences of + a character in the string or only care about whether the + string contains that character or not. + + \o Many functions in QString had a \c bool parameter that + specified case sensitivity. In Qt 4, in the interest of code + readability and maintainability, the \c bool parameters have + been replaced by the Qt::CaseSensitivity enum, which can take + the values Qt::CaseSensitive and Qt::CaseInsensitive. + + \oldcode + if (url.startsWith("http:", false)) + ... + \newcode + if (url.startsWith("http:", Qt::CaseInsensitive)) + ... + \endcode + + \o The QString::setExpand(uint, QChar) function, which already + was obsolete in Qt 3, is no longer available. Use + QString::operator[] instead. + + \oldcode + str.setExpand(32, '$'); + \newcode + str[32] = '$'; + \endcode + + \o The \c QT_NO_ASCII_CAST and \c QT_NO_CAST_ASCII macros have + been renamed \c QT_NO_CAST_TO_ASCII and \c + QT_NO_CAST_FROM_ASCII, respectively. + + \o The QString::data() used to return the same as + QString::ascii(). It now returns a pointer to the Unicode + data stored in the QString object. Call QString::ascii() if + you want the old behavior. + + \o QString::arg() now converts two-digit place markers, allowing + up to 99 place markers to be used in any given string. + + \o Comparisons between QStrings and \c NULL in order to determine + whether strings are empty are no longer allowed. + Use \l{QString::}{isEmpty()} instead. + + \endlist + + \section1 QStringList + + QStringList now inherits from QList<QString> and can no longer be + converted to a QValueList<QString>. Since QValueList inherits QList a + cast will work as expected. + + This change implies some API incompatibilities for QStringList. + For example, at() returns the string, not an iterator. See the + \l{#qvaluelist.section}{section on QValueList} for details. + + The static QStringList::split() function for splitting strings into + lists of smaller strings has been replaced by QString::split(), + which returns a QStringList. + + \section1 QStyle + + The QStyle API has been overhauled and improved. Most of the information on + why this change was done is described in \l{The Qt 4 Style API}{the QStyle overview}. + + Since QStyle is mostly used internally by Qt's widgets and styles and since + it is not essential to the good functioning of an application, there is no + compatibility path. This means that we have changed many enums and + functions and the qt3to4 porting tool will not change much in your qstyle + code. To ease the pain, we list some of the major changes here. + + QStyleOption has taken on a more central role and is no longer an optional + argument, please see the QStyleOption documentation for more information. + + The QStyle::StyleFlags have been renamed QStyle::StateFlags and are now prefixed State_ + instead of Style_, in addition the Style_ButtonDefault flag has moved to + QStyleOptionButton. + + The QStyle::PrimitiveElement enumeration has undergone extensive change. + Some of the enums were moved to QStyle::ControlElement, some were removed + and all were renamed. This renaming is not done by the qt3to4 porting tool, + so you must do it yourself. The table below shows how things look + now. + + \table + \header \o Old name \o New name \o Remark + \row \o \c PE_ButtonCommand \o QStyle::PE_PanelButtonCommand + \row \o \c PE_ButtonDefault \o QStyle::PE_FrameDefaultButton + \row \o \c PE_ButtonBevel \o QStyle::PE_PanelButtonBevel + \row \o \c PE_ButtonTool \o QStyle::PE_PanelButtonTool + \row \o \c PE_ButtonDropDown \o QStyle::PE_IndicatorButtonDropDown + \row \o \c PE_FocusRect \o QStyle::PE_FrameFocusRect + \row \o \c PE_ArrowUp \o QStyle::PE_IndicatorArrowUp + \row \o \c PE_ArrowDown \o QStyle::PE_IndicatorArrowDown + \row \o \c PE_ArrowRight \o QStyle::PE_IndicatorArrowRight + \row \o \c PE_ArrowLeft \o QStyle::PE_IndicatorArrowLeft + \row \o \c PE_SpinBoxUp \o QStyle::PE_IndicatorSpinUp + \row \o \c PE_SpinBoxDown \o QStyle::PE_IndicatorSpinDown + \row \o \c PE_SpinBoxPlus \o QStyle::PE_IndicatorSpinPlus + \row \o \c PE_SpinBoxMinus \o QStyle::PE_IndicatorSpinMinus + \row \o \c PE_SpinBoxSlider \o QStyle::CE_SpinBoxSlider \o uses QStyle::drawControl() + \row \o \c PE_Indicator \o QStyle::PE_IndicatorCheckBox + \row \o \c PE_IndicatorMask \o N/A \o use QStyle::styleHint() to retrieve mask + \row \o \c PE_ExclusiveIndicator \o QStyle::PE_IndicatorRadioButton + \row \o \c PE_ExclusiveIndicatorMask \o N/A \o use QStyle::styleHint() to retrieve mask + \row \o \c PE_DockWindowHandle \o QStyle::PE_IndicatorToolBarHandle + \row \o \c PE_DockWindowSeparator \o QStyle::PE_Q3DockWindowSeparator + \row \o \c PE_DockWindowResizeHandle \o QStyle::PE_IndicatorDockWindowResizeHandle + \row \o \c PE_DockWindowTitle \o QStyle::CE_DockWindowTitle \o uses QStyle::drawControl() + \row \o \c PE_Splitter \o QStyle::CE_Splitter \o uses QStyle::drawControl() + \row \o \c PE_Panel \o QStyle::PE_Frame + \row \o \c PE_PanelMenu \o QStyle::PE_FrameMenu + \row \o \c PE_PanelMenuBar \o QStyle::PE_PanelMenuBar + \row \o \c PE_PanelDockWindow \o QStyle::PE_FrameDockWindow + \row \o \c PE_TabBarBase \o QStyle::PE_FrameTabBarBase + \row \o \c PE_HeaderSection \o QStyle::CE_HeaderSection \o uses QStyle::drawControl() + \row \o \c PE_HeaderArrow \o QStyle::PE_IndicatorHeaderArrow + \row \o \c PE_StatusBarSection \o QStyle::PE_FrameStatusBar + \row \o \c PE_Separator \o QStyle::PE_Q3Separator + \row \o \c PE_SizeGrip \o QStyle::CE_SizeGrip \o uses QStyle::drawControl() + \row \o \c PE_CheckMark \o QStyle::PE_IndicatorMenuCheckMark + \row \o \c PE_ScrollBarAddLine \o QStyle::CE_ScrollBarAddLine \o uses QStyle::drawControl() + \row \o \c PE_ScrollBarSubLine \o QStyle::CE_ScrollBarSubLine \o uses QStyle::drawControl() + \row \o \c PE_ScrollBarAddPage \o QStyle::CE_ScrollBarAddPage \o uses QStyle::drawControl() + \row \o \c PE_ScrollBarSubPage \o QStyle::CE_ScrollBarSubPage \o uses QStyle::drawControl() + \row \o \c PE_ScrollBarSlider \o QStyle::CE_ScrollBarSlider \o uses QStyle::drawControl() + \row \o \c PE_ScrollBarFirst \o QStyle::CE_ScrollBarFirst \o uses QStyle::drawControl() + \row \o \c PE_ScrollBarLast \o QStyle::CE_ScrollBarLast \o uses QStyle::drawControl() + \row \o \c PE_ProgressBarChunk \o QStyle::PE_IndicatorProgressChunk + \row \o \c PE_PanelLineEdit \o QStyle::PE_FrameLineEdit + \row \o \c PE_PanelTabWidget \o QStyle::PE_FrameTabWidget + \row \o \c PE_WindowFrame \o QStyle::PE_FrameWindow + \row \o \c PE_CheckListController \o QStyle::PE_Q3CheckListController + \row \o \c PE_CheckListIndicator \o QStyle::PE_Q3CheckListIndicator + \row \o \c PE_CheckListExclusiveIndicato\o QStyle::PE_Q3CheckListExclusiveIndicator + \row \o \c PE_PanelGroupBox \o QStyle::PE_FrameGroupBox + \row \o \c PE_TreeBranch \o QStyle::PE_IndicatorBranch + \row \o \c PE_RubberBand \o QStyle::CE_RubberBand \o uses QStyle::drawControl() + \row \o \c PE_PanelToolBar \o QStyle::PE_PanelToolBar + \row \o \c PE_ToolBarHandle \o QStyle::PE_IndicatorToolBarHandle + \row \o \c PE_ToolBarSeparator \o QStyle::PE_IndicatorToolBarSeparator + \endtable + + The QStyle::drawControlMask() and QStyle::drawComplexControlMask() + functions have been removed. They are replaced with a style hint. + + The QStyle::drawItem() overloads that took both a pixmap and a string have + been removed. Use QStyle::drawItemText() and QStyle::drawItemPixmap() directly. + + The QStyle::itemRect() overload that took both a pixmap and a string is also removed, use + either QStyle::itemTextRect() or QStyle::itemPixmapRect() instead. + + \section1 QStyleSheet + + The QStyleSheet and QStyleSheetItem classes have been renamed + Q3StyleSheet and Q3StyleSheetItem, and have been moved to the + Qt3Support library. + + See \l{Rich Text Processing} for an overview of the Qt 4 rich + text classes, and \l{Qt Style Sheets} for a description of + CSS-like style sheet support in Qt 4.2 and above. + + \section1 QSyntaxHighlighter + + The \c QSyntaxHighlighter class from Qt 3 has been renamed + Q3SyntaxHighlighter and moved to the Qt3Support library. Since Qt + 4.1, it has been replaced by a new QSyntaxHighlighter class based + on Qt 4's new rich text engine. + + \section1 QTabBar + + See \l{#properties}{Properties} for a list of QTabBar properties + in Qt 3 that have changed in Qt 4. + + \section1 QTabDialog + + The \c QTabDialog class is no longer part of the public Qt API. + It has been renamed Q3TabDialog and moved to Qt3Support. In Qt 4 + applications, you can easily obtain the same result by combining + a QTabWidget with a QDialog and provide \l{QPushButton}s + yourself. + + See also the \l{dialogs/tabdialog} example, which shows how to + implement tab dialogs in Qt 4. + + \section1 QTabWidget + + See \l{#properties}{Properties} for a list of QTabWidget + properties in Qt 3 that have changed in Qt 4. + + \section1 QTable + + The \c QTable, \c QTableItem, \c QComboTableItem, \c + QCheckTableItem, and \c QTableSelection classes have been renamed + Q3Table, Q3TableItem, Q3ComboTableItem, Q3CheckTableItem, and + Q3TableSelection and moved to the Qt3Support library. + New Qt applications should use the new QTableWidget or QTableView + class instead. + + Some of these classes behave differently with respect to the way + they handle \c NULL pointers. For example, Q3TableItem::setPixmap() + no longer accepts \c NULL or 0 to indicate that the item should + contain a null pixmap; in this case, a null pixmap should be + constructed and passed explicitly to the function. + + See \l{Model/View Programming} for an overview of the new item + view classes. + + \section1 QTextCodec + + The loadCharmap() and loadCharmapFromFile() functions are no longer + available in Qt 4. You need to create your own codec if you want to + create a codec based on a POSIX2 charmap definition. + + \section1 QTextDrag + + The \c QTextDrag class has been renamed Q3TextDrag and moved to + the Qt3Support library. In Qt 4, use QMimeData + instead and call QMimeData::setText() to set the data. + + See \l{Porting to Qt 4 - Drag and Drop} for a comparison between + the drag and drop APIs in Qt 3 and Qt 4. + + \section1 QTextEdit + + The old QTextEdit and QTextBrowser classes have been renamed + Q3TextEdit and Q3TextBrowser, and have been moved to Qt3Support. + The new QTextEdit and QTextBrowser have a somewhat different API. + + The \c QTextEdit::setWrapPolicy() function has been renamed to \l{QTextEdit::setWordWrapMode()}{setWordWrapMode()} and the + \c QTextEdit::setWrapColumnOrWidth() function has been renamed to \l{QTextEdit::setLineWrapColumnOrWidth()} + {setLineWrapColumnOrWidth()}. The Q3TextEdit::setWrapPolicy() and Q3TextEdit::setWrapColumnOrWidth() still provide this + functionality in the Q3TextEdit class. + + + See \l{Rich Text Processing} for an overview of the Qt 4 rich + text classes. + + \section1 QTextIStream + + The QTextIStream convenience class is no longer provided in Qt 4. Use + QTextStream directly instead. + + \section1 QTextOStream + + The QTextOStream convenience class is no longer provided in Qt 4. Use + QTextStream directly instead. + + \section1 QTextOStreamIterator + + The undocumented \c QTextOStreamIterator class has been removed + from the Qt library. If you need it in your application, feel + free to copy the source code from the Qt 3 \c <qtl.h> header + file. + + \section1 QTextStream + + QTextStream has undergone a number of API and implementation enhancements, + and some of the changes affect QTextStream's behavior: + + \list + \o QTextStream now uses buffered writing, which means that you need to + call QTextStream::flush(), or use the streaming manipulators \c endl or + \c flush if you need QTextStream to flush its write buffer. The stream is + flushed automatically if QTextStream is deleted or when the device is + closed. + \o QTextStream now uses buffered reading, so if you read a line from the + stream, QTextStream will read as much as it can from the device to + fill up its internal read buffer. This speeds up reading significantly, + but Qt 3 code that mixed QTextStream access and direct device access + may need to be updated. + \o While QTextStream in Qt 3 always translated end-of-line characters from + Windows style ("\\r\\n") to Unix style ("\\n") on Windows, QTextStream in + Qt 4 only does this on devices opened with the \c{QIODevice::Text} mode + (formerly \c{IO_Translate}). + \endlist + + Note that when using a QTextStream on a QFile in Qt 4, calling + QIODevice::reset() on the QFile will not have the expected result + because QTextStream now buffers the file. Use the + QTextStream::seek() function instead. + + \section1 QTextView + + The \c QTextView class has been renamed Q3TextView and moved to the + Qt3Support library. + + \section1 QTimeEdit + + The QTimeEdit class in Qt 4 is a convenience class based on + QDateTimeEdit. The old class has been renamed Q3TimeEdit and moved + to the Qt3Support library. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of \c QTimeEdit virtual member functions in Qt 3 that are no + longer virtual in Qt 4. + + \section1 QTimer + + Windows restricts the granularity of timers, but starting with Qt 4, + we emulate a finer time resolution. On Windows XP we use the + multimedia timer API, which gives us 1 millisecond resolution for + QTimer. + + Note that other versions of Windows have a lower timer resolution, + and that code relying on underlying system timer restrictions + encounters no such limitations using Qt 4 (e.g., setting an + interval of 0 millisecond results in Qt occupying all of the + processor time when no GUI events need processing). + + \section1 QToolBar + + The old \c QToolBar class, which worked with the old \c + QMainWindow and \c QDockArea classes and inherited from \c + QDockWindow, has been renamed Q3ToolBar and moved to + Qt3Support. Note that, when using Q3ToolBar, the toolbar's actions + must be \l {Q3Action}s. + + Use the new QToolBar class in new applications. + + \note \l{Q3ToolBar}'s + \l{Q3DockWindow::setHorizontallyStretchable()}{horizontallyStretchable} + property can be achieved in QToolBar with + \l{QWidget#Size Hints and Size Policies}{size policies}. + + \section1 QToolButton + + See \l{#properties}{Properties} for a list of QToolButton properties + in Qt 3 that have changed in Qt 4. + + Note that many of the properties that could previously be set in + the constructor must now be set separately. + + \section1 QToolTip + + The QToolTip::setGloballyEnabled() function no longer exists. + Tooltips can be disabled by \l{QObject::installEventFilter()}{installing + an event filter} on qApp (the unique QApplication object) to block events + of type QEvent::ToolTip. + + \section1 QUriDrag + + The \c QUriDrag class has been renamed Q3UriDrag and moved to the + Qt3Support library. In Qt 4, use QMimeData instead + and call QMimeData::setUrl() to set the URL. + + See \l{Porting to Qt 4 - Drag and Drop} for a comparison between + the drag and drop APIs in Qt 3 and Qt 4. + + \section1 QUrl + + The QUrl class has been rewritten from scratch in Qt 4 to be more + standard-compliant. The old QUrl class has been renamed Q3Url and + moved to the Qt3Support library. + + The new QUrl class provides an extensive list of compatibility + functions to ease porting from Q3Url to QUrl. A few functions + require you to change your code: + + \list + \o Q3Url::Q3Url(const Q3Url &, const QString &, bool) can be + simulated by combining the URLs manually (using + QString::operator+(), for example). + \o Q3Url::setEncodedPathAndQuery(const QString &) is replaced by + QUrl::setPath() and QUrl::setEncodedQuery(). + \o Q3Url::encodedPathAndQuery() is replaced by QUrl::path() and + QUrl::encodedQuery(). + \o Q3Url::isLocalFile() can be simulated by checking that + QUrl::protocol() is "file". + \o Q3Url::toString(bool, bool) is replaced by + QUrl::toString(int), where the \c int parameter specifies a + combination of \l{QUrl::FormattingOptions}{formatting + options}. + \endlist + + \section1 QUrlOperator + + The \c QUrlOperator class is no longer part of the public Qt API. + It has been renamed Q3UrlOperator and moved to Qt3Support. + + From Qt 4.4, the Network Access API provides a subset of the features + provided by \c QUrlOperator that are mostly intended for use with + applications that use the HTTP and FTP protocols. See the + QNetworkRequest, QNetworkReply, and QNetworkAccessManager documentation + for further details. + + \target qvaluelist.section + \section1 QValueList<T> + + The QValueList<T> class has been replaced by QList<T> and + QLinkedList<T> in Qt 4. As a help when porting older Qt + applications, the Qt3Support library contains a + QValueList<T> class implemented in terms of the new + QLinkedList<T>. Similarly, it contains QValueListIterator<T> and + QValueListConstIterator<T> classes implemented in terms of + QLinkedList<T>::iterator and QLinkedList<T>::const_iterator. + + When porting to Qt 4, you have the choice of using QList<T> or + QLinkedList<T> as alternatives to QValueList<T>. QList<T> has an + index-based API and provides very fast random access + (QList::operator[]), whereas QLinkedList<T> has an iterator-based + API. + + Here's a list of problem functions: + + \list + \o QValueList(const std::list<T> &) doesn't exist in QList or + QLinkedList. You can simulate it by calling + \l{QLinkedList::append()}{append()} in a loop. + + \o QValueList::insert(iterator, size_type, const T& x) doesn't + exist in QList or QLinkedList. Call + \l{QLinkedList::insert()}{insert()} repeatedly instead. + + \o QValueList::fromLast() doesn't exist in QList or QLinkedList. Use + QValueList::end() instead. + + \oldcode + for (QValueList<T>::iterator i = list.fromLast(); i != list.begin(); --i) + do_something(*i); + \newcode + QLinkedList<T>::iterator i = list.end(); + while (i != list.begin()) { + --i; // decrement i before using it + do_something(*i); + } + \endcode + + \o QValueList::append() and QValueList::prepend() return an + iterator to the inserted item. QList's and QLinkedList's + corresponding functions don't, but it's not a problem because + QValueList::prepend() always returns begin() and append() + always returns QValueList::end() - 1. + + \o QValueList::at(\e i) return an iterator to the item at index + \e i. This corresponds to QList::begin() + \e i. + + \o QValueList::contains(const T &) corresponds to + QList::count(const T &) and QLinkedList::count(const T &). + \endlist + + \section1 QValueVector<T> + + The QValueVector<T> class has been replaced by QVector<T> in Qt + 4. As a help when porting older Qt applications, the Qt3Support + library contains a Q3ValueVector<T> class implemented in terms of + the new QVector<T>. + + When porting from QValueVector<T> to QVector<T>, you might run + into the following incompatibilities: + + \list + \o QValueVector(const std::vector<T> &) doesn't exist in QVector. + You can simulate it by calling QVector::append()} in a loop. + \o QValueVector::resize(int, const T &) doesn't exist in QVector. + If you want the new items to be initialized with a particular + value, use QVector::insert() instead. + \o QValueVector::at() on a non-const vector returns a non-const + reference. This corresponds to QVector::operator[](). + \o Both QValueVector::at() functions have an \e ok parameter of + type \c{bool *} that is set to true if the index is within + bounds. This functionality doesn't exist in QVector; instead, + check the index against QVector::size() yourself. + \endlist + + See \l{Generic Containers} for an overview of the Qt 4 container + classes. + + \section1 QVariant + + Some changes to the rest of the Qt library have + implications on QVariant: + + \list 1 + \o The \c QVariant::ColorGroup enum value is defined only + if \c QT3_SUPPORT is defined. + \o The \c QVariant::IconSet enum value has been renamed + QVariant::Icon. + \o The \c QVariant::CString enum value is now a synonym for + QVariant::ByteArray. + \endlist + + Also, the QVariant(bool, int) constructor has been replaced by QVariant(bool). + Old code like QVariant(true, 0) should be replaced with QVariant(true); otherwise, + the QVariant(int, void *) overload might accidentally be triggered. + + Many of QVariant's convenience functions in Qt 3, such as toColor() and + toKeySequence(), have been removed to enable QVariant to be part of the + QtCore module. QVariant is still able to hold values of these types. + + Types which are not supported by any of the QVariant constructors can be + stored as variants with the QVariant::fromValue() function. Types with no + suitable convenience function for unpacking can be retrieved with the + QVariant::value() function or passed directly to classes that implement + the QVariant() operator. + + \table + \header \o Qt 3 function \o Qt 4 function + \input porting/porting4-removedvariantfunctions.qdocinc + \endtable + + See the QVariant::Type enum for a list of types supported by QVariant. + + \section1 QVBox + + The \c QVBox class is now only available as Q3VBox in Qt 4. You + can achieve the same result as \c QVBox by creating a QWidget + with a vertical layout: + + \oldcode + QVBox *vbox = new QVBox; + QPushButton *child1 = new QPushButton(vbox); + QPushButton *child2 = new QPushButton(vbox); + \newcode + QWidget *vbox = new QWidget; + QPushButton *child1 = new QPushButton; + QPushButton *child2 = new QPushButton; + + QVBoxLayout *layout = new QVBoxLayout; + layout->addWidget(child1); + layout->addWidget(child2); + vbox->setLayout(layout); + \endcode + + Note that child widgets are not automatically placed into the widget's + layout; you will need to manually add each widget to the QVBoxLayout. + + \section1 QVGroupBox + + The \c QVGroupBox class has been renamed Q3VGroupBox and moved to + the Qt3Support library. + Qt 4 does not provide a specific replacement class for \c QVGroupBox + since QGroupBox is designed to be a generic container widget. As a + result, you need to supply your own layout for any child widgets. + + See \l{#QGroupBox} for more information about porting code that uses + group boxes. + + \section1 QWhatsThis + + The QWhatsThis class has been redesigned in Qt 4. The old \c + QWhatsThis class is available as Q3WhatsThis in Qt3Support. + + \section1 QWidget + + Widget background painting has been greatly improved, supporting + flicker-free updates and making it possible to have + semi-transparent widgets. This renders the following background + handling functions obsolete: + + \list + \o QWidget::repaint(bool noErase) - the \c noErase boolean parameter is gone + \o QWidget::setBackgroundMode(BackgroundMode m) + \o QWidget::backgroundBrush() const + \o QWidget::setBackgroundPixmap(const QPixmap &pm) + \o QWidget::backgroundPixmap() const + \o QWidget::setBackgroundColor(const QColor &c) + \o QWidget::backgroundColor() const + \o QWidget::foregroundColor() const + \o QWidget::eraseColor() const + \o QWidget::setEraseColor(const QColor &c) + \o QWidget::erasePixmap() const + \o QWidget::setErasePixmap(const QPixmap &p) + \o QWidget::paletteForegroundColor() + \o QWidget::setPaletteForegroundColor(const QColor &c) + \o QWidget::paletteBackgroundColor() + \o QWidget::setPaletteBackgroundColor(const QColor &c) + \o QWidget::paletteBackgroundPixmap() const + \o QWidget::setPaletteBackgroundPixmap(const QPixmap &p) + \o QWidget::erase() + \o QWidget::erase(const QRect &r) + \o QWidget::setBackgroundOrigin( BackgroundOrigin ) + \o QWidget::BackgroundOrigin backgroundOrigin() const + \o QWidget::backgroundOffset() + \endlist + + Sample code on how to do obtain similar behavior from Qt 4, previously + handled by some of the above functions can be found in the + \l{http://qt.nokia.com/doc/qwidget-qt3.html}{Qt 3 Support Members for QWidget} + page. + + A widget now receives change events in its QWidget::changeEvent() + handler. This makes the following virtual change handlers obsolete: + + \list + \o QWidget::styleChange - use QEvent::StyleChange + \o QWidget::enabledChange - use QEvent::EnabledChange + \o QWidget::paletteChange - use QEvent::PaletteChange + \o QWidget::fontChange - use QEvent::FontChange + \o QWidget::windowActivationChange - use QEvent::ActivationChange + \o QWidget::languageChange - use QEvent::LanguageChange + \endlist + + The following functions were slots, but are no more: + \list + \o QWidget::clearFocus() + \o QWidget::setMouseTracking() + \o QWidget::stackUnder(QWidget*) + \o QWidget::move(int x, int y) + \o QWidget::move(const QPoint &) + \o QWidget::resize(int w, int h) + \o QWidget::resize(const QSize &) + \o QWidget::setGeometry(int x, int y, int w, int h) + \o QWidget::setGeometry(const QRect &) + \o QWidget::adjustSize() + \o QWidget::update(int x, int y, int w, int h) + \o QWidget::update(const QRect&) + \o QWidget::repaint(bool erase) + \o QWidget::repaint(int x, int y, int w, int h, bool erase) + \o QWidget::repaint(const QRect &, bool erase) + \o QWidget::repaint(const QRegion &, bool erase) + \o QWidget::setCaption(const QString &) + \o QWidget::setIcon(const QPixmap &) + \o QWidget::setIconText(const QString &) + \endlist + + The following functions were incorrectly marked as virtual: + + \list + \o QWidget::close(bool alsoDelete) + \o QWidget::create(WId, bool, bool) + \o QWidget::destroy(bool) + \o QWidget::move(int x, int y) + \o QWidget::reparent(QWidget *parent, WFlags, const QPoint &, bool) + \o QWidget::resize(int w, int h) + \o QWidget::setAcceptDrops(bool on) + \o QWidget::setActiveWindow() + \o QWidget::setAutoMask(bool) + \o QWidget::setBackgroundColor(const QColor &) + \o QWidget::setBackgroundMode(BackgroundMode) + \o QWidget::setBackgroundOrigin(BackgroundOrigin) + \o QWidget::setBackgroundPixmap(const QPixmap &) + \o QWidget::setCaption(const QString &) + \o QWidget::setCursor(const QCursor &) + \o QWidget::setEnabled(bool) + \o QWidget::setEraseColor(const QColor &) + \o QWidget::setErasePixmap(const QPixmap &) + \o QWidget::setFocus() + \o QWidget::setFocusPolicy(FocusPolicy) + \o QWidget::setFocusProxy(QWidget *) + \o QWidget::setFont(const QFont &) + \o QWidget::setGeometry(const QRect &) + \o QWidget::setGeometry(int x, int y, int w, int h) + \o QWidget::setIcon(const QPixmap &) + \o QWidget::setIconText(const QString &) + \o QWidget::setKeyCompression(bool) + \o QWidget::setMask(const QBitmap &) + \o QWidget::setMask(const QRegion &) + \o QWidget::setMaximumSize(int maxw, int maxh) + \o QWidget::setMicroFocusHint(int x, int y, int w, int h, bool, QFont *f) + \o QWidget::setMinimumSize(int minw, int minh) + \o QWidget::setMouseTracking(bool enable) + \o QWidget::setPalette(const QPalette &) + \o QWidget::setPaletteBackgroundColor(const QColor &) + \o QWidget::setPaletteBackgroundPixmap(const QPixmap &) + \o QWidget::setSizeIncrement(int w, int h) + \o QWidget::setSizePolicy(QSizePolicy) + \o QWidget::setUpdatesEnabled(bool enable) + \o QWidget::setWState(uint) + \o QWidget::show() + \o QWidget::showFullScreen() + \o QWidget::showMaximized() + \o QWidget::showMinimized() + \o QWidget::showNormal() + \o QWidget::sizePolicy() + \o QWidget::unsetCursor() + \endlist + + The internal clearWState() function was removed. Use + QWidget::setAttribute() instead. + + setWFlags() was renamed QWidget::setWindowFlags(). + + clearWFlags() has no direct replacement. You can use + QWidget::setAttribute() instead. For example, + \c{setAttribute(..., false)} to clear an attribute. More information + is available \l{http://qt.nokia.com/doc/qwidget.html#setAttribute}{here}. + + testWFlags() was renamed to \l{QWidget::testAttribute()}{testAttribute()}. + + See \l{#properties}{Properties} for a list of QWidget properties + in Qt 3 that have changed in Qt 4. + + \section1 QWidgetFactory + + The \c QWidgetFactory class has been replaced by QFormBuilder in Qt 4. + + \section1 QWidgetIntDict + + The QWidgetIntDict class was a synonym for QIntDict<QWidget>. It + is no longer available in Qt 4. If you link against Qt3Support, + you can use Q3IntDict<QWidget> instead; otherwise, see the + \l{#qdict.section}{section on QDict<T>}. + + \target qwidgetlist.section + \section1 QWidgetList + + In Qt 3, the QWidgetList class was a typedef for + QPtrList<QWidget>. In Qt 4, it is a typedef for QList<QWidget *>. + See the \l{#qptrlist.section}{section on QPtrList<T>}. + + \section1 QWidgetPlugin + + The QWidgetPlugin class is no longer available in Qt 4. To create + custom widget plugins, subclass QDesignerCustomWidgetInterface to + provide information about the custom widget, and build a plugin in + the way described in the \l{designer/customwidgetplugin}{Custom + Widget Plugin} example. + + \section1 QWidgetStack + + The QWidgetStack class is no longer part of the Qt public API. It + has been renamed Q3WidgetStack and moved to Qt3Support. In Qt 4 + applications, you can use QStackedWidget instead to obtain the + same results. + + \section1 QWizard + + The \c QWizard class was reintroduced in Qt 4.3. See the + \l{Trivial Wizard Example}, \l{License Wizard Example} and + \l{Class Wizard Example} for more details. + + \section1 QWorkspace + + The \c QWorkspace in Qt 4 class requires explicit adding of MDI + windows with QWorkspace::addWindow(). +*/ + +/*! + \page porting4-virtual-functions.html + \title Porting to Qt 4 - Virtual Functions + \contentspage {Porting Guides}{Contents} + \previouspage Porting to Qt 4 + \nextpage Porting to Qt 4 - Drag and Drop + \ingroup porting + \brief An overview of changes to virtual functions in Qt 4. + + \section1 Virtual Functions + + Virtual functions that changed their signature in Qt 4: + + \table + \header \o Qt 3 function signature \o Qt 4 function signature + \input porting/porting4-modifiedvirtual.qdocinc + \endtable + + Virtual functions that are not virtual in Qt 4: + + \table + \header \o Qt 3 function \o Comment + \input porting/porting4-removedvirtual.qdocinc + \endtable +*/ diff --git a/doc/src/porting/qt3to4.qdoc b/doc/src/porting/qt3to4.qdoc new file mode 100644 index 0000000..d788f67 --- /dev/null +++ b/doc/src/porting/qt3to4.qdoc @@ -0,0 +1,179 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt3to4.html + \title qt3to4 - The Qt 3 to 4 Porting Tool + + \ingroup porting + \keyword qt3to4 + + The \c qt3to4 tool provides help when moving a project from Qt 3 + to Qt 4. It is designed to automate the most tedious part of the + porting effort. + + See \l{Porting to Qt 4} and \l{Porting UI Files to Qt 4} for + more information about porting Qt 3 applications to Qt 4. + + \section1 Usage + + \c qt3to4 can be run either on individual C++ source or header + files, or on an entire project specified by a \c qmake \c .pro + file: + + \snippet doc/src/snippets/code/doc_src_qt3to4.qdoc 0 + + In project mode, \c qt3to4 reads the \c .pro file and converts + all files specified in it. The tool modifies the files in place. + You might want to make a copy of your project before you run the + tool. + + \section1 Porting Rules + + The Qt porting tool loads its porting rules from an XML file + called \c q3porting.xml located in Qt's \c tools/porting/src directory. + By editing this file, you can add your own rules or remove some + rules. + + The standard \c q3porting.xml file specifies the following + conversions: + + \list + \o Rename classes that are now part of the Qt 3 support + library (e.g., replace \c QFileDialog with \c{Q3FileDialog}). + \o Prefix or rename enum values that have been moved or + renamed (e.g., replace \c QButton::On with \c{QCheckBox::On}) or + members of the Qt namespace (e.g., replace \c QWidget::red with + \c{Qt::red}). + \o Add \c #include directives that might be needed in Qt 4. + \endlist + + \section2 Location of the qt3porting.xml File + + You can now specify the location of the \c qt3porting.xml file with the + \c{-f} command line option. This is useful if you want to use a modified + file with your own rules. + + If you you don't want to maintain a modified \c qt3porting.xml it is + possible to create a "patch" file that includes the original file and adds + or disables rules. The syntax for this file looks like this: + + \snippet doc/src/snippets/code/doc_src_qt3to4.qdoc 1 + + \section1 Logging + + The porting tool logs all changes to a file called \c + portinglog.txt in the current directory. This file lists all + changes made to the source files. + + \section1 Advanced Usage + + When porting, \c qt3to4 parses the source files and ports the + contents according to the C++ language rules. This C++ parsing + step can be disabled with the \c -disableCppParsing option. + + If C++ parsing is enabled, \c qt3to4 must be able to locate the + headers included from the source files. Necessary headers include + the public Qt headers and any headers that declares names that + may conflict with names in the public Qt headers. The standard + C++ headers and system headers are usually not needed. + + You can tell \c qt3to4 where to look for headers by using the + \c{-I} command-line option. Qt 3.3 header information is built + in, so it is normaly not necessary to specify the location of the + Qt headers. If you are porting from a different version of Qt 3, + you may want to disable the built-in headers with + \c{-disableBuiltInQt3Headers}, and then add the path to the + actual headers with the \c{-I} option. + + When porting a project, \c qt3to4 will read the \c INCLUDEPATH + and \c DEPENDPATH variables from the \c .pro file and add the + paths specified here to the list of include search directories. + + To see which headers that are not found, use the \c{-missingFileWarnings} + option. + + \section1 Limitations + + In some cases, you might get compiler errors because of identifiers + in the global namespace (e.g., \c CTRL). Adding + + \snippet doc/src/snippets/code/doc_src_qt3to4.qdoc 2 + + at the beginning of the source file that contains + the indentifier solves the problem. + + \section1 Legal Notices + + Some source code in \c qt3to4 is licensed under specific highly + permissive licenses from the original authors. Nokia gratefully + acknowledges these contributions to \c qt3to4 and all uses of + \c qt3to4 should also acknowledge these contributions and quote the + following license statements in an appendix to the documentation. + + \list + \o \l{Contributions to the Following qt3to4 Files: treewalker.h, + treedump.cpp, treedump.h, treewalker.cpp} + \endlist +*/ + +/*! + \page qt3to4-treewalker.html + \title Contributions to the Following qt3to4 Files: treewalker.h, treedump.cpp, treedump.h, treewalker.cpp + \ingroup licensing + \brief License information for contributions to the qt3to4 source code. + + \legalese + Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). \BR + Copyright (C) 2005 Roberto Raggi + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, modify, market, reproduce, + grant sublicenses and distribute subject to the following + conditions: The above copyright notice and this permission notice + shall be included in all copies or substantial portions of the + Software. These files are provided AS IS with NO WARRANTY OF ANY + KIND, INCLUDING THE WARRANTY OF DESIGN, MERCHANTIBILITY AND FITNESS + FOR A PARTICULAR PURPOSE. + \endlegalese +*/ diff --git a/doc/src/porting/qt4-accessibility.qdoc b/doc/src/porting/qt4-accessibility.qdoc new file mode 100644 index 0000000..1b985c1 --- /dev/null +++ b/doc/src/porting/qt4-accessibility.qdoc @@ -0,0 +1,162 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt4-accessibility.html + \title Cross-Platform Accessibility Support in Qt 4 + + \contentspage {What's New in Qt 4}{Home} + \previouspage The New Qt Designer + \nextpage The Qt 4 Database GUI Layer + + Qt 4 allows developers to write cross-platform applications that + are usable by visually impaired users as well as by users with + other disabilities. Qt accessibility will make applications + accessible to more users and opens the governmental market, where + accessibility is often a requirement. + + \section1 General Overview + + The accessibility classes have been extended in + various ways since Qt 3. We added new functions and new enum + values, and revised the API to make it more consistent with the + rest of Qt. We also added two properties to QWidget, + \l{QWidget::accessibleName}{accessibleName} and + \l{QWidget::accessibleDescription}{accessibleDescription}, that + can be set in \e{Qt Designer} to provide basic help texts without + having to write any code. + + Qt's accessibility architecture is as follows. Qt offers one + generic interface, QAccessibleInterface, that can be used to + wrap all widgets and objects (e.g., QPushButton). This single + interface provides all the metadata necessary for the assistive + technologies. Qt provides implementations of this interface for + its built-in widgets as plugins. + + A more detailed overview of the accessibility support in Qt can + be found on the \l Accessibility page. + + \section1 Enabling Accessibility Support + + By default, Qt applications are run with accessibility support + enabled on Windows and Mac OS X. On Unix/X11 platforms, applications + must be launched in an environment with the \c QT_ACCESSIBILITY + variable set to 1. For example, this is set in the following way with + the bash shell: + + \snippet doc/src/snippets/code/doc_src_qt4-accessibility.qdoc environment + + Accessibility features are built into Qt by default when the libraries + are configured and built. + + \section1 Creating New Accessible Interfaces + + When you develop custom widgets, you can create custom subclasses + of QAccessibleInterface and distribute them as plugins (using + QAccessiblePlugin) or compile them into the application. + Likewise, Qt's predefined accessibility support can be built as + plugin (the default) or directly into the Qt library. The main + advantage of using plugins is that the accessibility classes are + only loaded into memory if they are actually used; they don't + slow down the common case where no assistive technology is being + used. + + In addition to QAccessibleInterface, Qt includes two convenience + classes, QAccessibleObject and QAccessibleWidget, that + provide the lowest common denominator of metadata (e.g., widget + geometry, window title, basic help text). You can use them as + base classes when wrapping your custom QObject or QWidget + subclasses. + + Another new feature in Qt 4 is that Qt can now support other + backends in addition to the predefined ones. This is done by + subclassing QAccessibleBridge. + + \omit + \section1 Software Layering + + Qt Application + | links to + Qt Accessibility Module + | Plugin (in-process) + Qt ATK Bridge + | links to + ATK + | Plugin (in-process) + at-spi + | CORBA + assistive technologies + + Windows: + + Qt Application + | links to + Qt Accessibility Module + | COM (?) + MSAA + | ? + assistive technologies + + Mac: + + ? + \endomit + + \section1 Example Code + + The first example illustrates how to provide accessibility + information for a custom widget. We can use QAccessibleWidget as + a base class and reimplement various functions: + + \snippet doc/src/snippets/code/doc_src_qt4-accessibility.qdoc 0 + + Here's how we would implement the + \l{QAccessibleInterface::doAction()}{doAction()} function to call + a function named click() on the wrapped MyWidget object when the + user invokes the object's default action or "presses" it. + + \snippet doc/src/snippets/code/doc_src_qt4-accessibility.qdoc 1 + + To export the widget interface as a plugin, we must subclass + QAccessibleFactory: + + \snippet doc/src/snippets/code/doc_src_qt4-accessibility.qdoc 2 +*/ diff --git a/doc/src/porting/qt4-arthur.qdoc b/doc/src/porting/qt4-arthur.qdoc new file mode 100644 index 0000000..b253d06 --- /dev/null +++ b/doc/src/porting/qt4-arthur.qdoc @@ -0,0 +1,336 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt4-arthur.html + \title The Arthur Paint System + + \contentspage {What's New in Qt 4}{Home} + \previouspage The Interview Framework + \nextpage The Scribe Classes + + This document describes Qt 4's painting system, providing a + comparison between the approaches used by Qt when rendering + graphics in Qt 3 and Qt 4. + + \tableofcontents + + \section1 Architecture + + The Qt 4 Paint System is primarily based on the classes + QPainter, QPaintDevice, and QPaintEngine. QPainter is the + class used to perform drawing operations, such as drawLine() + and drawRect(). QPaintDevice represents a device that can be + painted on using a QPainter; both QWidget and QPixmap are + QPaintDevices. QPaintEngine provides the interface that the + painter uses to draw onto different types of devices. + + \section2 A Look Back at Qt 3 + + In Qt 3, QPainter could be used to draw on widgets and pixmaps. + (It could also be used to draw to printers on Windows and Mac OS + X.) When other paint devices needed to be supported, such as + QPrinter on X11, this was done by deriving from QPaintDevice and + reimplementing the virtual function QPaintDevice::cmd(). A + reimplemented paint device was treated as an external device. + + QPainter was capable of recognizing external devices and could + serialize each paint operation to the reimplemented cmd() + function. This allowed reimplementation of arbitrary devices, but + the approach has some disadvantages which we have addressed in + Qt 4. One of these is that an external device could not reuse any + functionality implemented in QPainter since QPainter was tied to + widget/pixmap painting on that platform. Supporting multiple + device backends, such as OpenGL, was therefore inconvenient and + not very efficient. + + This has led us to devise a more convenient and intuitive API for + Qt 4. + + \section2 How Painting is Done in Qt 4 + + In Qt 4 we have introduced the QPaintEngine abstract class. + Implementations of this class provide the concrete functionality + needed to draw to specific device types. The QPaintEngine class + is only used internally by QPainter and QPaintDevice, and it is + hidden from application programmers unless they reimplement their own + device types for their own QPaintEngine subclasses. Qt currently + provides paint engines for the following platforms and APIs: + + \list + \o A pixel-based engine for the Windows platform that is + also used to draw onto QImages on all platforms + \o OpenGL on all platforms + \o PostScript on Linux, Unix, and Mac OS X + \o QuickDraw and CoreGraphics on Mac OS X + \o X11 and the X Render Extension on Linux and Unix systems + \omit + \o QVFb, VNC, and LinuxFb for Qt for Embedded Linux + \endomit + \endlist + + To implement support for a new backend, you must derive from + QPaintEngine and reimplement its virtual functions. You also need + to derive from QPaintDevice and reimplement the virtual function + QPaintDevice::paintEngine() to tell QPainter which paint engine + should be used to draw on this particular device. + + The main benefit of this approach is that all painting follows the + same painting pipeline. This means that adding support for new features + and providing default implementations for unsupported ones has + become much simpler. + + \section1 New Features in the Qt 4 Paint System + + \section2 Gradient Brushes + + With Qt 4 it is possible to fill shapes using gradient + brushes. A gradient in this case is used to describe the transition + from one color at a given point to different color at another point. A + gradient can span from one color to another or over a + number of colors by specifying multiple colors at positions in the + gradient area. Qt 4 supports linear, radial, and conical gradients. + + Linear gradients are specified using two control points. + Setting a linear gradient brush is done by creating a QLinearGradient + object and setting it as a brush. + + \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 0 + + The code shown above produces a pattern as show in the following + pixmap: + + \img diagonalGradient.png + + Radial gradients are specified using a center, a radius, and a + focal point. Setting a radial brush is done by creating a QRadialGradient + object and setting it as a brush. + + \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 1 + + The code shown above produces a pattern as shown in the following + pixmap: + + \img radialGradient.png + + Conical gradients are specified using a center and a start + angle. Setting a conical brush is done by creating a + QConicalGradient object and setting it as a brush. + + \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 2 + + The code shown above produces a pattern as shown in the following + pixmap: + + \img conicalGradient.png + + \section2 Alpha-Blended Drawing + + With Qt 4 we support alpha-blended outlining and filling. The + alpha channel of a color is defined through QColor. The alpha + channel specifies the transparency effect, 0 represents a fully + transparent color, while 255 represents a fully opaque color. For + example: + + \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 3 + + The code shown above produces the following output: + + \img alphafill.png + + Alpha-blended drawing is supported on Windows, Mac OS X, and on + X11 systems that have the X Render extension installed. + + + \section2 QPainter and QGLWidget + + It is now possible to open a QPainter on a QGLWidget as if it + were a normal QWidget. One huge benefit from this is that we + utilize the high performance of OpenGL for most drawing + operations, such as transformations and pixmap drawing. + + + \section2 Anti-Aliased Edges + + On platforms where this is supported by the native drawing API, we + provide the option of turning on anti-aliased edges when drawing + graphics primitives. + + \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 4 + + This produces the following output: + + \img antialiased.png + + Anti-aliasing is supported when drawing to a QImage and on all + systems, except on X11 when XRender is not present. + + + \section2 Extensive Use of Native Graphics Operations + + Where this makes sense, Qt uses native graphics + operations. The benefit we gain from this is that these operations + can potentially be performed in hardware, giving significant + speed improvements over many pure-software implementations. + + Among these are native transformations (Mac OS X and OpenGL), + making painting with a world matrix much faster. Some pixmap + operations have also been moved closer to the underlying + hardware implementations. + + + \section2 Painter Paths + + A painter path is an object composed of a number of graphical + building blocks, such as rectangles, ellipses, lines, and curves. + A painter path can be used for filling, outlining, and for clipping. + The main advantage of painter paths over normal drawing operations + is that it is possible to build up non-linear shapes which can be + drawn later in one go. + + Building blocks can be joined in closed subpaths, such as a + rectangle or an ellipse, or they can exist independently as unclosed + subpaths, although an unclosed path will not be filled. + + Below is a code example on how a path can be used. The + painter in this case has a pen width of 3 and a light blue brush. We + first add a rectangle, which becomes a closed subpath. We then add + two bezier curves, and finally draw the entire path. + + \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 5 + + The code above produces the following output: + + \img pathexample.png + + + \section2 Widget Double-Buffering + + In Qt 4, all widgets are double-buffered by default. + + In previous versions of Qt double-buffering was achieved by + painting to an off-screen pixmap then copying the pixmap to the + screen. For example: + + \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 6 + + Since the double-buffering is handled by QWidget internally this + now becomes: + + \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 7 + + Double-buffering is turned on by default, but can be turned off for + individual widgets by setting the widget attribute + Qt::WA_PaintOnScreen. + + \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 8 + + \section2 Pen and Brush Transformation + + In Qt 3, pens and brushes weren't affected by the painter's + transformation matrix. For example, if you drew a rectangle with a + pen width of 1 using a scaled painter, the resulting line width + would still be 1. This made it difficult to implement features + such as zooming and high-resolution printing. + + In Qt 4, pens and brushes honor the painter's transformation + matrix. + + Note that this feature is still in development and not yet + supported on all platforms. + + \section2 Custom Filled Pens + + In Qt 4, it is possible to specify how an outline should be + filled. It can be a solid color or a QBrush, which makes it + possible to specify both texture and gradient fills for both + text and outlines. + + \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 9 + + The code above produces the following output: + + \img gradientText.png + + \section2 QImage as a Paint Device + + A great improvement of Qt 4 over previous versions it that it now + provides a pixel-based raster paint engine which allows users to + open a painter on a QImage. The QImage paint engine supports the + full feature set of QPainter (paths, antialiasing, alphablending, + etc.) and can be used on all platforms. + + One advantage of this is that it is possible to guarantee the + pixel exactness of any drawing operation in a platform-independent + way. + + Painting on an image is as simple as drawing on any other paint device. + + \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 10 + + \section2 SVG Rendering Support + + \l{Scalable Vector Graphics} (SVG) is an language for describing both static + and animated two-dimensional vector graphics. Qt includes support for the + \l{SVG 1.2 Tiny Static Features}{static features} of \l{SVG 1.2 Tiny}, taking + advantage of the improved paint system in Qt 4. SVG drawings can be rendered + onto any QPaintDevice subclass, such as QWidget, QImage, and QGLWidget, to + take advantage of specific advantages of each device. This approach gives + developers the flexibility to experiment, in order to find the best solution + for each application. + + \image svg-image.png + + Since SVG is an XML-based format, the QtXml module is required to read SVG + files. For this reason, classes for SVG handling are provided separately in + the QtSvg module. + + Displaying an SVG drawing in an application is as simple as displaying a + bitmap image. QSvgWidget is a display widget that can be placed in an + appropriate place in a user interface, and new content can be loaded as + required. For example, a predetermined file can be loaded and displayed in + a widget with little effort: + + \snippet doc/src/snippets/qsvgwidget/main.cpp 0 + + For applications with more specialized requirements, the QSvgRenderer class + provides more control over the way SVG drawings are rendered and animated. +*/ diff --git a/doc/src/porting/qt4-designer.qdoc b/doc/src/porting/qt4-designer.qdoc new file mode 100644 index 0000000..0bfe034 --- /dev/null +++ b/doc/src/porting/qt4-designer.qdoc @@ -0,0 +1,298 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt4-designer.html + + \title The New Qt Designer + + \contentspage {What's New in Qt 4}{Home} + \previouspage The Qt 4 Main Window Classes + \nextpage Cross-Platform Accessibility Support in Qt 4 + + \QD has been completely re-written based on our experience with + the previous versions of the product for Qt 3. One of the main new + ideas behind this new version is to release the application as a + collection of interchangeable components that include the property + editor, the widget box, and other useful tools for creating + graphical user interfaces with Qt. These components can either be + used together in the \QD application, or independently integrated + into other systems. As a result, certain features such as the + project editor and code editor have been removed from the version + included with this release. + + The current version of \QD is near feature complete and can be used for + many tasks. However, it is still under continuous development. This + document will explain what is already in place. + + See also the \l{Qt Designer Manual}. + + \tableofcontents + + \section1 The Current State of Qt Designer + + When used as a standalone application, \QD includes a number of + components that work together to provide a flexible GUI design + tool. Widgets and dialog windows can be composed using a + form-based interface that fully supports drag and drop, clipboard + operations, and an undo/redo stack. + + This version of \QD introduces a number of editing modes to make + different types of editing more natural. Each editing mode + displays the form in an appropriate way for that mode, and + provides a specialized user interface for manipulating its + contents. The current editing modes are Widget Editing, Signals + and Slots Editing, Buddy Editing, and Tab Order Editing. + + \section2 User Interface Features + + \table + \row \i \inlineimage designer-main-window.png + \i \bold{Widget Box} + + The Widget Box displays a categorized list of widgets and other + objects that can be placed on a form using drag and drop. + + When \QD is in multi-window mode, the window containing the Widget + Box also holds the main menu and the tool bar. When in workbench + mode, the Widget Box becomes an independent window within the \QD + workspace. + + The contents of the Widget Box are defined in an XML file that + holds a collection of .ui documents for standard Qt widgets. This + file can be extended, making it possible to add custom widgets to + the Widget Box. + \endtable + + \table + \row \i \bold{Property Editor} + + The Property Editor allows designers to edit most properties of + widgets and layout objects. The property names and values are + presented in an editable tree view that shows the properties of + the currently selected object. + + Certain resources, such as icons, can be configured in the + Property Editor. Resources can be taken from any currently + installed resource files, making it easier to design + self-contained components. + + \i \inlineimage designer-property-editor.png + \endtable + + \section2 Editing Features + + \QD allows form designers to work on different aspects of their forms by + switching between specialized editing modes. Tools for editing widget + properties, resources, and actions provide context-sensitive information + about the forms being edited. + + \table + \row \i \inlineimage designer-choosing-form.png + \i \bold{Form Templates} + + Form templates provide ready-to-use forms for various types of widgets, + such as QWidget, QDialog, and QMainWindow. Custom templates based on + these widgets can also be created. + + Templates can contain child widgets and layouts. Designers can + save time by creating templates for the most common user interface + features for repeated use. + \endtable + + \table + \row + \i \bold{Widget Editing Mode} + + The new \QD allows widgets to be dropped into existing layouts on + the form. Previously, it was necessary to break layouts in order + to add new widgets to them. + + \QD now supports more direct manipulation of widgets: + You can clone a widget by dragging it with the \key CTRL key held down, and + it is even possible to drag widgets between forms. + + In-place widget editors provide specialized editing facilities for + the most-used widget properties. + + \i \inlineimage designer-editing-mode.png + \endtable + + \table + \row + \i \inlineimage designer-connection-mode.png + \i \bold{Signals and Slots Editing Mode} + + \QD now employs a "wired" approach when representing and editing + connections between objects on a form. The Signal and Slots + Editing mode displays all the signal and slot connections on your + form as arrows. These arrows can be manipulated visually, and + provide the user with an overview of the form's connection logic. + + Connections can be made between objects on a form and the form itself. + This is particularly useful when designing dialogs. + \endtable + + \table + \row + \i \bold{Buddy Editing Mode} + + Widgets that cannot accept keyboard input are often given buddy + widgets that will take the keyboard focus on their behalf. + + In Buddy Editing mode, \QD provides a similar approach to that + used in the Signals and Slots Editing mode to show the + relationships between widgets and their buddies. + + \i \inlineimage designer-buddy-mode.png + \endtable + + \table + \row + \i \inlineimage designer-tab-order-mode.png + \i \bold{Tab Order Mode} + + In this mode, users can specify the order in which input widgets accept + the keyboard focus. + + The way that the tab order is defined follows the approach taken + in Qt 3's version of \QD; The default tab order is based on the + order in which widgets are constructed. + + \endtable + + \table + \row + \i \bold{The Resource Editor} + + The new \QD fully supports The Qt Resource System, and provide the + Resource Editor to help designers and developers manage the + resources that are needed by their applications. + + Using the Resource Editor, resources can be associated with a + given form, and also modified and extended throught the editor's + file browser style interface. + + The Resource Editor uses files that are processed by various + components of the \l{The Qt Resource System}{Qt Resource System} + to ensure that all required resources are embedded in the + application. + + \i \inlineimage designer-resources-editing.png + \endtable + + \table + \row + \i \inlineimage designer-action-editor.png + \i \bold{The Action Editor} + + With the release of Qt 4.1, \QD introduces the Action Editor + simplifying the management of actions when creating main window + applications. + + When creating a main window, you can add a menu bar and toolbars + using \QD's context menu. Once you have the menu bar or a toolbar + in place, you can create and add actions using the Action Editor. + + \endtable + + \section2 Plugin Support + + \table + \row + \i \inlineimage worldtimeclockplugin-example.png + \i \bold{Custom Widgets} + + Plugins can be used to add new custom widgets, special editors, and + support for widgets from the Qt 3 support library. + + Support for custom widget plugins allows user interface designers to + use application-specific widgets in their designs as early as possible + in the development process. + + \QD handles custom widgets in the same way as standard Qt widgets, + and allows custom signals and slots to be connected to other objects + from within Signals and Slots Editing mode. + \endtable + + \table + \row + \i \bold{The QtDesigner Module} + + The new modular \QD is designed to be integrated into other environments + and extended with custom components. + + The QtDesigner Module is a library that developers can use to + write extensions and plugins for \QD, and enables \QD components + to be embedded into Integrated Development Environments + (IDEs). + + With the release of Qt 4.1 the QtDesigner Module is fully + documented. The release also provides several new examples using + the QtDesigner API to create task menu extensions and custom + multi-page widgets (i.e. container extensions). + + \i \inlineimage designer-manual-taskmenuextension.png + \endtable + + \section1 Run-Time Support for Forms + + With the Qt 4.1 release, the new QtUiTools module is introduced to + provide classes handling forms created with \QD. + + Currently the module only contains the QUiLoader class. + + QUiLoader can be used by standalone applications to + dynamically create form-based user interfaces at run-time. This + library can be statically linked with applications and + redistributed under the same terms as Qt. + + \table + \row + \i \inlineimage calculatorbuilder-example.png + \i \bold{Dynamic Form Creation} + + The QtUiTools library lets developers dynamically construct user interfaces at + run-time using the same techniques as \QD. Since forms can contain custom + widget plugins, the loading mechanism can be customized to search for + third party or application-specific plugins. + \endtable +*/ diff --git a/doc/src/porting/qt4-interview.qdoc b/doc/src/porting/qt4-interview.qdoc new file mode 100644 index 0000000..158de87 --- /dev/null +++ b/doc/src/porting/qt4-interview.qdoc @@ -0,0 +1,293 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt4-interview.html + \title The Interview Framework + + \contentspage {What's New in Qt 4}{Home} + \previouspage The Tulip Container Classes + \nextpage The Arthur Paint System + + The Interview classes provide a model/view framework for Qt + applications based on the well known Model-View-Controller design + pattern. In this document, we will describe Qt's model/view + architecture, provide some examples, and show the improvements + offered over Qt 3's item view classes. + + \tableofcontents + + \section1 Overview of The Model/View Architecture + + The model/view architecture is a variation of the Model-View-Controller + (MVC) design pattern, originating from Smalltalk, that is often used when + building user interfaces. + + In the model/view architecture, the view and the controller objects are + combined. This still separates the way that data is stored from the way + that it is presented to the user, but provides a simpler framework based + on the same principles. This separation makes it possible to display the + same data in several different views, and to implement new types of views, + without changing the underlying data structures. + + User input is handled by \e delegates. The advantage of this approach is + that it allows rendering and editing of individual items of data to be + customized to suit each data type in use. + + \table + \row \i \inlineimage modelview-overview.png + \i \bold{The model/view architecture} + + The model communicates with a source of data, providing an \e interface + for the other components in the architecture. The nature of the + communication depends on the type of data source, and the way the model + is implemented. + + The view obtains \e{model indexes} from the model; these are references + to items of data. By supplying model indexes to the model, the view can + retrieve items of data from the data source. + + In standard views, a \e delegate renders the items of data. When an item + is edited, the delegate communicates with the model directly using + model indexes. + \endtable + + \section1 Model/View Classes + + On a fundamental level, the Interview classes define the interfaces and + common functionality for models, views, and delegates. All implemented + components subclass QAbstractItemModel, QAbstractItemView, or + QAbstractItemDelegate. The use of a common API ensures a level of + interoperability between the components. + + \image standard-views.png + + Interview provides ready-to-use implementations of views for table, + tree, and list widgets: QTableView, QTreeView, and QListView. + These standard views are suitable for displaying the most common + types of data structures used in applications, and can be used with + the ready-made models supplied with Qt: + + \list + \o QStandardItemModel is a minimal convenience model that developers + can use to manage items of data. + \o QDirModel provides directory information for use with QListView and + QTreeView. + \o QStringListModel is a convenience model that can be used to hold + strings for views such as QListView and QComboBox. + \endlist + + Two specialized abstract models are provided that can be subclassed + and extended (see the + \l{model-view-programming.html#related-examples}{Model/View Programming} + examples): + + \list + \o QAbstractTableModel is a useful starting point for providing a custom + model that can be used with QTableView. + \o QAbstractListModel can be subclassed to produce a list-based model + for use with QListView. + \endlist + + Operations on items, such as filtering and sorting, are handled by \e{proxy + models} that allow views to display processed data without having to + copy or modify data obtained from a source model. Interview provides + the QSortFilterProxyModel class to allow items of data from a source model + to be sorted and filtered before they are supplied to views. + + Developers who are familiar with the conventional list, tree, and table + widgets may find QListWidget, QTreeWidget, and QTableWidget useful. + These present a simplified interface to the views that does not require a + knowledge of the underlying model/view architecture. + + For details about how to use the model/view classes, see the + \l{Model/View Programming} document. + + See also the \l{The Qt 4 Database GUI Layer}{Database GUI Layer} document + for information about Qt 4's database models. + + \section1 Example Code + + To illustrate how the Interview classes are used, we present two + examples that show different aspects of the model/view architecture. + + \section2 Sharing a Model Between Views + + In this example, we display the contents of a model using two + different views, and share the user's selection between + them. We will use the QDirModel supplied with Qt because it + requires very little configuration, and provides existing data to + the views. + + The main() function for this example demonstrates all the + principles involved in setting up a model and two views. We also + share the selection between the two views: + + \snippet doc/src/snippets/shareddirmodel/main.cpp 1 + + In the above function, we construct a directory model to display + the contents of a default directory. The two views are constructed + and given the same model to work with. By default, each view will + maintain and display its own selection of items from the model, + so we explicitly create a new selection that is shared between the + tree view and the list view. As a result, changes to the selection + in either of these views will automatically cause the selection in + the other to change. + + \image interview-shareddirmodel.png + + The model/view architecture allows us to replace the QDirModel in + this example with a completely different model, one that will perhaps + obtain data from a remote server, or from a database. + + \section2 Creating a Custom Model + + In this example, we display items of data obtained from a custom list + model using a standard view. The custom model is a subclass of + QAbstractListModel and provides implementations of a core set of + functions. + + The complete declaration of our model is as follows: + + \snippet doc/src/snippets/stringlistmodel/model.h 0 + \snippet doc/src/snippets/stringlistmodel/model.h 1 + \codeline + \snippet doc/src/snippets/stringlistmodel/model.h 5 + + The model takes a list of strings when constructed, and supplies these + to views as required. Since this is only a simple read-only model, we + only need to implement a few functions. + + The underlying data structure used to hold the strings is a QStringList. + Since the model maps each item in the list to a row in the model, the + rowCount() function is quite simple: + + \snippet doc/src/snippets/stringlistmodel/model.cpp 0 + + The data() function returns an item of data for each model index + supplied by a view: + + \snippet doc/src/snippets/stringlistmodel/model.cpp 1 + + The data() function returns a QVariant containing the information + referred to by the model index. Items of data are returned to the view, + but only if a number of checks are satisfied; for example, if the view + specifies an invalid model index, the model indicates this by returning + an invalid QVariant. + + Vertical and horizontal headers are supplied by the headerData() + function. In this model, the value returned for these items is the row + or column number, depending on the header: + + \snippet doc/src/snippets/stringlistmodel/model.cpp 2 + + We only include an excerpt from the main() function for this short + example: + + \snippet doc/src/snippets/stringlistmodel/main.cpp 1 + \dots + \snippet doc/src/snippets/stringlistmodel/main.cpp 3 + + We create a string list to use with the model, and we supply it to the + model when it is constructed. The information in the string list is + made available to the view via the model. + + \image stringlistmodel.png + + This example shows that it can be easy to populate views with data + from a simple model. The standard models and views planned for + Qt 4 will make the process even easier, and the convenience widgets + supplied provide support for the classic item-based approach. + + \section1 What's Changed Since Qt 3? + + The table and item view classes in Qt 3 implemented widgets that + both stored data and presented it to the user. These classes were + designed to be easy-to-use and consistent, but were sometimes + difficult to customize and extend. + + The equivalent classes in Qt 4 are designed to be extensible while + remaining easy-to-use; the introduction of the model/view + architecture ensures that they will be more consistent than their + predecessors. The view classes provided can be summarized in the + following way: + + \list + \i QListView class provides a view widget that looks similar to + Qt 3's QListBox widget, but displays data provided by a model. + It can also be used to display icons in a similar way to Qt 3's + QIconView. + \i The QTableView class is a view widget that displays tabular data + like Qt 3's QTable widget, but uses data provided by a model. + \i The QTreeView class provides a view widget that behaves like + Qt 3's QListView widget, except that it displays data provided + by a model. + \endlist + + Since the model takes responsibility for supplying items of data, + and the view takes care of their presentation to the user, we do + not require item classes to represent individual items. + Delegates handle the painting and editing of data obtained from + the model. + + Qt continues to provide a number of classic item view widgets with + familiar item-based interfaces that are not based on compatibility + classes: + + \list + \i The QListWidget class provides a widget to display a + list of items, as found in Qt 3's QListBox class. + \i The QTreeWidget class implements the equivalent of Qt 3's + QListView class. + \i The QTableWidget class provides comparable functionality to + Qt 3's QTable class. + \endlist + + Each of the convenience classes have a corresponding item class: + QListWidgetItem, QTreeWidgetItem, and QTableWidgetItem are the Qt 4 + equivalents of Qt 3's QListBoxItem, QListViewItem, and QTableItem + respectively. + + The move towards a model/view architecture presents both challenges + and opportunities for developers. Although the approach may appear to + be rather powerful for simple applications, it encourages greater + reuse of components within applications. +*/ diff --git a/doc/src/porting/qt4-mainwindow.qdoc b/doc/src/porting/qt4-mainwindow.qdoc new file mode 100644 index 0000000..7c48b95 --- /dev/null +++ b/doc/src/porting/qt4-mainwindow.qdoc @@ -0,0 +1,250 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt4-mainwindow.html + \title The Qt 4 Main Window Classes + + \contentspage {What's New in Qt 4}{Home} + \previouspage The Scribe Classes + \nextpage The New Qt Designer + + Qt 4 introduces a new set of main window classes that supersede the + Qt 3 main window classes, providing a more efficient implementation + while remaining easy to use. + + \tableofcontents + + \section1 Overview of the Main Window Classes + + The main window-related classes have been redesigned to satisfy a + number of requirements, addressing issues raised by our customers and + internal developers. The aim of this redesign is to provide a more + consistent and efficient framework for main window management. + + \section1 The Main Window Classes + + Qt 4 provides the following classes for managing main windows and + associated user interface components: + + \list + \o QMainWindow remains the central class around which applications + can be built. The interface to this class has been simplified, and + much of the functionality previously included in this class is now + present in the companion QDockWidget and QToolBar classes. + + \o QDockWidget provides a widget that can be used to create + detachable tool palettes or helper windows. Dock widgets keep track + of their own properties, and they can be moved, closed, and floated + as external windows. + + \o QToolBar provides a generic toolbar widget that can hold a + number of different action-related widgets, such as buttons, + drop-down menus, comboboxes, and spin boxes. The emphasis on a + unified action model in Qt 4 means that toolbars cooperate well + with menus and keyboard shortcuts. + \endlist + + \section1 Example Code + + Using QMainWindow is straightforward. Generally, we subclass + QMainWindow and set up menus, toolbars, and dock widgets inside + the QMainWindow constructor. + + To add a menu bar to the main window, we simply create the menus, and + add them to the main window's menu bar. Note that the + QMainWindow::menuBar() function will automatically create the menu bar + the first time it is called. You can also call + QMainWindow::setMenuBar() to use a custom menu bar in the main window. + + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 0 + \dots + \snippet examples/mainwindows/menus/mainwindow.cpp 5 + \dots + + Once actions have been created, we can add them to the main window + components. To begin with, we add them to the pop-up menus: + + \snippet examples/mainwindows/menus/mainwindow.cpp 10 + \dots + \snippet examples/mainwindows/menus/mainwindow.cpp 11 + \dots + + The QToolBar and QMenu classes use Qt's action system to provide a + consistent API. In the above code, some existing actions were added to + the file menu with the QMenu::addAction() function. QToolBar also + provides this function, making it easy to reuse actions in different + parts of the main window. This avoids unnecessary duplication of work. + + We create a toolbar as a child of the main window, and add the desired + actions to it: + + \snippet examples/mainwindows/sdi/mainwindow.cpp 0 + \dots + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 1 + + In this example, the toolbar is restricted to the top and bottom + toolbar areas of the main window, and is initially placed in the + top tool bar area. We can see that the actions specified by \c + newAct and \c openAct will be displayed both on the toolbar and in + the file menu. + + QDockWidget is used in a similar way to QToolBar. We create a + dock widget as a child of the main window, and add widgets as children + of the dock widget: + + \snippet doc/src/snippets/dockwidgets/mainwindow.cpp 0 + + In this example, the dock widget can only be placed in the left and + right dock areas, and it is initially placed in the left dock area. + + The QMainWindow API allows the programmer to customize which dock + widget areas occupy the four corners of the dock widget area. If + required, the default can be changed with the + QMainWindow::setCorner() function: + + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 2 + + The following diagram shows the configuration produced by the above code. + Note that the left and right dock widgets will occupy the top and bottom + corners of the main window in this layout. + + \image mainwindow-docks-example.png + + Once all of the main window components have been set up, the central widget + is created and installed by using code similar to the following: + + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 3 + + The central widget can be any subclass of QWidget. + + \section1 What's Changed since Qt 3? + + The main window classes in Qt 4 adds new functionality, mainly to + the dock widgets and toolbars. We have also made changes to the + design of the framework. + + Although the QMainWindow class in Qt 3 provided support for + toolbars, dock widgets, and other standard user interface + components, its design meant that these items were managed + through a large number of QMainWindow member functions. In Qt 4, + the QMainWindow class delegates many of the management tasks to + QDockWidget and QToolBar (allowing more consistent behavior to be + defined and implemented). + + The dock widget and toolbar classes are now separated into + independent classes. (write some more here) + + (It is intended that these changes allow more consistent behavior + to be defined and implemented (which? example). In + response to feedback from customers, we hope to improve these classes + even further.) + + \section2 New Functionality + + Dock widgets are animated when docking or + detaching from a dock area. The dock areas will also adjust their + size to show where the dock widget will dock when it hovers over + it. This animation can be turned off with \c setAnimated(). + + By default, dock widgets are added to the dock areas in a single + row. By setting nesting enabled with \c setDockNestingEnabled(), + the widgets can be added both vertically and horizontally. + + Two dock widgets can occupy the same space in a dock area. The user + can then choose which widget that is visible with a tab bar that + is located below the widgets. The QMainWindow::tabifyDockWidget() + joins two tab widgets in such a tabbed dock area. (revise the + entire paragraph) + + \section2 Independent QDockWidget And QToolBar Classes + + Toolbar and dock window functionality is provided by two independent + classes: QToolBar and QDockWidget. Toolbars and dock widgets + reside in separate areas, with toolbars outside the dock widget + area. This behavior differs from the Qt 3 behavior, where + QToolBar inherited functionality from QDockWidget, and both types of + component shared the same areas. The result is a more consistent + and predictable experience for users. Toolbars and dock widgets + provide feedback while being dragged into their new positions. + + \image mainwindow-docks.png + + The diagram above shows the layout of a main window that contains both + toolbars and dock widgets. Each corner area can be used by either + of the adjacent dock widget areas, allowing dock widget behavior and + main window layout to be specified precisely. + + Toolbars and dock widgets are child widgets of the main window. They + are no longer reparented into a dock area widget by the main window. + Instead, layouts are used to manage the placement of toolbars and dock + widgets. One consequence is that the old QDockArea class is no + longer required in Qt 4. + + \section2 Code Change Examples + + QMainWindow retains the menuBar() function, but menus are always + constructed using QAction objects. All kinds of menus are + constructed using the general QMenu class. + + Qt 3: + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 4 + Qt 4: + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 5 + + Toolbars follow the same pattern as menus, with the new, more + consistent behavior: + + Qt 3: + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 6 + Qt 4: + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 7 + + The behavior of dock widgets is now configured through the member + functions of QDockWidget. For example, compare the old and new ways + of creating a dock widget in the dock area on the left hand side of the + main window. + + In Qt 3: + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 8 + In Qt 4: + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 9 +*/ diff --git a/doc/src/porting/qt4-network.qdoc b/doc/src/porting/qt4-network.qdoc new file mode 100644 index 0000000..36fd46a --- /dev/null +++ b/doc/src/porting/qt4-network.qdoc @@ -0,0 +1,243 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt4-network.html + \title The Network Module in Qt 4 + + \contentspage {What's New in Qt 4}{Home} + \previouspage The Qt 4 Database GUI Layer + \nextpage The Qt 4 Style API + + The network module in Qt 4 provides some new features, such as + support for internationalized domain names, better IPv6 support, + and better performance. And since Qt 4 allows us to break binary + compatibility with previous releases, we took this opportunity to + improve the class names and API to make them more intuitive to + use. + + \tableofcontents + + \section1 General Overview + + Compared to Qt 3, the network module in Qt 4 brings the following + benefits: + + \list + \o The Qt 4 network classes have more intuitive names and APIs. + For example, QServerSocket has been renamed QTcpServer. + \o The entire network module is \l{reentrant}, making it + possible to use them simultaneously from multiple threads. + \o It is now possible to send and receive UDP datagrams and to + use synchronous (i.e., blocking) sockets without having to + use a low-level API (QSocketDevice in Qt 3). + \o QHostAddress and QHostInfo support internationalized domain names + (RFC 3492). + \o QUrl is more lightweight and fully supports the latest URI + specification draft. + \o UDP broadcasting is now supported. + \endlist + + The Qt 4 network module provides fundamental classes for writing + TCP and UDP applications, as well as higher-level classes that + implement the client side of the HTTP and FTP protocols. + + Here's an overview of the TCP and UDP classes: + + \list + \o QTcpSocket encapsulates a TCP socket. It inherits from + QIODevice, so you can use QTextStream and QDataStream to read + or write data. It is useful for writing both clients and + servers. + \o QTcpServer allows you to listen on a certain port on a + server. It emits a + \l{QTcpServer::newConnection()}{newConnection()} signal every + time a client tries to connect to the server. Once the + connection is established, you can talk to the client using + QTcpSocket. + \o QUdpSocket is an API for sending and receiving UDP datagrams. + \endlist + + QTcpSocket and QUdpSocket inherit most of their functionality + from QAbstractSocket. You can also use QAbstractSocket directly + as a wrapper around a native socket descriptor. + + By default, the socket classes work asynchronously (i.e., they + are non-blocking), emitting signals to notify when data has + arrived or when the peer has closed the connection. In + multithreaded applications and in non-GUI applications, you also + have the opportunity of using blocking (synchronous) functions on + the socket, which often results in a more straightforward style + of programming, with the networking logic concentrated in one or + two functions instead of spread across multiple slots. + + QFtp and QNetworkAccessManager and its associated classes use + QTcpSocket internally to implement the FTP and HTTP protocols. The + classes work asynchronously and can schedule (i.e., queue) + requests. + + The network module contains four helper classes: QHostAddress, + QHostInfo, QUrl, and QUrlInfo. QHostAddress stores an IPv4 or IPv6 + address, QHostInfo resolves host names into addresses, QUrl stores a + URL, and QUrlInfo stores information about a resource pointed to + by a URL, such as the file size and modification date. (Because + QUrl is used by QTextBrowser, it is part of the QtCore library and + not of QtNetwork.) + + See the \l QtNetwork module overview for more information. + + \section1 Example Code + + All the code snippets presented here are quoted from + self-contained, compilable examples located in Qt's \c + examples/network directory. + + \section2 TCP Client + + The first example illustrates how to write a TCP client using + QTcpSocket. The client talks to a fortune server that provides + fortune to the user. Here's how to set up the socket: + + \snippet examples/network/fortuneclient/client.cpp 1 + \codeline + \snippet examples/network/fortuneclient/client.cpp 2 + \snippet examples/network/fortuneclient/client.cpp 4 + + When the user requests a new fortune, the client establishes a + connection to the server: + + \snippet examples/network/fortuneclient/client.cpp 7 + + When the server answers, the following code is executed to read + the data from the socket: + + \snippet examples/network/fortuneclient/client.cpp 9 + + The server's answer starts with a \e size field (which we store + in \c blockSize), followed by \e size bytes of data. If the + client hasn't received all the data yet, it waits for the server + to send more. + + An alternative approach is to use a blocking socket. The code can + then be concentrated in one function: + + \snippet examples/network/blockingfortuneclient/fortunethread.cpp 7 + + \section2 TCP Server + + The following code snippets illustrate how to write a TCP server + using QTcpServer and QTcpSocket. Here's how to set up a TCP + server: + + \snippet examples/network/fortuneserver/server.cpp 0 + \codeline + \snippet examples/network/fortuneserver/server.cpp 3 + + When a client tries to connect to the server, the following code + in the sendFortune() slot is executed: + + \snippet examples/network/fortuneserver/server.cpp 5 + + \section2 UDP Senders and Receivers + + Here's how to broadcast a UDP datagram: + + \snippet examples/network/broadcastsender/sender.cpp 0 + \snippet examples/network/broadcastsender/sender.cpp 1 + + Here's how to receive a UDP datagram: + + \snippet examples/network/broadcastreceiver/receiver.cpp 0 + \codeline + \snippet examples/network/broadcastreceiver/receiver.cpp 1 + + Then in the processPendingDatagrams() slot: + + \snippet examples/network/broadcastreceiver/receiver.cpp 2 + + \section1 Comparison with Qt 3 + + The main difference between Qt 3 and Qt 4 is that the very high + level QNetworkProtocol and QUrlOperator abstraction has been + eliminated. These classes attempted the impossible (unify FTP and + HTTP under one roof), and unsurprisingly failed at that. Qt 4 + still provides QFtp, and it also proveds the QNetworkAccessManager. + + The QSocket class in Qt 3 has been renamed QTcpSocket. The new + class is reentrant and supports blocking. It's also easier to + handle closing than with Qt 3, where you had to connect to both + the QSocket::connectionClosed() and the + QSocket::delayedCloseFinished() signals. + + The QServerSocket class in Qt 3 has been renamed QTcpServer. The + API has changed quite a bit. While in Qt 3 it was necessary to + subclass QServerSocket and reimplement the newConnection() pure + virtual function, QTcpServer now emits a + \l{QTcpServer::newConnection()}{newConnection()} signal that you + can connect to a slot. + + The QHostInfo class has been redesigned to use the operating system's + getaddrinfo() function instead of implementing the DNS protocol. + Internally, QHostInfo simply starts a thread and calls getaddrinfo() + in that thread. This wasn't possible in Qt 3 because + getaddrinfo() is a blocking call and Qt 3 could be configured + without multithreading support. + + The QSocketDevice class in Qt 3 is no longer part of the public + Qt API. If you used QSocketDevice to send or receive UDP + datagrams, use QUdpSocket instead. If you used QSocketDevice + because it supported blocking sockets, use QTcpSocket or + QUdpSocket instead and use the blocking functions + (\l{QAbstractSocket::waitForConnected()}{waitForConnected()}, + \l{QAbstractSocket::waitForConnected()}{waitForReadyRead()}, + etc.). If you used QSocketDevice from a non-GUI thread because it + was the only reentrant networking class in Qt 3, use QTcpSocket, + QTcpServer, or QUdpSocket instead. + + Internally, Qt 4 has a class called QSocketLayer that provides a + cross-platform low-level socket API. It resembles the old + QSocketDevice class. We might make it public in a later release + if users ask for it. + + As an aid to porting to Qt 4, the \l{Qt3Support} + library includes Q3Dns, Q3ServerSocket, Q3Socket, and Q3SocketDevice + classes. +*/ diff --git a/doc/src/porting/qt4-scribe.qdoc b/doc/src/porting/qt4-scribe.qdoc new file mode 100644 index 0000000..64037cf --- /dev/null +++ b/doc/src/porting/qt4-scribe.qdoc @@ -0,0 +1,257 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt4-scribe.html + \title The Scribe Classes + + \contentspage {What's New in Qt 4}{Home} + \previouspage The Arthur Paint System + \nextpage The Qt 4 Main Window Classes + + \keyword Scribe + + Scribe introduces a set of text layout classes to Qt 4. These classes + replace the old rich text engine found in Qt 3, and provide new features + for processing and laying out both plain and rich text. + + \tableofcontents + + For more details about how to use the Scribe classes, see the + \l{richtext.html}{Rich Text Processing} document. + + \section1 Overview of Scribe + + Support for text rendering and layout in Qt 4 has been redesigned + around a system that allows textual content to be represented in a more + flexible way than was possible with Qt 3. Qt 4 also provides a more + convenient programming interface for editing documents. These + improvements are made available through a reimplementation of the + existing text rendering engine, and the introduction of several new + classes. + + The following sections provide a brief overview of the main concepts + behind Scribe. + + \section2 The Document Interface + + Text documents are represented by the QTextDocument class, rather + than by QString objects. Each QTextDocument object contains + information about the document's internal representation, its + structure, and keeps track of modifications to provide undo/redo + facilities. + This approach allows features such as layout management to be + delegated to specialized classes, but also provides a focus for the + framework. + + Documents are either converted from external sources or created from + scratch using Qt. The creation process can done by an editor widget, + such as QTextEdit, or by explicit calls to the Scribe API. + + Text documents can be accessed in two complementary ways: as a linear + buffer for editors to use, and as an object hierarchy that is useful to + layout engines. + In the hierarchical document model, objects generally correspond to + visual elements such as frames, tables, and lists. At a lower level, + these elements describe properties such as the text style and alignment. + The linear representation of the document is used for editing and + manipulation of the document's contents. + + \section2 Document Structure + + Each document contains a root frame into which all other structural + elements are placed. This frame contains other structural elements, + including tables, text blocks, and other frames; these can be nested to + an arbitrary depth. + + Frames provide logical separation between parts of the document, but + also have properties that determine how they will appear when rendered. + A table is a specialized type of frame that consists of a number of + cells, arranged into rows and columns, each of which can contain + further structure and text. Tables provide management and layout + features that allow flexible configurations of cells to be created. + + Text blocks contain text fragments, each of which specifies text and + character format information. Textual properties are defined both at + the character level and at the block level. At the character level, + properties such as font family, text color, and font weight can be + specified. The block level properties control the higher level + appearance and behavior of the text, such as the direction of text + flow, alignment, and background color. + + The document structure is not manipulated directly. Editing is + performed through a cursor-based interface. + + \section2 Editing and Content Creation + + Documents can be edited via the interface provided by the QTextCursor + class; cursors are either created using a constructor or obtained from + an editor widget. The cursor is used to perform editing operations that + correspond exactly to those the user is able to make themselves in an + editor. As a result, information about the document structure is also + available through the cursor, and this allows the structure to be + modified. The use of a cursor-oriented interface for editing makes the + process of writing a custom editor simpler for developers, since the + editing operations can be easily visualized. + + The QTextCursor class also maintains information about any text it + has selected in the document, again following a model that is + conceptually similar to the actions made by the user to select text + in an editor. + + \section2 Document Layout + + The layout of a document is only relevant when it is to be displayed on + a device, or when some information is requested that requires a visual + representation of the document. Until this occurs, the document does + not need to be formatted and prepared for a device. + + Each document's layout is managed by a subclass of the + QAbstractTextDocumentLayout class. This class provides a common + interface for layout and rendering engines. The default rendering + behavior is currently implemented in a private class. This approach + makes it possible to create custom layouts, and provides the + mechanism used when preparing pages for printing or exporting to + Portable Document Format (PDF) files. + + \section1 Example Code + + Here we present two different ways in which the Scribe classes can be + used: for creating and manipulating rich text, and for laying out + plain text. + + + \section2 Manipulating Rich Text + + Rich text is stored in text documents that can either be created by + importing HTML from an external source, or generated using a + QTextCursor. The easiest way to use a rich text document is through + the QTextEdit class, providing an editable view onto a document. The code + below imports HTML into a document, and displays the document using a + text edit widget. + + \snippet doc/src/snippets/scribe-overview/main.cpp 1 + + You can retrieve the document from the text edit using the + document() function. The document can then be edited programmatically + using the QTextCursor class. This class is modeled after a screen + cursor, and editing operations follow the same semantics. The following + code changes the first line of the document to a bold font, leaving all + other font properties untouched. The editor will be automatically + updated to reflect the changes made to the underlying document data. + + \snippet doc/src/snippets/scribe-overview/main.cpp 0 + + Note that the cursor was moved from the start of the first line to the + end, but that it retained an anchor at the start of the line. This + demonstrates the cursor-based selection facilities of the + QTextCursor class. + + Rich text can be generated very quickly using the cursor-based + approach. The following example shows a simple calendar in a + QTextEdit widget with bold headers for the days of the week: + + \snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 0 + \codeline + \snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 1 + \snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 2 + \snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 3 + + The above example demonstrates how simple it is to quickly generate new + rich text documents using a minimum amount of code. Although we have + generated a crude fixed-pitch calendar to avoid quoting too much code, + Scribe provides much more sophisticated layout and formatting features. + + \section2 Plain Text Layout + + Sometimes it is important to be able to format plain text within an + irregularly-shaped region, perhaps when rendering a custom widget, for + example. Scribe provides generic features, such as those provided by + the QTextLayout class, to help developers perform word-wrapping and + layout tasks without the need to create a document first. + + \img plaintext-layout.png + + Formatting and drawing a paragraph of plain text is straightforward. + The example below will lay out a paragraph of text, using a single + font, around the right hand edge of a circle. + + \snippet doc/src/snippets/plaintextlayout/window.cpp 0 + + We create a text layout, specifying the text string we want to display + and the font to use. We ensure that the text we supplied is formatted + correctly by obtaining text lines from the text format, and wrapping + the remaining text using the available space. The lines are positioned + as we move down the page. + + The formatted text can be drawn onto a paint device; in the above code, + the text is drawn directly onto a widget. + + \section2 Printing Features + + The layout system used to display rich text documents also supports + paged layout of documents, and this is used by Qt to generate output for + printing. The printing process is performed by QPrinter and controlled by + the user via options displayed in a QPrintDialog: + + \snippet doc/src/snippets/textdocument-printing/mainwindow.cpp 0 + + Rich text documents can also be exported as PDF files using QPrinter and + the appropriate print engine: + + \snippet demos/textedit/textedit.cpp 0 + + \section1 Comparison with Qt 3 + + The cursor-based editing features, combined with the structural document + model, provide a powerful set of tools for manipulating and displaying + rich text documents. These provide features that were unavailable in + Qt 3's public API. The engine used is a complete rewrite and does not + use the rich text engine supplied with Qt 3. + + The QTextEdit class in Qt 4 has also been completely rewritten with an + API that is quite different from its Qt 3 counterpart. Some compatibility + methods have been added to allow the widget to be used, for basic cases, + in a way that is familiar to users of Qt 3. This class is provided as a + working example of an editor widget that uses the new API, showing that + it is possible to completely implement a document editor based on the + QTextCursor editing interface. +*/ diff --git a/doc/src/porting/qt4-sql.qdoc b/doc/src/porting/qt4-sql.qdoc new file mode 100644 index 0000000..3425e96 --- /dev/null +++ b/doc/src/porting/qt4-sql.qdoc @@ -0,0 +1,175 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt4-sql.html + \title The Qt 4 Database GUI Layer + + \contentspage {What's New in Qt 4}{Home} + \previouspage Cross-Platform Accessibility Support in Qt 4 + \nextpage The Network Module in Qt 4 + + The GUI layer of the SQL module in Qt 4 has been entirely + redesigned to work with \l{qt4-interview.html}{Interview} (Qt's + new model/view classes). It consists of three model classes + (QSqlQueryModel, QSqlTableModel, and QSqlRelationalTableModel) + that can be used with Qt's view classes, notably QTableView. + + \section1 General Overview + + The Qt 4 SQL classes are divided into three layers: + + \list + \o The database drivers + \o The core SQL classes + \o The GUI classes + \endlist + + The database drivers and the core SQL classes are mostly the same + as in Qt 3. The database item models are new with Qt 4; they + inherit from QAbstractItemModel and make it easy to present data + from a database in a view class such as QListView, QTableView, + and QTreeView. + + The philosophy behind the Qt 4 SQL module is that it should be + possible to use database models for rendering and editing data + just like any other item models. By changing the model at + run-time, you can decide whether you want to store your data in + an SQL database or in, say, an XML file. This generic approach + has the additional benefit that you don't need to know anything + about SQL to display and edit data. + + The Qt 4 SQL module includes three item models: + + \list + \o QSqlQueryModel is a read-only model based on an arbitrary + SQL query. + \o QSqlTableModel is a read-write model that works on a single + table. + \o QSqlRelationalTableModel is a QSqlTableModel subclass with + foreign key support. + \endlist + + Combined with Qt's view classes and Qt's default delegate class + (QItemDelegate), the models offer a very powerful mechanism for + accessing databases. For finer control on the rendering of the + fields, you can subclass one of the predefined models, or even + QAbstractItemDelegate or QItemDelegate if you need finer control. + + You can also perform some customizations without subclassing. For + example, you can sort a table using QSqlTableModel::sort(), and + you can initialize new rows by connecting to the + QSqlTableModel::primeInsert() signal. + + One nice feature supported by the read-write models is the + possibility to perform changes to the item model without + affecting the database until QSqlTableModel::submitAll() is + called. Changes can be dropped using QSqlTableModel::revertAll(). + + The new classes perform advantageously compared to the SQL + module's GUI layer in Qt 3. Speed and memory improvements in the + tool classes (especially QVariant, QString, and QMap) and in the + SQL drivers contribute to making Qt 4 database applications more + snappy. + + See the \l QtSql module overview for a more complete introduction + to Qt's SQL classes. + + \section1 Example Code + + The simplest way to present data from a database is to simply + combine a QSqlQueryModel with a QTableView: + + \snippet doc/src/snippets/code/doc_src_qt4-sql.qdoc 0 + + To present the contents of a single table, we can use + QSqlTableModel instead: + + \snippet doc/src/snippets/code/doc_src_qt4-sql.qdoc 1 + + In practice, it's common that we need to customize the rendering + of a field in the database. In that case, we can create our own + model based on QSqlQueryModel. The next code snippet shows a + custom model that prepends '#' to the value in field 0 and + converts the value in field 2 to uppercase: + + \snippet examples/sql/querymodel/customsqlmodel.h 0 + \codeline + \snippet examples/sql/querymodel/customsqlmodel.cpp 0 + + It is also possible to subclass QSqlQueryModel to add support for + editing. This is done by reimplementing + QAbstractItemModel::flags() to specify which database fields are + editable and QAbstractItemModel::setData() to modify the + database. Here's an example of a setData() reimplementation that + changes the first or last name of a person: + + \snippet examples/sql/querymodel/editablesqlmodel.cpp 1 + + It relies on helper functions called \c setFirstName() and + \c setLastName(), which execute an \c{update}. Here's + \c setFirstName(): + + \snippet examples/sql/querymodel/editablesqlmodel.cpp 2 + + See Qt's \c examples/sql directory for more examples. + + \section1 Comparison with Qt 3 + + The core SQL database classes haven't changed so much since Qt 3. + Here's a list of the main changes: + + \list + \o QSqlDatabase is now value-based instead of pointer-based. + \o QSqlFieldInfo and QSqlRecordInfo has been merged into + QSqlField and QSqlRecord. + \o The SQL query generation has been moved into the drivers. This + makes it possible to use non-standard SQL extensions. It also + opens the door to non-SQL databases. + \endlist + + The GUI-related database classes have been entirely redesigned. + The QSqlCursor abstraction has been replaced with QSqlQueryModel + and QSqlTableModel; QSqlEditorFactory is replaced by + QAbstractItemDelegate; QDataTable is replaced by QTableView. The + old classes are part of the \l{Qt3Support} library to aid + porting to Qt 4. +*/ diff --git a/doc/src/porting/qt4-styles.qdoc b/doc/src/porting/qt4-styles.qdoc new file mode 100644 index 0000000..4134962 --- /dev/null +++ b/doc/src/porting/qt4-styles.qdoc @@ -0,0 +1,157 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt4-styles.html + \title The Qt 4 Style API + + \contentspage {What's New in Qt 4}{Home} + \previouspage The Network Module in Qt 4 + \nextpage Thread Support in Qt 4 + + Qt's style API is responsible for performing the widget drawing + for built-in widgets. The Qt 4 style API has been revised to make + it possible for a style to draw widgets without calling any + functions on the widget. + + Because Qt 4 is split across multiple libraries, Qt needed this + update to be able to draw widgets from other libraries than + QtGui. For application developers, this has other benefits, such + as more managable parameter lists and the possibility of drawing + any graphical element without having a widget of a specific + type. + + \section1 General Overview + + The QStyle class is an abstract base class that encapsulates + the look and feel of a GUI. Qt's built-in widgets use it to + perform nearly all of their drawing, ensuring that they look + exactly like the equivalent native widgets. + + Most draw functions now take four arguments: + + \list + \o an enum value specifying which graphical element to draw + \o a QStyleOption specifying how and where to render that element + \o a QPainter that should be used to draw the element + \o a QWidget on which the drawing is performed (optional) + \endlist + + The style gets all the information it needs to render the + graphical element from QStyleOption. The widget is passed as the + last argument in case the style needs it to perform special + effects (such as animated default buttons on Mac OS X), but it + isn't mandatory. In fact, QStyle can be used to draw on any + paint device, not just widgets, by setting the QPainter properly. + + Thanks to QStyleOption, it is now possible to make QStyle draw + widgets without linking in any code for the widget. This is how + Qt's built-in styles can draw Qt 3 widgets such as + Q3ListView without necessarily linking against the Qt3Support + library. Another significant benefit of the new approach is that + it's now possible to use \l{QStyle}'s draw functions on other + widgets than the built-in widgets; for example, you can draw a + combobox on any widget, not just on a QComboBox. + + QStyleOption has various subclasses for the various types of + graphical elements that can be drawn, and it's possible to create + custom subclasses. For example, the QStyle::PE_FrameFocusRect + element expects a QStyleOptionFocusRect argument. This is + documented for each enum value. + + When reimplementing QStyle functions that take a + QStyleOption parameter, you often need to cast the + QStyleOption to a subclass (e.g., QStyleOptionFocusRect). For + safety, you can use qstyleoption_cast() to ensure that the + pointer type is correct. If the object isn't of the right type, + qstyleoption_cast() returns 0. For example: + + \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 0 + + For performance reasons, there are few member functions and the + access to the variables is direct. This "low-level" feel makes + the structures use straightforward and emphasizes that these are + simply parameters used by the style functions. In addition, the + caller of a QStyle function usually creates QStyleOption + objects on the stack. This combined with Qt's extensive use of + \l{implicit sharing} for types such as QString, QPalette, and + QColor ensures that no memory allocation needlessly takes place. + (Dynamic memory allocation can be an expensive operation, + especially when drawing very often in a short time.) + + \section1 Example Code + + The following code snippet illustrates how to use QStyle to + draw the focus rectangle from a custom widget's paintEvent(): + + \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 1 + + The next example shows how to derive from an existing style to + customize the look of a graphical element: + + \snippet doc/src/snippets/customstyle/customstyle.h 0 + \codeline + \snippet doc/src/snippets/customstyle/customstyle.cpp 2 + \snippet doc/src/snippets/customstyle/customstyle.cpp 3 + \snippet doc/src/snippets/customstyle/customstyle.cpp 4 + + See also the \l{Styles Example} for a more detailed description of + how custom styles can be created. + + \section1 Comparison with Qt 3 + + The QStyle class has a similar API in Qt 4 as in Qt 3, with + more or less the same functions. What has changed is the + signature of the functions and the role played by QStyleOption. + For example, here's the signature of the QStyle::drawControl() + function in Qt 3: + + \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 2 + + Here's the signature of the same function in Qt 4: + + \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 3 + + In Qt 3, some of the information required to draw a graphical + element was stored in a QStyleOption parameter, while the rest + was deduced by querying the widget. In Qt 4, everything is stored + in the QStyleOption parameter. +*/ diff --git a/doc/src/porting/qt4-threads.qdoc b/doc/src/porting/qt4-threads.qdoc new file mode 100644 index 0000000..1800d6a --- /dev/null +++ b/doc/src/porting/qt4-threads.qdoc @@ -0,0 +1,101 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt4-threads.html + \title Thread Support in Qt 4 + + \contentspage {What's New in Qt 4}{Home} + \previouspage The Qt 4 Style API + + Qt 4 makes it easier than ever to write multithreaded + applications. More classes have been made usable from non-GUI + threads, and the signals and slots mechanism can now be used to + communicate between threads. + + \section1 General Overview + + QThread now inherits QObject. It emits signals to indicate that + the thread started or finished executing, and provides a few + slots as well. + + Each thread can now have its own event loop. The initial thread + starts its event loops using QCoreApplication::exec(); other + threads can start an event loop using QThread::exec(). Like + QCoreApplication, QThread also provides an + \l{QThread::exit()}{exit(int)} function and a + \l{QThread::quit()}{quit()} slot. + + An event loop in a thread makes it possible for the thread to use + certain non-GUI Qt classes that require the presence of an event + loop (such as QTimer, QTcpSocket, and QProcess). It also makes it + possible to connect signals from any threads to slots of a + specific thread. When a signal is emitted, the slot isn't called + immediately; instead, it is invoked when control returns to the + event loop of the thread to which the object belongs. The slot is + executed in the thread where the receiver object lives. See + QObject::connect() for details. + + Qt 4 also introduces a new synchronization class: QReadWriteLock. + It is similar to QMutex, except that it distinguishes between + "read" and "write" access to shared data and allows multiple + readers to access the data simultaneously. Using QReadWriteLock + instead of QMutex when it is possible can make multithreaded + programs more concurrent. + + Since Qt 4, \l{implicitly shared} classes can safely be copied + across threads, like any other value classes. They are fully + reentrant. This is implemented using atomic reference counting + operations, which are implemented in assembly language for the + different platforms supported by Qt. Atomic reference counting is + very fast, much faster than using a mutex. + + See \l{Thread Support in Qt} for more information. + + \section1 Comparison with Qt 3 + + Earlier versions of Qt offered an option to build the library + without thread support. In Qt 4, threads are always enabled. + + Qt 3 had a class called \c QDeepCopy that you could use to take a + deep copy of an implicitly shared object. In Qt 4, the atomic + reference counting makes this class superfluous. +*/ diff --git a/doc/src/porting/qt4-tulip.qdoc b/doc/src/porting/qt4-tulip.qdoc new file mode 100644 index 0000000..9354651 --- /dev/null +++ b/doc/src/porting/qt4-tulip.qdoc @@ -0,0 +1,200 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt4-tulip.html + \title The Tulip Container Classes + + \contentspage {What's New in Qt 4}{Home} + \previouspage What's New in Qt 4 + \nextpage The Interview Framework + + Qt 4 introduces a new set of containers that supersede both the old + QCollection pointer-based containers and the newer QTL value-based + containers. + + \tableofcontents + + \section1 General Overview + + The Tulip containers are similar to Qt 3's QTL containers + (QValueList, QValueVector, QMap), but have the following + advantages: + + \list + \o The containers provide new iterators with a nicer, less + error-prone syntax than STL, inspired by Java's iterators. (The + STL-style iterators are still available as a lightweight, + STL-compatible alternative.) + + \o The containers have been optimized for minimal code expansion. + + \o An empty container performs no memory allocation, and only + requires the same space as a pointer. + + \o Even though they are implicitly shared, they can safely be copied + across different threads without formality. There's no need to use + \c QDeepCopy. + \endlist + + Tulip provides the following sequential containers: QList, + QLinkedList, QVector, QStack, and QQueue. For most + applications, QList is the best type to use. Although it is + implemented as an array-list, it provides very fast prepends and + appends. If you really need a linked-list, use QLinkedList; if you + want your items to occupy consecutive memory locations, use QVector. + QStack and QQueue are convenience classes that provide LIFO and + FIFO semantics. + + Tulip also provides these associative containers: QMap, + QMultiMap, QHash, QMultiHash, and QSet. The "Multi" containers + conveniently support multiple values associated with a single + key. The "Hash" containers provide faster lookup by using a hash + function instead of a binary search on a sorted set. + + The Tulip containers support the \l foreach keyword, a Qt-specific + addition to the C++ language that is implemented using the standard + C++ preprocessor. The syntax is: + + \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 0 + + Example: + + \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 1 + + The iterator variable can also be defined outside the loop. For + example: + + \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 2 + + Just like standard \c for loops, foreach supports braces, \c + break, \c continue, and nested loops. Qt makes a copy of the + container when it enters the loop. If you modify the container as + you are iterating, that won't affect the loop. + + For details about the new containers, see the + \l{Generic Containers} and \l{Generic Algorithms} overview documents. + + In addition to the new containers, considerable work has also gone into + QByteArray and QString. The Qt 3 QCString class has been + merged with QByteArray. The new QByteArray automatically provides + a '\0' terminator after the last character. For example, the byte array + of size 5 containing "abcde" has a null byte at position 5 (one past + the end). This solves all the typical problems that occurred in Qt 3 + with conversions between QByteArray and QCString. + + To avoid crashes, QByteArray::data() never returns a null + pointer. Furthermore, the distinction between null and empty + strings has been watered down so that \c{QByteArray() == + QByteArray("")} and \c{QString() == QString("")}. + + \section1 Examples + + The first group of examples show how to use the new Java-style + iterators. The main difference between the Java-style iterators and the + STL-style iterators is that the Java-style ones point between items (or + before the first item, or after the last item), whereas the STL ones + point at an item (or past the last item). One advantage of the + Java-style iterators is that iterating forward and backward are + symmetric operations. + + Traversing a container using a Java-style iterator: + + \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 3 + + Modifying items using a Java-style iterator: + + \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 4 + + Removing items using a Java-style iterator: + + \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 5 + + Iterating over items with a particular value using STL-style vs. + Java-style iterators: + + \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 6 + + Modifying and removing items using STL-style vs. Java-style + iterators: + + \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 7 + + The next group of examples show the API of the container classes + themselves. The API is similar to the QTL classes of Qt 3, but is nicer + in many respects. + + Iterating over a QList using an index (which is fast even for large + lists, because QList is implemented as an array-list): + + \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 8 + + Retrieving a value from a map, using a default value if the key + doesn't exist: + + \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 9 + + Getting all the values for a particular key in a QMultiMap or QMultiHash: + + \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 10 + + \section1 Comparison with Qt 3 + + Tulip containers are value based. If you want to store a list where + each item is a QWidget *, use QList<QWidget *>. + + The new containers do not support auto-delete. In practice, we + discovered that the only case where auto-delete proved worthwhile was + when the data really should be stored as a value rather than as a + pointer (e.g., QList<int> rather than QList<int *>). If you need + to delete all the items in a container, use qDeleteAll(). + + If you use QValueList in Qt 3, you can replace it with either + QList or QLinkedList in Qt 4. In most cases, QList is the best + choice: It is typically faster, results in less code in your + executable, and requires less memory. However, QLinkedList's + iterators provide stronger guarantees, and only QLinkedList provides + constant-time insertions in the middle, which can make a difference for + lists with thousands of items. + + If you use QValueVector or QMap in Qt 3, the corresponding Qt 4 + classes (QVector, QMap) are very similar to use. +*/ |