diff options
Diffstat (limited to 'doc/src')
54 files changed, 1319 insertions, 479 deletions
diff --git a/doc/src/custom-types.qdoc b/doc/src/custom-types.qdoc index bf5340e..81eecfc 100644 --- a/doc/src/custom-types.qdoc +++ b/doc/src/custom-types.qdoc @@ -56,9 +56,123 @@ Standard types such as QSize, QColor and QString can all be stored in QVariant objects, used as the types of properties in QObject-based classes, and emitted in signal-slot communication. + In this document, we take a custom type and describe how to integrate it into Qt's object model so that it can be stored in the same way as standard Qt types. We then show how to register the custom type to allow it to be used in signals and slots connections. \section1 Creating a Custom Type + + Before we begin, we need to ensure that the custom type we are creating meets all the + requirements imposed by QMetaType. In other words, it must provide: + + \list + \o a public default constructor, + \o a public copy constructor, and + \o a public destructor. + \endlist + + The following \c Message class definition includes these members: + + \snippet examples/tools/customtype/message.h custom type definition + + The class also provides a constructor for normal use and two public member functions + that are used to obtain the private data. + + \section1 Declaring the Type with QMetaType + + The \c Message class only needs a suitable implementation in order to be usable. + However, Qt's type system will not be able to understand how to store, retrieve + and serialize instances of this class without some assistance. For example, we + will be unable to store \c Message values in QVariant. + + The class in Qt responsible for custom types is QMetaType. To make the type known + to this class, we invoke the Q_DECLARE_METATYPE() macro on the class in the header + file where it is defined: + + \snippet examples/tools/customtype/message.h custom type meta-type declaration + + This now makes it possible for \c Message values to be stored in QVariant objects + and retrieved later. See the \l{Custom Type Example} for code that demonstrates + this. + + The Q_DECLARE_METATYPE() macro also makes it possible for these values to be used as + arguments to signals, but \e{only in direct signal-slot connections}. + To make the custom type generally usable with the signals and slots mechanism, we + need to perform some extra work. + + \section1 Creating and Destroying Custom Objects + + Although the declaration in the previous section makes the type available for use + in direct signal-slot connections, it cannot be used for queued signal-slot + connections, such as those that are made between objects in different threads. + This is because the meta-object system does not know how to handle creation and + destruction of objects of the custom type at run-time. + + To enable creation of objects at run-time, call the qRegisterMetaType() template + function to register it with the meta-object system. This also makes the type + available for queued signal-slot communication as long as you call it before you + make the first connection that uses the type. + + The \l{Queued Custom Type Example} declares a \c Block class which is registered + in the \c{main.cpp} file: + + \snippet examples/threads/queuedcustomtype/main.cpp main start + \dots + \snippet examples/threads/queuedcustomtype/main.cpp register meta-type for queued communications + \dots + \snippet examples/threads/queuedcustomtype/main.cpp main finish + + This type is later used in a signal-slot connection in the \c{window.cpp} file: + + \snippet examples/threads/queuedcustomtype/window.cpp Window constructor start + \dots + \snippet examples/threads/queuedcustomtype/window.cpp connecting signal with custom type + \dots + \snippet examples/threads/queuedcustomtype/window.cpp Window constructor finish + + If a type is used in a queued connection without being registered, a warning will be + printed at the console; for example: + + \code + QObject::connect: Cannot queue arguments of type 'Block' + (Make sure 'Block' is registered using qRegisterMetaType().) + \endcode + + \section1 Making the Type Printable + + It is often quite useful to make a custom type printable for debugging purposes, + as in the following code: + + \snippet examples/tools/customtype/main.cpp printing a custom type + + This is achieved by creating a streaming operator for the type, which is often + defined in the header file for that type: + + \snippet examples/tools/customtype/message.h custom type streaming operator + + The implementation for the \c Message type in the \l{Custom Type Example} + goes to some effort to make the printable representation as readable as + possible: + + \snippet examples/tools/customtype/message.cpp custom type streaming operator + + The output sent to the debug stream can, of course, be made as simple or as + complicated as you like. Note that the value returned by this function is + the QDebug object itself, though this is often obtained by calling the + maybeSpace() member function of QDebug that pads out the stream with space + characters to make it more readable. + + \section1 Further Reading + + The Q_DECLARE_METATYPE() macro and qRegisterMetaType() function documentation + contain more detailed information about their uses and limitations. + + The \l{Custom Type Example}{Custom Type}, + \l{Custom Type Sending Example}{Custom Type Sending} + and \l{Queued Custom Type Example}{Queued Custom Type} examples show how to + implement a custom type with the features outlined in this document. + + The \l{Debugging Techniques} document provides an overview of the debugging + mechanisms discussed above. */ diff --git a/doc/src/debug.qdoc b/doc/src/debug.qdoc index cd9d8cb..da5a82f 100644 --- a/doc/src/debug.qdoc +++ b/doc/src/debug.qdoc @@ -200,7 +200,10 @@ between each item. Here is an example for a class that represents a 2D coordinate. - \snippet doc/src/snippets/qdebugsnippet.cpp 0 + \snippet doc/src/snippets/qdebug/qdebugsnippet.cpp 0 + + Integration of custom types with Qt's meta-object system is covered + in more depth in the \l{Creating Custom Qt Types} document. \section1 Debugging Macros diff --git a/doc/src/deployment.qdoc b/doc/src/deployment.qdoc index 496fe81..d9f7c1a 100644 --- a/doc/src/deployment.qdoc +++ b/doc/src/deployment.qdoc @@ -89,7 +89,8 @@ of Qt, you get Qt as a shared library. The disadvantage with the shared library approach is that you - will get more files to deploy. + will get more files to deploy. For more information, see + \l{sharedlibrary.html}{Creating Shared Libraries}. \section1 Deploying Qt's Libraries @@ -110,13 +111,14 @@ \o \l {QtNetwork} \o \l {QtOpenGL} \o \l {QtScript} - \o \l {QtSql} + \o \l {QtScriptTools} \row + \o \l {QtSql} \o \l {QtSvg} \o \l {QtWebKit} \o \l {QtXml} - \o \l {QtXmlPatterns} \row + \o \l {QtXmlPatterns} \o \l {Phonon Module}{Phonon} \o \l {Qt3Support} \endtable @@ -177,11 +179,13 @@ Please see \l{QtWebKit Module#License Information}{the QtWebKit module documentation} for more information. - \row \o Phonon \o Phonon + \row \o \l{Phonon Module}{Phonon} \o Phonon \o Phonon relies on the native multimedia engines on different platforms. Phonon itself is licensed under the GNU LGPL version 2. Please see \l{Phonon Module#License Information}{the Phonon module documentation} - for more information. + for more information on licensing and the + \l{Phonon Overview#Backends}{Phonon Overview} for details of the backends + in use on different platforms. \endtable \section1 Platform-Specific Notes @@ -878,30 +882,44 @@ HTML pages from the World Wide Web, you should include all text codec plugins to support as many HTML encodings possible. - The search path for Qt plugins (as well as a few other paths) is - hard-coded into the QtCore library. By default, the first plugin - search path will be hard-coded to be a \c plugins subdirectory of - the Qt installation: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 25 - - Pre-determined paths like this one have certain disadvantages. - For example, they may not exist on the target machine. For that - reason you need to examine various alternatives to make sure that - the Qt plugins are found: + The search path for Qt plugins is hard-coded into the QtCore library. + By default, the plugins subdirectory of the Qt installation is the first + plugin search path. However, pre-determined paths like the default one + have certain disadvantages. For example, they may not exist on the target + machine. For that reason, you need to examine various alternatives to make + sure that the Qt plugins are found: \list - \o \l{qt-conf.html}{Using \c qt.conf}. This is the recommended - approach since it provides the most flexibility. - + \o \l{qt-conf.html}{Using \c qt.conf}. This approach is the recommended + if you have executables in different places sharing the same plugins. + \o Using QApplication::addLibraryPath() or - QApplication::setLibraryPaths(). + QApplication::setLibraryPaths(). This approach is recommended if you only + have one executable that will use the plugin. \o Using a third party installation utility to change the hard-coded paths in the QtCore library. \endlist + + If you add a custom path using QApplication::addLibraryPath it could + look like this: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 54 + + Then qApp->libraryPaths() would return something like this: + + "C:/customPath/plugins " + "C:/Qt/4.5.0/plugins" + "E:/myApplication/directory/" + + The executable will look for the plugins in these directories and + the same order as the QStringList returned by qApp->libraryPaths(). + The newly added path is prepended to the qApp->libraryPaths() which + means that it will be searched through first. However, if you use + qApp->setLibraryPaths(), you will be able to determend which paths + and in which order they will be searched. The \l{How to Create Qt Plugins} document outlines the issues you need to pay attention to when building and deploying plugins for @@ -1105,7 +1123,7 @@ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 38 For the Qt frameworks, the first line (i.e. \c - {path/to/Qt/lib/QtGui.framework/Versions/4.0/QtGui (compatibility + {path/to/Qt/lib/QtGui.framework/Versions/4/QtGui (compatibility version 4.0.0, current version 4.0.1)}) becomes the framework's identification name which is used by the dynamic linker (\c dyld). @@ -1448,4 +1466,11 @@ \o The accessibility plugin is always deployed. \o Accessibility for Qt3Support is deployed if the application uses the Qt3Support module. \endlist + + macdeployqt supports the following options: + \list + \o -no-plugins: Skip plugin deployment + \o -dmg : Create a .dmg disk image + \o -no-strip : Don't run 'strip' on the binaries + \endlist */ diff --git a/doc/src/designer-manual.qdoc b/doc/src/designer-manual.qdoc index 768f476..e10a5be 100644 --- a/doc/src/designer-manual.qdoc +++ b/doc/src/designer-manual.qdoc @@ -128,6 +128,7 @@ \header \i Widget Filter Box \i Widget Morphing + \i Disambiguation Field \row \i \inlineimage designer-widget-filter.png \i \inlineimage designer-widget-morph.png @@ -1855,7 +1856,7 @@ pixmap property in the property editor. \section2 The Direct Approach - To demonstrate thow to use user interface (\c{.ui}) files straight from + To demonstrate how to use user interface (\c{.ui}) files straight from \QD, we create a simple Calculator Form application. This is based on the original \l{Calculator Form Example}{Calculator Form} example. @@ -2294,7 +2295,7 @@ pixmap property in the property editor. \image worldtimeclockplugin-example.png - The \l QtDesigner module provides you with the ability to create cusom + The \l QtDesigner module provides you with the ability to create custom widgets in \QD. @@ -2442,6 +2443,10 @@ pixmap property in the property editor. \target BuildingandInstallingthePlugin \section1 Building and Installing the Plugin + \section2 A Simple Plugin + + The \l{Custom Widget Plugin Example} demonstrates a simple \QD plugin. + The \c{.pro} file for a plugin must specify the headers and sources for both the custom widget and the plugin interface. Typically, this file only has to specify that the plugin's project is to be built as a library, but @@ -2476,65 +2481,42 @@ pixmap property in the property editor. See QCoreApplication::libraryPaths() for more information about customizing paths for libraries and plugins with Qt applications. -\omit - \section1 Using Qt Script to Aid in Building Forms - - Starting with Qt 4.3, \c .ui files may contain - \l{QtScript}{Qt Script} snippets that are executed by \l uic or QUiLoader - when building forms. + \section2 Splitting up the Plugin - The snippets are executed per widget. The snippet may modify properties - or invoke slots on the widget. + In a real world scenario, you do not want to have dependencies of the + application making use of the custom widgets to the \QD headers and + libraries as introduced by the simple approach explained above. - Special variables are used to access the widget: + There are two ways to resolve this: - \table - \header - \o Name - \o Value - \row \o \c widget - \o The widget being built. - \row \o \c childWidgets - \o An array containing the child widgets. This is useful - for QDesignerContainerExtension subclasses. - \endtable + \list + \i Create a \c{.pri} file that contains the headers sources and sources + of the custom widget: - If scripts are present in an \c {uic}-generated form, the application - must be configured with Qt Script support. + \code + INCLUDEPATH += $$PWD + HEADERS += $$PWD/analogclock.h + SOURCES += $$PWD/analogclock.cpp + \endcode - \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 5 + This file would then be included by the \c{.pro} file of the plugin and + the application: - For security reasons, the execution of scripts is disabled - by default in QUiLoader. You can enable it by - calling the QUiLoader::setScriptingEnabled() method. + \code + include(customwidget.pri) + \endcode - The resulting script snippet is concatenated from snippets occurring in - several places: + Running \c{qmake -Wall} on the \c{.pro} files causes a warning to be + printed if an included \c{.pri} file cannot be found. - \table - \header - \o Source - \o Usage - \row \o The \c codeTemplate() function of QDesignerCustomWidgetInterface - \o Allows snippets to be run on a per-class basis; for example, to set up a - container using the QDesignerContainerExtension. - \row \o The \c script() method of QDesignerScriptExtension - \o Allows snippets to be run on a per-widget basis; for example, - to set up the internal state of a custom widget. - - Such an internal state might be, for example, the contents of - a custom item view container widget, for which an editor - is provided by an QDesignerTaskMenuExtension object. - - \row \o Snippets entered at run-time using the \gui{Change script...} - option of the form's context menu - \o Fast prototyping. To get an idea, - drag a QLineEdit onto the form, enter the script - \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 6 - and preview the form. - \endtable -\endomit + \i Create a standalone shared library containing the custom widgets only + as described in + \l{sharedlibrary.html}{Creating Shared Libraries}. + This library would then be used by the application as well as by the + \QD plugin. Care must be taken to ensure that the plugin can locate + the library at run-time. + \endlist \section1 Related Examples diff --git a/doc/src/diagrams/qtransform-representation.sk b/doc/src/diagrams/qtransform-representation.sk new file mode 100644 index 0000000..17dcbfe --- /dev/null +++ b/doc/src/diagrams/qtransform-representation.sk @@ -0,0 +1,103 @@ +##Sketch 1 2 +document() +layout('A4',0) +layer('Layer 1',1,1,0,0,(0,0,0)) +lp((0,0,1)) +lw(2) +r(65,0,0,-65,190,760) +lp((0,0,1)) +lw(2) +r(65,0,0,-65,190,695) +lp((0,0,1)) +lw(2) +r(65,0,0,-65,190,630) +lp((0,0,1)) +lw(2) +r(65,0,0,-65,320,760) +lp((0,0,1)) +lw(2) +r(65,0,0,-65,320,695) +lp((0,0,1)) +lw(2) +r(65,0,0,-65,320,630) +lp((0,0,1)) +lw(2) +r(65,0,0,-65,255,760) +lp((0,0,1)) +lw(2) +r(65,0,0,-65,255,695) +lp((0,0,1)) +lw(2) +r(65,0,0,-65,255,630) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(24) +txt('m33',(329.16,589.968)) +G() +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(24) +txt('dy',(274.828,577.768)) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(24) +txt('m32',(264.16,602.768)) +G_() +G() +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(24) +txt('m31',(199.16,602.768)) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(24) +txt('dx',(209.828,577.8)) +G_() +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(24) +txt('m11',(199.16,719.968)) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(24) +txt('m12',(264.16,719.968)) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(24) +txt('m13',(329.16,719.968)) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(24) +txt('m21',(199.16,654.968)) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(24) +txt('m22',(264.16,654.968)) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(24) +txt('m23',(329.16,654.968)) +guidelayer('Guide Lines',1,0,0,1,(0,0,1)) +grid((0,0,5,5),1,(0,0,1),'Grid') diff --git a/doc/src/examples.qdoc b/doc/src/examples.qdoc index c1f9ef5..b750aa0 100644 --- a/doc/src/examples.qdoc +++ b/doc/src/examples.qdoc @@ -234,6 +234,7 @@ \o \l{painting/fontsampler}{Font Sampler} \o \l{painting/imagecomposition}{Image Composition}\raisedaster \o \l{painting/painterpaths}{Painter Paths}\raisedaster + \o \l{painting/svggenerator}{SVG Generator}\raisedaster \o \l{painting/svgviewer}{SVG Viewer} \o \l{painting/transformations}{Transformations}\raisedaster \endlist @@ -315,6 +316,7 @@ \section1 Threads \list + \o \l{threads/queuedcustomtype}{Queued Custom Type}\raisedaster \o \l{threads/mandelbrot}{Mandelbrot}\raisedaster \o \l{threads/semaphores}{Semaphores}\raisedaster \o \l{threads/waitconditions}{Wait Conditions}\raisedaster @@ -326,6 +328,8 @@ \o \l{tools/codecs}{Codecs} \o \l{tools/completer}{Completer}\raisedaster \o \l{tools/customcompleter}{Custom Completer}\raisedaster + \o \l{tools/customtype}{Custom Type}\raisedaster + \o \l{tools/customtypesending}{Custom Type Sending}\raisedaster \o \l{tools/echoplugin}{Echo Plugin}\raisedaster \o \l{tools/i18n}{I18N} \o \l{tools/plugandpaint}{Plug & Paint}\raisedaster diff --git a/doc/src/examples/collidingmice-example.qdoc b/doc/src/examples/collidingmice-example.qdoc index 7ea2ca2..657a204 100644 --- a/doc/src/examples/collidingmice-example.qdoc +++ b/doc/src/examples/collidingmice-example.qdoc @@ -66,7 +66,7 @@ \section1 Mouse Class Definition - The \c mouse class inherits both QObject and QGraphicsItem. The + The \c mouse class inherits from QGraphicsItem. The QGraphicsItem class is the base class for all graphical items in the Graphics View framework, and provides a light-weight foundation for writing your own custom items. @@ -78,14 +78,11 @@ {QGraphicsItem::}{boundingRect()}, which returns an estimate of the area painted by the item, and \l {QGraphicsItem::}{paint()}, which implements the actual painting. In addition, we reimplement - the \l {QGraphicsItem::}{shape()} function to return an accurate + the \l {QGraphicsItem::}{shape()} and \l {QGraphicsItem::}{advance()}. + We reimplement \l {QGraphicsItem::}{shape()} to return an accurate shape of our mouse item; the default implementation simply returns - the item's bounding rectangle. - - The rationale for deriving from QObject in addition to - QGraphicsItem is to be able to animate our items by reimplementing - QObject's \l {QObject::}{timerEvent()} function and use - QObject::startTimer() to generate timer events. + the item's bounding rectangle. We reimplement \l {QGraphicsItem::}{advance()} + to handle the animation so it all happens on one update. \section1 Mouse Class Definition @@ -105,19 +102,18 @@ calling the item's \l {QGraphicsItem::rotate()}{rotate()} function we alter the direction in which the mouse will start moving. - In the end we call QObject's \l {QObject::}{startTimer()} - function, emitting a timer event every 1000/33 millisecond. This - enables us to animate our mouse item using our reimplementation of - the \l {QObject::}{timerEvent()} function; whenever a mouse - receives a timer event it will trigger \l - {QObject::}{timerEvent()}: - + When the QGraphicsScene decides to advance the scene a frame it will call + QGraphicsItem::advance() on each of the items. This enables us to animate + our mouse using our reimplementation of the advance() function. + \snippet examples/graphicsview/collidingmice/mouse.cpp 4 \snippet examples/graphicsview/collidingmice/mouse.cpp 5 \snippet examples/graphicsview/collidingmice/mouse.cpp 6 - First we ensure that the mice stays within a circle with a radius - of 150 pixels. + First, we don't bother doing any advance if the step is 0 since we want to our advance in + the actual advance (advance() is called twice, once with step == 0 indicating that items + are about to advance and with step == 1 for the actual advance). We also ensure that the + mice stays within a circle with a radius of 150 pixels. Note the \l {QGraphicsItem::mapFromScene()}{mapFromScene()} function provided by QGraphicsItem. This function maps a position @@ -275,5 +271,12 @@ In the end, we set the application window's title and size before we enter the main event loop using the QApplication::exec() function. -*/ + Finally, we create a QTimer and connect its timeout() signal to the advance() + slot of the scene. Every time the timer fires, the scene will advance one frame. + We then tell the timer to fire every 1000/33 millisecond. This will + give us a frame rate of 30 frames a second, which is fast enough for most animations. + Doing the animation with a single timer connect to advance the scene ensures that all the + mice are moved at one point and, more importantly, only one update is sent to the screen + after all the mice have moved. +*/
\ No newline at end of file diff --git a/doc/src/examples/customtype.qdoc b/doc/src/examples/customtype.qdoc new file mode 100644 index 0000000..ffeccc3 --- /dev/null +++ b/doc/src/examples/customtype.qdoc @@ -0,0 +1,157 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (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 qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/customtype + \title Custom Type Example + + The Custom Type example shows how to integrate a custom type into Qt's + meta-object system. + + Contents: + + \tableofcontents + + \section1 Overview + + Qt provides a range of standard value types that are used to provide + rich and meaningful APIs. These types are integrated with the meta-object + system, enabling them to be stored in QVariant objects, written out in + debugging information and sent between components in signal-slot + communication. + + Custom types can also be integrated with the meta-object system as long as + they are written to conform to some simple guidelines. In this example, we + introduce a simple \c Message class, we describe how we make it work with + QVariant, and we show how it can be extended to generate a printable + representation of itself for use in debugging output. + + \section1 The Message Class Definition + + The \c Message class is a simple value class that contains two pieces + of information (a QString and a QStringList), each of which can be read + using trivial getter functions: + + \snippet examples/tools/customtype/message.h custom type definition + + The default constructor, copy constructor and destructor are + all required, and must be public, if the type is to be integrated into the + meta-object system. Other than this, we are free to implement whatever we + need to make the type do what we want, so we also include a constructor + that lets us set the type's data members. + + To enable the type to be used with QVariant, we declare it using the + Q_DECLARE_METATYPE() macro: + + \snippet examples/tools/customtype/message.h custom type meta-type declaration + + We do not need to write any additional code to accompany this macro. + + To allow us to see a readable description of each \c Message object when it + is sent to the debug output stream, we define a streaming operator: + + \snippet examples/tools/customtype/message.h custom type streaming operator + + This facility is useful if you need to insert tracing statements in your + code for debugging purposes. + + \section1 The Message Class Implementation + + The implementation of the default constructor, copy constructor and destructor + are straightforward for the \c Message class: + + \snippet examples/tools/customtype/message.cpp Message class implementation + + The streaming operator is implemented in the following way: + + \snippet examples/tools/customtype/message.cpp custom type streaming operator + + Here, we want to represent each value depending on how many lines are stored + in the message body. We stream text to the QDebug object passed to the + operator and return the QDebug object obtained from its maybeSpace() member + function; this is described in more detail in the + \l{Creating Custom Qt Types#Making the Type Printable}{Creating Custom Qt Types} + document. + + We include the code for the getter functions for completeness: + + \snippet examples/tools/customtype/message.cpp getter functions + + With the type fully defined, implemented, and integrated with the + meta-object system, we can now use it. + + \section1 Using the Message + + In the example's \c{main()} function, we show how a \c Message object can + be printed to the console by sending it to the debug stream: + + \snippet examples/tools/customtype/main.cpp printing a custom type + + You can use the type with QVariant in exactly the same way as you would + use standard Qt value types. Here's how to store a value using the + QVariant::setValue() function: + + \snippet examples/tools/customtype/main.cpp storing a custom value + + Alternatively, the qVariantFromValue() and qVariantSetValue() functions + can be used if you are using a compiler without support for member template + functions. + + The value can be retrieved using the QVariant::value() member template + function: + + \snippet examples/tools/customtype/main.cpp retrieving a custom value + + Alternatively, the qVariantValue() template function can be used if + you are using a compiler without support for member template functions. + + \section1 Further Reading + + The custom \c Message type can also be used with direct signal-slot + connections; see the \l{Custom Type Sending Example} for a demonstration + of this. + To register a custom type for use with queued signals and slots, such as + those used in cross-thread communication, see the + \l{Queued Custom Type Example}. + + More information on using custom types with Qt can be found in the + \l{Creating Custom Qt Types} document. +*/ diff --git a/doc/src/examples/customtypesending.qdoc b/doc/src/examples/customtypesending.qdoc new file mode 100644 index 0000000..d335c28 --- /dev/null +++ b/doc/src/examples/customtypesending.qdoc @@ -0,0 +1,128 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (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 qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/customtypesending + \title Custom Type Sending Example + + The Custom Type Sending example shows how to use a custom type with signals + and slots. + + \image customtypesending-example.png + + Contents: + + \tableofcontents + + \section1 Overview + + In the \l{Custom Type Example}, we showed how to integrate custom types + with the meta-object system, enabling them to be stored in QVariant + objects, written out in debugging information and used in signal-slot + communication. + + In this example, we demonstrate that the preparations made to the + \c Message class and its declaration with Q_DECLARE_METATYPE() enable it + to be used with direct signal-slot connections. We do this by creating + a \c Window class containing signals and slots whose signatures include + \c Message arguments. + + \section1 The Window Class Definition + + We define a simple \c Window class with a signal and public slot that + allow a \c Message object to be sent via a signal-slot connection: + + \snippet examples/tools/customtypesending/window.h Window class definition + + The window will contain a text editor to show the contents of a message + and a push button that the user can click to send a message. To facilitate + this, we also define the \c sendMessage() slot. We also keep a \c Message + instance in the \c thisMessage private variable which holds the actual + message to be sent. + + \section1 The Window Class Implementation + + The \c Window constructor sets up a user interface containing a text + editor and a push button. + + \snippet examples/tools/customtypesending/window.cpp Window constructor + + The button's \l{QPushButton::}{clicked()} signal is connected to the + window's \c{sendMessage()} slot, which emits the \c{messageSent(Message)} + signal with the \c Message held by the \c thisMessage variable: + + \snippet examples/tools/customtypesending/window.cpp sending a message + + We implement a slot to allow the message to be received, and this also + lets us set the message in the window programatically: + + \snippet examples/tools/customtypesending/window.cpp receiving a message + + In this function, we simply assign the new message to \c thisMessage + and update the text in the editor. + + \section1 Making the Connection + + In the example's \c{main()} function, we perform the connection between + two instances of the \c Window class: + + \snippet examples/tools/customtypesending/main.cpp main function + + We set the message for the first window and connect the + \c{messageSent(Message)} signal from each window to the other's + \c{setMessage(Message)} slot. Since the signals and slots mechanism is only + concerned with the type, we can simplify the signatures of both the + signal and slot when we make the connection. + + When the user clicks on the \gui{Send message} button in either window, + the message shown will be emitted in a signal that the other window will + receive and display. + + \section1 Further Reading + + Although the custom \c Message type can be used with direct signals and + slots, an additional registration step needs to be performed if you want + to use it with queued signal-slot connections. See the + \l{Queued Custom Type Example} for details. + + More information on using custom types with Qt can be found in the + \l{Creating Custom Qt Types} document. +*/ diff --git a/doc/src/examples/extension.qdoc b/doc/src/examples/extension.qdoc index 8a0ca3a..02e0698 100644 --- a/doc/src/examples/extension.qdoc +++ b/doc/src/examples/extension.qdoc @@ -80,9 +80,9 @@ user type a word to search for, we need several \l {QCheckBox}{QCheckBox}es to facilitate the search options, and we need three \l {QPushButton}{QPushButton}s: the \gui Find button to - start a search, the \gui More button to enable an advanced search, - and the \gui Close button to exit the application. Finally, we - need a QWidget representing the application's extension part. + start a search and the \gui More button to enable an advanced search. + Finally, we need a QWidget representing the application's extension + part. \section1 FindDialog Class Implementation @@ -128,8 +128,7 @@ the connection makes sure that the extension widget is shown depending on the state of \gui More button. - We also connect the \gui Close button to the QWidget::close() - slot, and we put the checkboxes associated with the advanced + We also put the check boxes associated with the advanced search options into a layout we install on the extension widget. \snippet examples/dialogs/extension/finddialog.cpp 4 @@ -137,7 +136,7 @@ Before we create the main layout, we create several child layouts for the widgets: First we allign the QLabel ans its buddy, the QLineEdit, using a QHBoxLayout. Then we vertically allign the - QLabel and QLineEdit with the checkboxes associated with the + QLabel and QLineEdit with the check boxes associated with the simple search, using a QVBoxLayout. We also create a QVBoxLayout for the buttons. In the end we lay out the two latter layouts and the extension widget using a QGridLayout. diff --git a/doc/src/examples/queuedcustomtype.qdoc b/doc/src/examples/queuedcustomtype.qdoc new file mode 100644 index 0000000..bbd1427 --- /dev/null +++ b/doc/src/examples/queuedcustomtype.qdoc @@ -0,0 +1,177 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (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 qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example threads/queuedcustomtype + \title Queued Custom Type Example + + The Queued Custom Type example shows how to send custom types between + threads with queued signals and slots. + + \image queuedcustomtype-example.png + + Contents: + + \tableofcontents + + \section1 Overview + + In the \l{Custom Type Sending Example}, we showed how to use a custom type + with signal-slot communication within the same thread. + + In this example, we create a new value class, \c Block, and register it + with the meta-object system to enable us to send instances of it between + threads using queued signals and slots. + + \section1 The Block Class + + The \c Block class is similar to the \c Message class described in the + \l{Custom Type Example}. It provides the default constructor, copy + constructor and destructor in the public section of the class that the + meta-object system requires. It describes a colored rectangle. + + \snippet examples/threads/queuedcustomtype/block.h custom type definition and meta-type declaration + + We will still need to register it with the meta-object system at + run-time by calling the qRegisterMetaType() template function before + we make any signal-slot connections that use this type. + Even though we do not intend to use the type with QVariant in this example, + it is good practice to also declare the new type with Q_DECLARE_METATYPE(). + + The implementation of the \c Block class is trivial, so we avoid quoting + it here. + + \section1 The Window Class + + We define a simple \c Window class with a public slot that accepts a + \c Block object. The rest of the class is concerned with managing the + user interface and handling images. + + \snippet examples/threads/queuedcustomtype/window.h Window class definition + + The \c Window class also contains a worker thread, provided by a + \c RenderThread object. This will emit signals to send \c Block objects + to the window's \c addBlock(Block) slot. + + The parts of the \c Window class that are most relevant are the constructor + and the \c addBlock(Block) slot. + + The constructor creates a thread for rendering images, sets up a user + interface containing a label and two push buttons that are connected to + slots in the same class. + + \snippet examples/threads/queuedcustomtype/window.cpp Window constructor start + \snippet examples/threads/queuedcustomtype/window.cpp set up widgets and connections + \snippet examples/threads/queuedcustomtype/window.cpp connecting signal with custom type + + In the last of these connections, we connect a signal in the + \c RenderThread object to the \c addBlock(Block) slot in the window. + + \dots + \snippet examples/threads/queuedcustomtype/window.cpp Window constructor finish + + The rest of the constructor simply sets up the layout of the window. + + The \c addBlock(Block) slot receives blocks from the rendering thread via + the signal-slot connection set up in the constructor: + + \snippet examples/threads/queuedcustomtype/window.cpp Adding blocks to the display + + We simply paint these onto the label as they arrive. + + \section1 The RenderThread Class + + The \c RenderThread class processes an image, creating \c Block objects + and using the \c sendBlock(Block) signal to send them to other components + in the example. + + \snippet examples/threads/queuedcustomtype/renderthread.h RenderThread class definition + + The constructor and destructor are not quoted here. These take care of + setting up the thread's internal state and cleaning up when it is destroyed. + + Processing is started with the \c processImage() function, which calls the + \c RenderThread class's reimplementation of the QThread::run() function: + + \snippet examples/threads/queuedcustomtype/renderthread.cpp processing the image (start) + + Ignoring the details of the way the image is processed, we see that the + signal containing a block is emitted in the usual way: + + \dots + \snippet examples/threads/queuedcustomtype/renderthread.cpp processing the image (finish) + + Each signal that is emitted will be queued and delivered later to the + window's \c addBlock(Block) slot. + + \section1 Registering the Type + + In the example's \c{main()} function, we perform the registration of the + \c Block class as a custom type with the meta-object system by calling the + qRegisterMetaType() template function: + + \snippet examples/threads/queuedcustomtype/main.cpp main function + + This call is placed here to ensure that the type is registered before any + signal-slot connections are made that use it. + + The rest of the \c{main()} function is concerned with setting a seed for + the pseudo-random number generator, creating and showing the window, and + setting a default image. See the source code for the implementation of the + \c createImage() function. + + \section1 Further Reading + + This example showed how a custom type can be registered with the + meta-object system so that it can be used with signal-slot connections + between threads. For ordinary communication involving direct signals and + slots, it is enough to simply declare the type in the way described in the + \l{Custom Type Sending Example}. + + In practice, both the Q_DECLARE_METATYPE() macro and the qRegisterMetaType() + template function can be used to register custom types, but + qRegisterMetaType() is only required if you need to perform signal-slot + communication or need to create and destroy objects of the custom type + at run-time. + + More information on using custom types with Qt can be found in the + \l{Creating Custom Qt Types} document. +*/ diff --git a/doc/src/examples/qxmlstreambookmarks.qdoc b/doc/src/examples/qxmlstreambookmarks.qdoc index 7059043..fb3a1c1 100644 --- a/doc/src/examples/qxmlstreambookmarks.qdoc +++ b/doc/src/examples/qxmlstreambookmarks.qdoc @@ -103,8 +103,9 @@ The \c read() function accepts a QIODevice and sets it using \l{QXmlStreamReader::setDevice()}{setDevice()}. The actual process - of reading only takes place in event the file is a valid XBEL 1.0 - file. Otherwise, the \l{QXmlStreamReader::raiseError()} + of reading only takes place if the file is a valid XBEL 1.0 file. + Note that the XML input needs to be well-formed to be accepted by + QXmlStreamReader. Otherwise, the \l{QXmlStreamReader::raiseError()} {raiseError()} function is used to display an error message. \snippet examples/xml/streambookmarks/xbelreader.cpp 1 diff --git a/doc/src/examples/svggenerator.qdoc b/doc/src/examples/svggenerator.qdoc new file mode 100644 index 0000000..32bb89a --- /dev/null +++ b/doc/src/examples/svggenerator.qdoc @@ -0,0 +1,136 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (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 qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example painting/svggenerator + \title SVG Generator Example + + The SVG Generator example shows how to add SVG file export to applications. + + \image svggenerator-example.png + + Scalable Vector Graphics (SVG) is an XML-based language for describing + two-dimensional vector graphics. Qt provides classes for rendering and + generating SVG drawings. This example allows the user to create a simple + picture and save it to an SVG file. + + The example consists of two classes: \c Window and \c DisplayWidget. + + The \c Window class contains the application logic and constructs the user + interface from a Qt Designer \c{.ui} file as described in the + \l{Using a Designer .ui File in Your Application#The Multiple Inheritance Approach}{Qt Designer manual}. + It also contains the code to write an SVG file. + + The \c DisplayWidget class performs all the work of painting a picture on + screen. Since we want the SVG to resemble this picture as closely as + possible, we make this code available to the \c Window class so that it can + be used to generate SVG files. + + \section1 The DisplayWidget Class + + The \c DisplayWidget class displays a drawing consisting of a selection of + elements chosen by the user. These are defined using \c Shape and + \c Background enums that are included within the class definition: + + \snippet examples/painting/svggenerator/displaywidget.h DisplayWidget class definition + + Much of this class is used to configure the appearance of the drawing. The + \c paintEvent() and \c paint() functions are most relevant to the purpose + of this example, so we will describe these here and leave the reader to + look at the source code for the example to see how shapes and colors are + handled. + + We reimplement the QWidget::paintEvent() function to display the drawing + on screen: + + \snippet examples/painting/svggenerator/displaywidget.cpp paint event + + Here, we only construct a QPainter object, begin painting on the device + and set a render hint for improved output quality before calling the + \c paint() function to perform the painting itself. When this returns, + we close the painter and return. + + The \c paint() function is designed to be used for different painting + tasks. In this example, we use it to draw on a \c DisplayWidget instance + and on a QSvgGenerator object. We show how the painting is performed to + demonstrate that there is nothing device-specific about the process: + + \snippet examples/painting/svggenerator/displaywidget.cpp paint function + + \section1 The Window Class + + The \c Window class represents the example's window, containing the user + interface, which has been created using Qt Designer: + + \snippet examples/painting/svggenerator/window.h Window class definition + + As with the \c DisplayWidget class, we concentrate on the parts of the code + which are concerned with painting and SVG generation. In the \c Window + class, the \c saveSvg() function is called whenever the \gui{Save As...} + button is clicked; this connection was defined in the \c{window.ui} file + using Qt Designer. + + The start of the \c saveSvg() function performs the task of showing a file + dialog so that the user can specify a SVG file to save the drawing to. + + \snippet examples/painting/svggenerator/window.cpp save SVG + + In the rest of the function, we set up the generator and configure it to + generate output with the appropriate dimensions and write to the + user-specified file. We paint on the QSvgGenerator object in the same way + that we paint on a widget, calling the \c DisplayWidget::paint() function + so that we use exactly the same code that we used to display the drawing. + + The generation process itself begins with the call to the painter's + \l{QPainter::}{begin()} function and ends with call to its + \l{QPainter::}{end()} function. The QSvgGenerator paint device relies on + the explicit use of these functions to ensure that output is written to + the file. + + \section1 Further Reading + + The \l{SVG Viewer Example} shows how to display SVG drawings in an + application, and can be used to show the contents of SVG files created + by this example. + + See the QtSvg module documentation for more information about SVG and Qt's + SVG classes. +*/ diff --git a/doc/src/exportedfunctions.qdoc b/doc/src/exportedfunctions.qdoc index 2d4821f..f67950c 100644 --- a/doc/src/exportedfunctions.qdoc +++ b/doc/src/exportedfunctions.qdoc @@ -101,8 +101,10 @@ press-and-hold operation on the application's dock icon or \key{Ctrl}-clicks on it while the application is running. - The menu will be turned into a Mac menu which will be merged - with Mac OS X built-in commands. + The menu will be turned into a Mac menu and the items added to the default + Dock menu. There is no merging of the Qt menu items with the items that are + in the Dock menu (i.e., it is not recommended to include actions that + duplicate functionality of items already in the Dock menu). \section1 void qt_mac_set_menubar_icons(bool \e{enable}) diff --git a/doc/src/external-resources.qdoc b/doc/src/external-resources.qdoc index 8904ddb..3bfb5af 100644 --- a/doc/src/external-resources.qdoc +++ b/doc/src/external-resources.qdoc @@ -352,3 +352,8 @@ \externalpage http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html \title GNU Lesser General Public License, version 2.1 */ + +/*! + \externalpage http://developers.sun.com/sunstudio/downloads/patches/index.jsp + \title Sun Studio Patches +*/ diff --git a/doc/src/graphicsview.qdoc b/doc/src/graphicsview.qdoc index fc21c53..049b0c3 100644 --- a/doc/src/graphicsview.qdoc +++ b/doc/src/graphicsview.qdoc @@ -77,8 +77,8 @@ \section1 The Graphics View Architecture Graphics View provides an item-based approach to model-view programming, - much like InterView's convenience classes QTableWidget, QTreeWidget and - QListWidget. Several views can observe a single scene, and the scene + much like InterView's convenience classes QTableView, QTreeView and + QListView. Several views can observe a single scene, and the scene contains items of varying geometric shapes. \section2 The Scene diff --git a/doc/src/images/customtypesending-example.png b/doc/src/images/customtypesending-example.png Binary files differnew file mode 100644 index 0000000..fbc3953 --- /dev/null +++ b/doc/src/images/customtypesending-example.png diff --git a/doc/src/images/extension-example.png b/doc/src/images/extension-example.png Binary files differindex dfaacc0..18fab52 100644 --- a/doc/src/images/extension-example.png +++ b/doc/src/images/extension-example.png diff --git a/doc/src/images/extension_more.png b/doc/src/images/extension_more.png Binary files differindex 2b06809..407af27 100644 --- a/doc/src/images/extension_more.png +++ b/doc/src/images/extension_more.png diff --git a/doc/src/images/qtransform-representation.png b/doc/src/images/qtransform-representation.png Binary files differindex 2608872..883d5dc 100644 --- a/doc/src/images/qtransform-representation.png +++ b/doc/src/images/qtransform-representation.png diff --git a/doc/src/images/queuedcustomtype-example.png b/doc/src/images/queuedcustomtype-example.png Binary files differnew file mode 100644 index 0000000..4399b63 --- /dev/null +++ b/doc/src/images/queuedcustomtype-example.png diff --git a/doc/src/images/svggenerator-example.png b/doc/src/images/svggenerator-example.png Binary files differnew file mode 100644 index 0000000..e7a8e53 --- /dev/null +++ b/doc/src/images/svggenerator-example.png diff --git a/doc/src/installation.qdoc b/doc/src/installation.qdoc index 6d02801..925a195 100644 --- a/doc/src/installation.qdoc +++ b/doc/src/installation.qdoc @@ -614,7 +614,7 @@ in the \l{Qt for Windows CE Requirements} document. <td><tt>-xinerama</tt> or auto-detected</td><td>1.1.0</td> </tr><tr id="DefaultColor"> <td> Xi </td><td> libXi </td><td> X11 Input Extensions</td> - <td>auto-detected</td><td>1.3.0</td> + <td><tt>-xinput</tt> or auto-detected</td><td>1.3.0</td> </tr><tr id="DefaultColor"> <td> Xt </td><td> libXt </td><td> Xt Intrinsics</td><td></td><td>0.99</td> </tr><tr id="DefaultColor"> diff --git a/doc/src/model-view-programming.qdoc b/doc/src/model-view-programming.qdoc index 50d6498..bf0c1c8 100644 --- a/doc/src/model-view-programming.qdoc +++ b/doc/src/model-view-programming.qdoc @@ -227,9 +227,14 @@ \section2 Delegates QAbstractItemDelegate is the abstract base class for delegates in the - model/view framework. A default delegate implementation is provided by - the QItemDelegate class, and this is used as the default delegate by - Qt's standard views. + model/view framework. Since Qt 4.4, the default delegate implementation is + provided by QStyledItemDelegate, and this is used as the default delegate + by Qt's standard views. However, QStyledItemDelegate and QItemDelegate are + independent alternatives to painting and providing editors for items in + views. The difference between them is that QStyledItemDelegate uses the + current style to paint its items. We therefore recommend using + QStyledItemDelegate as the base class when implementing custom delegates or + when working with Qt style sheets. Delegates are described in the section on \l{Delegate Classes}. diff --git a/doc/src/phonon-api.qdoc b/doc/src/phonon-api.qdoc index 01f7c8a..3d04c68 100644 --- a/doc/src/phonon-api.qdoc +++ b/doc/src/phonon-api.qdoc @@ -2568,7 +2568,7 @@ details. Phonon also provides EffectWidget, which lets the user modify the - parameters of an effect an the fly, e.g., with comboboxes. + parameters of an effect an the fly; e.g., with combo boxes. \sa {Phonon Module}, EffectWidget */ @@ -2656,7 +2656,7 @@ To find out what \l{Phonon::}{AudioOutputDevice}s are available for AudioOutput, you can call - BackendCapabilities::availableAudioDevices(). A default device is + BackendCapabilities::availableAudioOutputDevices(). A default device is selected by the backend, but it is possible to set the device to be used with setOutputDevice(). The outputDeviceChanged() signal will be emitted if the device changes. diff --git a/doc/src/phonon.qdoc b/doc/src/phonon.qdoc index e86ccf6..9470e61 100644 --- a/doc/src/phonon.qdoc +++ b/doc/src/phonon.qdoc @@ -49,7 +49,7 @@ \section1 Introduction Qt uses the Phonon multimedia framework to provide functionality - for playback of the most common multimedia formats.The media can + for playback of the most common multimedia formats. The media can be read from files or streamed over a network, using a QURL to a file. @@ -566,7 +566,8 @@ framework, but rather use exchangeable backends to do the work. See the \l{Phonon Module} page for general information about the - framework. + framework and the \l{Phonon Overview} for an introductory tour of its + features. */ /*! diff --git a/doc/src/platform-notes.qdoc b/doc/src/platform-notes.qdoc index ad13c1c..c8046c4 100644 --- a/doc/src/platform-notes.qdoc +++ b/doc/src/platform-notes.qdoc @@ -232,9 +232,7 @@ \section1 Windows Vista - Known issues for Qt on Vista will be listed here. - - As of Qt 4.2.0 no Vista-specific issues are known. + At the time Qt %VERSION% was released, there were no known Vista-specific issues. \target Windows NT \section1 Windows XP, Windows 2000 and Windows NT @@ -404,7 +402,7 @@ Any platform-compiler combinations not listed here should be considered unsupported. - \section2 Actively Supported Platforms + \section1 Actively Supported Platforms \table \header \o OS \o Architecture \o Makespec \o Compiler version(s) @@ -435,7 +433,7 @@ \o wince*-msvc2008 \o Visual Studio 2008 \endtable - \section2 Community Supported Platforms + \section1 Community Supported Platforms \table \header \o OS \o Architecture \o Makespec \o Compiler version(s) @@ -460,7 +458,7 @@ \row \o Embedded Linux \o MIPS, PowerPC \o qws/linux-g++ \o GCC 3.4, 4.1, 4.2, 4.3 \endtable - \section2 Unsupported Platforms + \section1 Unsupported Platforms The following platforms were supported in previous releases, either as actively supported or community supported platforms, but are now unsupported. @@ -493,7 +491,6 @@ \row \row \o aCC series 3 \o \o \o \o \bold{X} \o \bold{X} \row \o aCC series 6 \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} - \row \o MIPSpro 7.4.2m \o{5,1} \e{Unsupported - see the Unsupported Platforms table} \row \o xlC 6 \o \o \o \o \bold{X} \o \bold{X} \row \o \l{Known Issues in %VERSION%}{Intel CC 10 (see note)} \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} @@ -666,9 +663,9 @@ \section2 Sun Studio - Qt is tested using Sun Studio 10 (Sun CC 5.5). Go to - \l{http://developers.sun.com/prodtech/cc/downloads/patches/index.html}{Sun's website} - to download the latest patches for your Sun compiler. + Qt is tested using Sun Studio 8 (Sun CC 5.5). Go to + \l{Sun Studio Patches} page on Sun's Web site to download + the latest patches for your Sun compiler. \section2 Sun WorkShop 5.0 diff --git a/doc/src/porting4-removedvirtual.qdocinc b/doc/src/porting4-removedvirtual.qdocinc index 3eedad2..1af4fa6 100644 --- a/doc/src/porting4-removedvirtual.qdocinc +++ b/doc/src/porting4-removedvirtual.qdocinc @@ -22,7 +22,7 @@ \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 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. diff --git a/doc/src/qalgorithms.qdoc b/doc/src/qalgorithms.qdoc index 459fb81..b33c250 100644 --- a/doc/src/qalgorithms.qdoc +++ b/doc/src/qalgorithms.qdoc @@ -490,7 +490,10 @@ of \a value in the variable passed as a reference in argument \a n. \overload - This is the same as qLowerBound(\a{container}.begin(), \a{container}.end(), value); + For read-only iteration over containers, this function is broadly equivalent to + qLowerBound(\a{container}.begin(), \a{container}.end(), value). However, since it + returns a const iterator, you cannot use it to modify the container; for example, + to insert items. */ /*! \fn RandomAccessIterator qUpperBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value) diff --git a/doc/src/qaxcontainer.qdoc b/doc/src/qaxcontainer.qdoc index 2138aaf..48c76fc 100644 --- a/doc/src/qaxcontainer.qdoc +++ b/doc/src/qaxcontainer.qdoc @@ -73,9 +73,6 @@ standard ActiveX controls to provide high-level user interface functionality are provided. - The QAxContainer module is part of the \l{Qt Full Framework Edition} for - Windows. It is \e not part of the \l{Open Source Versions of Qt}. - \sa {ActiveQt Framework} Topics: diff --git a/doc/src/qaxserver.qdoc b/doc/src/qaxserver.qdoc index ff04962..f0c317b 100644 --- a/doc/src/qaxserver.qdoc +++ b/doc/src/qaxserver.qdoc @@ -63,9 +63,6 @@ Some \l{Qt Examples#ActiveQt}{example implementations} of ActiveX controls and COM objects are provided. - The QAxServer module is part of the \l{Qt Full Framework Edition} for - Windows. It is \e not part of the \l{Open Source Versions of Qt}. - \sa {ActiveQt Framework} Topics: diff --git a/doc/src/qdesktopwidget.qdoc b/doc/src/qdesktopwidget.qdoc index 0361aae..5a27fb4 100644 --- a/doc/src/qdesktopwidget.qdoc +++ b/doc/src/qdesktopwidget.qdoc @@ -48,6 +48,9 @@ \ingroup environment \mainclass + QApplication::desktop() function should be used to get an instance + of the QDesktopWidget. + Systems with more than one graphics card and monitor can manage the physical screen space available either as multiple desktops, or as a large virtual desktop, which usually has the size of the bounding @@ -86,12 +89,14 @@ screens. The correct width and height values are obtained using availableGeometry() or screenGeometry() for a particular screen. - \sa QApplication, QX11Info::appRootWindow() + \sa QApplication, QApplication::desktop(), QX11Info::appRootWindow() */ /*! \fn QDesktopWidget::QDesktopWidget() + \internal + Creates the desktop widget. If the system supports a virtual desktop, this widget will have @@ -104,6 +109,8 @@ /*! \fn QDesktopWidget::~QDesktopWidget() + \internal + Destroys the desktop widget and frees any allocated resources. */ diff --git a/doc/src/qmake-manual.qdoc b/doc/src/qmake-manual.qdoc index 30da8c6..39581a2 100644 --- a/doc/src/qmake-manual.qdoc +++ b/doc/src/qmake-manual.qdoc @@ -367,15 +367,20 @@ \row \o debug \o The project is to be built in debug mode. \row \o debug_and_release \o The project is built in \e both debug and release modes. + \row \o debug_and_release_target \o The project is built in \e both debug + and release modes. TARGET is built into \e both the debug and release directories. \row \o build_all \o If \c debug_and_release is specified, the project is built in both debug and release modes by default. + \row \o autogen_precompile_source \o Automatically generates a \c .cpp file that includes + the precompiled header file specified in the .pro file. \row \o ordered \o When using the \c subdirs template, this option specifies that the directories listed should be processed in the order in which they are given. \row \o warn_on \o The compiler should output as many warnings as possible. This is ignored if \c warn_off is specified. \row \o warn_off \o The compiler should output as few warnings as possible. - \endtable + \row \o copy_dir_files \o Enables the install rule to also copy directories, not just files. + \endtable The \c debug_and_release option is special in that it enables \e both debug and release versions of a project to be built. In such a case, the Makefile that @@ -3075,6 +3080,9 @@ called \c{.qmake.cache} in parent directories of the current directory. If it fails to find this file, it will silently ignore this step of processing. + If it finds a \c{.qmake.cache} file then it will process this file first before + it processes the project file. + \target LibDepend \section1 Library Dependencies diff --git a/doc/src/qnamespace.qdoc b/doc/src/qnamespace.qdoc index 6220795..d9f001e 100644 --- a/doc/src/qnamespace.qdoc +++ b/doc/src/qnamespace.qdoc @@ -142,7 +142,7 @@ QAction::iconVisibleInMenu property. Menus that are currently open or menus already created in the native - Mac OS X menubar MAY NOT pick up a change in this attribute. Changes + Mac OS X menubar \e{may not} pick up a change in this attribute. Changes in the QAction::iconVisibleInMenu property will always be picked up. \value AA_NativeWindows Ensures that widgets have native windows. @@ -508,11 +508,11 @@ \value DirectConnection When emitted, the signal is immediately delivered to the slot. \value QueuedConnection When emitted, the signal is queued until the event loop is able to deliver it to the slot. - \value - BlockingQueuedConnection Same as QueuedConnection, except that the current thread blocks + \value BlockingQueuedConnection + Same as QueuedConnection, except that the current thread blocks until the slot has been delivered. This connection type should only be used for receivers in a different thread. Note that misuse - of this type can lead to dead locks in your application. + of this type can lead to deadlocks in your application. \value AutoConnection If the signal is emitted from the thread in which the receiving object lives, the slot is invoked directly, as with diff --git a/doc/src/qprintdialog.qdoc b/doc/src/qprintdialog.qdoc index 6cac1c9..a4cd18b 100644 --- a/doc/src/qprintdialog.qdoc +++ b/doc/src/qprintdialog.qdoc @@ -39,26 +39,34 @@ ** ****************************************************************************/ +#ifdef QT3_SUPPORT /*! - \fn QPrinter *QPrintDialog::printer() const + \fn QPrinter *QPrintDialog::printer() const - Returns a pointer to the printer this dialog configures, or 0 if - this dialog does not operate on any printer. + Returns a pointer to the printer this dialog configures, or 0 if + this dialog does not operate on any printer. + + This function is available for Unix platforms only. */ /*! - \fn void QPrintDialog::setPrinter(QPrinter *printer, bool pickupSettings) + \fn void QPrintDialog::setPrinter(QPrinter *printer, bool pickupSettings) + + Sets this dialog to configure printer \a printer, or no printer if \a printer + is null. If \a pickupSettings is true, the dialog reads most of + its settings from \a printer. If \a pickupSettings is false (the + default) the dialog keeps its old settings. - Sets this dialog to configure printer \a printer, or no printer if \a printer - is null. If \a pickupSettings is true, the dialog reads most of - its settings from \a printer. If \a pickupSettings is false (the - default) the dialog keeps its old settings. + This function is available for Unix platforms only. */ /*! - \fn void QPrintDialog::addButton(QPushButton *button) + \fn void QPrintDialog::addButton(QPushButton *button) + + Adds the \a button to the layout of the print dialog. The added + buttons are arranged from the left to the right below the + last groupbox of the printdialog. - Adds the \a button to the layout of the print dialog. The added - buttons are arranged from the left to the right below the - last groupbox of the printdialog. + This function is available for Unix platforms only. */ +#endif diff --git a/doc/src/qt4-intro.qdoc b/doc/src/qt4-intro.qdoc index cd66c10..5d83ef2 100644 --- a/doc/src/qt4-intro.qdoc +++ b/doc/src/qt4-intro.qdoc @@ -161,9 +161,9 @@ \o Support for OLE verbs and MIME data handling in \l{ActiveQt}. \endlist - For more information about improvements in the current release, see - the \l{http://www.qtsoftware.com/developer/changes/changes-4.1.4/} - {detailed list of changes}. + For more information about improvements in each Qt release, see + the \l{http://www.qtsoftware.com/developer/changes/} + {detailed lists of changes}. \section1 Significant Improvements @@ -447,11 +447,10 @@ \l{http://www.qtsoftware.com/developer/changes/changes-4.5.0}{available online}. A \l{Known Issues in %VERSION%}{list of known issues} for this release is also available. - \omit + Changes between this release and the previous release are provided in the \c{changes-%VERSION%} file (also \l{http://www.qtsoftware.com/developer/changes/changes-%VERSION%}{available online}). - \endomit A list of other Qt 4 features can be found on the \bold{\l{What's New in Qt 4}} page. diff --git a/doc/src/qtcocoa-known-issues.qdoc b/doc/src/qtcocoa-known-issues.qdoc deleted file mode 100644 index eedbd68..0000000 --- a/doc/src/qtcocoa-known-issues.qdoc +++ /dev/null @@ -1,168 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Qt Software Information (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 qt-sales@nokia.com. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qtcocoa-known-issues.html - \title Known Issues with the Qt/Mac Cocoa Port - - This document explains the current list of features in the Qt/Mac Cocoa port - that are currently not working. Most of the issues will be addressed in - upcoming snapshots and beta releases. We hope that all the issues should be - addressed by the time the of the final 4.5.0 release. - - \tableofcontents - - \section1 What Works - - Here are the things that we can say about the current state of the Qt/Mac Cocoa port. - - \list - \i \e{64-bit Support}: - The Qt libraries currently do build and link as 64-bit frameworks and it is - possible to build and run many of the Qt examples as 64-bit. - - \i \e{HIViews are now NSViews}: - Every QWidget is now backed by an NSView pointer instead of an HIViewRef. - QWidget::winId() will return an NSView pointer that can be used in other - Cocoa technologies (e.g., Core Animation). - - \i \e{Some Native Dialogs Work}: - QFileDialog and QColorDialog have been ported to use NSOpen-/NSSavePanel and - NSColorPanel respectively. QPrintDialog and QPageSetupDialog are not in - this release, but are on their way. Currently, none of these dialogs show - up as sheets pending the creation of an asynchronous API. - - \i \e{Painting, Printing, and Styles}: - Since printing and painting used Quartz 2D and styling used HITheme, these - sub-systems work without any changes. - - \i \e {OpenGL}: - OpenGL is fully supported,including pixel buffers and framebuffer objects. - - \i \e{Clipboard}: - Using QClipboard to copy and paste data works as expected. - - \i \e{Mouse, Keyboard, and Wheel events}: - Mouse, keyboard, and wheel events are dispatched to the proper - widget. The Qt/Mac Cocoa port respects Cocoa's idea of a "First - Responder." - - \endlist - - \section1 Current Known Issues - - The following are items that don't currently work, but that we plan to have - resolved before the final release of the Qt/Mac Cocoa port. Please do not - file bugs on these. - - \list - \i \e{Carbon Support}: - The current source tree for the Qt/Mac Cocoa port contains source for - building Qt/Mac with Cocoa. It contains some of the source code that is - used for the Carbon port, but it is currently not set up to build the - Carbon Qt/Mac libraries. Please use a normal release or snapshot if you - want to use Carbon. - - \i \e{Drag and Drop Support}: - Drag and Drop is currently not implemented and needs to be ported to Cocoa, - but using the clipboard does work at this time. - - \i \e {Accessibility}: - Accessibility support is not implemented and needs to be ported to Cocoa. - - \i \e {Text}: - Most text rendering works fine for Latin-1 characters. However, rendering - non-Latin-1 characters has not been tested. - - \i \e {Input Methods}: - Input methods also need to be ported to Cocoa. - - \i \e {Shortcuts}: - Shortcuts that exist outside of the menu bar may not be dispatched. - - \i \e {Tablet Support}: - The tablet support has not been ported from Carbon yet. However, it should - still be possible to use the tablet as a mouse. - - \i \e {Phonon}: - Phonon uses the QuickTime backend that is only available on 32-bit. Using - Phonon in 64-bit requires a QTKit-based backend and has not been done. - - \i \e {Unified Toolbar}: - The QMainWindow::setUnifiedTitleAndToolBarOnMac() method currently does nothing. - - \i \e {Dialogs, Tool Windows, Sheets, and Drawers}: - At the moment, all windows are subclasses of NSWindow. This means that - window types like drawers and sheets do not work and tool windows do not - get the right decorations. Modal dialogs do show up at the correct window - level, but are not yet considered "panels." Many window flags are not - recognized. - - \endlist - - \section1 Things We Don't Expect to Support - - The following items that we do not plan on spending any resources on unless - there is monumental outcry for their inclusion. - - \list - \i \e{Qt3Support}: - At this time we have no plans for making the Qt3Support module work with - the Qt/Mac Cocoa port in 64-bit mode. Following in footsteps of Apple, we - would like to encourage you to consider the time of going Cocoa and 64-bit - as a chance to jettison Qt 3 constructs and classes. - - \i \e{Support for versions of Mac OS X below 10.5}: - We are using methods and classes that are only available in 10.5 and - higher. Most of these functions don't have any equivalent on earlier - versions. We recommend using the Carbon version for earlier versions of Mac - OS X. We anticipate keeping the Carbon port supported at least for the - lifetime of 4.5. - - \i \e{Support for -no-framework or -static}: - Cocoa requires that we load a nib in order to properly access the global - menu bar. This nib has to reside on disk somewhere. The most logical place - for it to reside is inside the QtGui framework. For this reason, building - Qt as standard "dylibs" or statically is no longer supported. - - \endlist - -*/ diff --git a/doc/src/sharedlibrary.qdoc b/doc/src/sharedlibrary.qdoc new file mode 100644 index 0000000..3febb8f --- /dev/null +++ b/doc/src/sharedlibrary.qdoc @@ -0,0 +1,186 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (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 qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the Qt GUI Toolkit. +** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE +** +****************************************************************************/ + +/*! + \group deployment + \page sharedlibrary.html + \ingroup buildsystem + + \title Creating Shared Libraries + The following sections list certain things that should be taken into + account when creating shared libraries. + + \section1 Using Symbols from Shared Libraries + + Symbols - functions, variables or classes - contained in shared libraries + intended to be used by \e{clients}, such as applications or other + libraries, must be marked in a special way. These symbols are called + \e{public symbols} that are \e{exported} or made publicly visible. + + The remaining symbols should not be visible from the outside. On most + platforms, compilers will hide them by default. On some platforms, a + special compiler option is required to hide these symbols. + + When compiling a shared library, it must be marked for \e{export}. To use + the shared library from a client, some platforms may require a special + \e{import} declaration as well. + + Depending on your target platform, Qt provides special macros that contain + the necessary definitions: + \list + \o \c{Q_DECL_EXPORT} must be added to the declarations of symbols used + when compiling a shared library. + \o \c{Q_DECL_IMPORT} must be added to the declarations of symbols used + when compiling a client that uses the shared library. + \endlist + + Now, we need to ensure that the right macro is invoked -- whether we + compile a share library itself, or just the client using the shared + library. + Typically, this can be solved by adding a special header. + + Let us assume we want to create a shared library called \e{mysharedlib}. + A special header for this library, \c{mysharedlib_global.h}, looks like + this: + + \code + #include <QtCore/QtGlobal> + + #if defined(MYSHAREDLIB_LIBRARY) + # define MYSHAREDLIB_EXPORT Q_DECL_EXPORT + #else + # define MYSHAREDLIB_EXPORT Q_DECL_IMPORT + #endif + \endcode + + In the \c{.pro} file of the shared library, we add: + + \code + DEFINES += MYSHAREDLIB_LIBRARY + \endcode + + In each header of the library, we specify the following: + + \code + #include "mysharedlib_global.h" + + MYSHAREDLIB_EXPORT void foo(); + class MYSHAREDLIB_EXPORT MyClass... + \endcode + This ensures that the right macro is seen by both library and clients. We + also use this technique in Qt's sources. + + + \section1 Header File Considerations + + Typically, clients will include only the public header files of shared + libraries. These libraries might be installed in a different location, when + deployed. Therefore, it is important to exclude other internal header files + that were used when building the shared library. + + For example, the library might provide a class that wraps a hardware device + and contains a handle to that device, provided by some 3rd-party library: + + \code + #include <footronics/device.h> + + class MyDevice { + private: + FOOTRONICS_DEVICE_HANDLE handle; + }; + \endcode + + A similar situation arises with forms created by Qt Designer when using + aggregation or multiple inheritance: + + \code + #include "ui_widget.h" + + class MyWidget : public QWidget { + private: + Ui::MyWidget m_ui; + }; + \endcode + + When deploying the library, there should be no dependency to the internal + headers \c{footronics/device.h} or \c{ui_widget.h}. + + This can be avoided by making use of the \e{Pointer to implementation} + idiom described in various C++ programming books. For classes with + \e{value semantics}, consider using QSharedDataPointer. + + + \section1 Binary compatibility + + For clients loading a shared library, to work correctly, the memory + layout of the classes being used must match exactly the memory layout of + the library version that was used to compile the client. In other words, + the library found by the client at runtime must be \e{binary compatible} + with the version used at compile time. + + This is usually not a problem if the client is a self-contained software + package that ships all the libraries it needs. + + However, if the client application relies on a shared library that belongs + to a different installation package or to the operating system, then we + need to think of a versioning scheme for shared libraries and decide at + which level \e{Binary compatibility} is to be maintained. For example, Qt + libraries of the same \e{major version number} are guaranteed to be binary + compatible. + + Maintaining \e{Binary compatibility} places some restrictions on the changes + you can make to the classes. A good explanation can be found at + \l{http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++} + {KDE - Policies/Binary Compatibility Issues With C++}. These issues should + be considered right from the start of library design. + We recommend that the principle of \e{Information hiding} and the + \e{Pointer to implementation} technique be used wherever possible. +*/ diff --git a/doc/src/snippets/alphachannel.cpp b/doc/src/snippets/alphachannel.cpp index 7783271..ad0885a 100644 --- a/doc/src/snippets/alphachannel.cpp +++ b/doc/src/snippets/alphachannel.cpp @@ -47,11 +47,8 @@ #include <qfile.h> #include <qdir.h> #include <qfileinfo.h> - -#if (QT_VERSION) >= 0x040000 #include <QtGui> #include <QtCore> -#endif class MyClass : public QWidget { @@ -95,12 +92,10 @@ protected: //! [0] } - QPixmap channelImage, pixmap; + QPixmap channelImage, pixmap; QSize sizeHint() const { return QSize(500, 500); } }; - - int main(int argc, char **argv) { QApplication app(argc, argv); diff --git a/doc/src/snippets/code/doc_src_deployment.qdoc b/doc/src/snippets/code/doc_src_deployment.qdoc index 844041a..b8bf571 100644 --- a/doc/src/snippets/code/doc_src_deployment.qdoc +++ b/doc/src/snippets/code/doc_src_deployment.qdoc @@ -407,3 +407,8 @@ Versions/A/QuartzCore libphonon_qt7.dylib QMAKE_MAC_SDK=/Developer/SDKs/MacOSX10.4u.sdk CONFIG+=x86 ppc //! [53] + + +//! [54] +qApp->addLibraryPath("C:/customPath/plugins"); +//! [54] diff --git a/doc/src/snippets/code/doc_src_installation.qdoc b/doc/src/snippets/code/doc_src_installation.qdoc index 66bb998..e35dad9 100644 --- a/doc/src/snippets/code/doc_src_installation.qdoc +++ b/doc/src/snippets/code/doc_src_installation.qdoc @@ -44,7 +44,7 @@ PATH - to locate qmake, moc and other Qt tools //! [8] C: -cd /D C:\Qt\4.4.0-rc1 +cd /D C:\Qt\%VERSION% configure //! [8] diff --git a/doc/src/snippets/code/doc_src_qtestlib.qdoc b/doc/src/snippets/code/doc_src_qtestlib.qdoc index a4ef52e..ff52b2f 100644 --- a/doc/src/snippets/code/doc_src_qtestlib.qdoc +++ b/doc/src/snippets/code/doc_src_qtestlib.qdoc @@ -69,7 +69,7 @@ void TestQString::toUpper() //! [10] ********* Start testing of TestQString ********* -Config: Using QTest library 4.1.0, Qt 4.1.0 +Config: Using QTest library %VERSION%, Qt %VERSION% PASS : TestQString::initTestCase() PASS : TestQString::toUpper() PASS : TestQString::cleanupTestCase() @@ -99,4 +99,4 @@ private slots: } } }; -//! [12]
\ No newline at end of file +//! [12] diff --git a/doc/src/snippets/code/src_corelib_global_qglobal.cpp b/doc/src/snippets/code/src_corelib_global_qglobal.cpp index 72663e9..287181a 100644 --- a/doc/src/snippets/code/src_corelib_global_qglobal.cpp +++ b/doc/src/snippets/code/src_corelib_global_qglobal.cpp @@ -456,3 +456,11 @@ class MyClass : public QObject //! [45] QWidget w = QWidget(); //! [45] + +//! [46] + // Instead of comparing with 0.0 + qFuzzyCompare(0.0,1.0e-200); // This will return false + // Compare adding 1 to both values will fix the problem + qFuzzyCompare(1 + 0.0, 1 + 1.0e-200); // This will return true +//! [46] + diff --git a/doc/src/snippets/code/src_corelib_kernel_qmetaobject.cpp b/doc/src/snippets/code/src_corelib_kernel_qmetaobject.cpp index ca18465..c181a40 100644 --- a/doc/src/snippets/code/src_corelib_kernel_qmetaobject.cpp +++ b/doc/src/snippets/code/src_corelib_kernel_qmetaobject.cpp @@ -71,7 +71,7 @@ for(int i = metaObject->methodOffset(); i < metaObject->methodCount(); ++i) //! [methodCount] //! [6] -int methodIndex = pushButton->metaObject()->indexForMethod("animateClick"); +int methodIndex = pushButton->metaObject()->indexOfMethod("animateClick()"); QMetaMethod method = metaObject->method(methodIndex); method.invoke(pushButton, Qt::QueuedConnection); //! [6] @@ -82,7 +82,8 @@ QMetaMethod::invoke: Unable to handle unregistered datatype 'MyType' //! [8] QString retVal; -int methodIndex = obj->metaObject()->indexForMethod("compute"); +QByteArray normalizedSignature = QMetaObject::normalizedSignature("compute(QString, int, double)"); +int methodIndex = obj->metaObject()->indexOfMethod(normalizedSignature); QMetaMethod method = metaObject->method(methodIndex); method.invoke(obj, Qt::DirectConnection, diff --git a/doc/src/snippets/code/src_corelib_kernel_qmetatype.cpp b/doc/src/snippets/code/src_corelib_kernel_qmetatype.cpp index 355a237..783852b 100644 --- a/doc/src/snippets/code/src_corelib_kernel_qmetatype.cpp +++ b/doc/src/snippets/code/src_corelib_kernel_qmetatype.cpp @@ -33,7 +33,7 @@ MyStruct s2 = var.value<MyStruct>(); //! [3] int id = QMetaType::type("MyClass"); -if (id != -1) { +if (id == 0) { void *myClassPtr = QMetaType::construct(id); ... QMetaType::destroy(id, myClassPtr); diff --git a/doc/src/snippets/code/src_gui_util_qdesktopservices.cpp b/doc/src/snippets/code/src_gui_util_qdesktopservices.cpp index a9c630b..5001984 100644 --- a/doc/src/snippets/code/src_gui_util_qdesktopservices.cpp +++ b/doc/src/snippets/code/src_gui_util_qdesktopservices.cpp @@ -11,7 +11,10 @@ public slots: QDesktopServices::setUrlHandler("help", helpInstance, "showHelp"); //! [0] - //! [1] mailto:user@foo.com?subject=Test&body=Just a test //! [1] + +//! [2] +QDesktopServices::openUrl(QUrl("file:///C:/Documents and Settings/All Users/Desktop", QUrl::TolerantMode)); +//! [2] diff --git a/doc/src/snippets/qdebug/qdebug.pro b/doc/src/snippets/qdebug/qdebug.pro new file mode 100644 index 0000000..e62a71c --- /dev/null +++ b/doc/src/snippets/qdebug/qdebug.pro @@ -0,0 +1 @@ +SOURCES = qdebugsnippet.cpp diff --git a/doc/src/snippets/qdebugsnippet.cpp b/doc/src/snippets/qdebug/qdebugsnippet.cpp index 4c0d80d..b713f21 100644 --- a/doc/src/snippets/qdebugsnippet.cpp +++ b/doc/src/snippets/qdebug/qdebugsnippet.cpp @@ -62,9 +62,13 @@ QDebug operator<<(QDebug dbg, const Coordinate &c) int main(int argv, char **args) { - Coordinate nate; - nate.myX = 10; - nate.myY = 44; + Coordinate coordinate; + coordinate.myX = 10; + coordinate.myY = 44; - qDebug() << nate; +//! [1] + qDebug() << "Date:" << QDate::currentDate(); + qDebug() << "Types:" << QString("String") << QChar('x') << QRect(0, 10, 50, 40); + qDebug() << "Custom coordinate type:" << coordinate; +//! [1] } diff --git a/doc/src/snippets/qxmlstreamwriter/main.cpp b/doc/src/snippets/qxmlstreamwriter/main.cpp new file mode 100644 index 0000000..a0e7010 --- /dev/null +++ b/doc/src/snippets/qxmlstreamwriter/main.cpp @@ -0,0 +1,77 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (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 qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QCoreApplication> +#include <QFile> +#include <QXmlStreamWriter> +#include <stdio.h> + +int main(int argc, char *argv[]) +{ + QCoreApplication app(argc, argv); + QFile output; + output.open(stdout, QIODevice::WriteOnly); +//! [write output] +//! [start stream] + QXmlStreamWriter stream(&output); + stream.setAutoFormatting(true); + stream.writeStartDocument(); +//! [start stream] + stream.writeDTD("<!DOCTYPE xbel>"); + stream.writeStartElement("xbel"); + stream.writeAttribute("version", "1.0"); + stream.writeStartElement("folder"); + stream.writeAttribute("folded", "no"); +//! [write element] + stream.writeStartElement("bookmark"); + stream.writeAttribute("href", "http://www.qtsoftware.com/"); + stream.writeTextElement("title", "Qt Software"); + stream.writeEndElement(); // bookmark +//! [write element] + stream.writeEndElement(); // folder + stream.writeEndElement(); // xbel +//! [finish stream] + stream.writeEndDocument(); +//! [finish stream] +//! [write output] + output.close(); + return 0; +} diff --git a/doc/src/snippets/qxmlstreamwriter/qxmlstreamwriter.pro b/doc/src/snippets/qxmlstreamwriter/qxmlstreamwriter.pro new file mode 100644 index 0000000..8f74a5d --- /dev/null +++ b/doc/src/snippets/qxmlstreamwriter/qxmlstreamwriter.pro @@ -0,0 +1,2 @@ +SOURCES = main.cpp +QT += xml diff --git a/doc/src/snippets/xml/prettyprint/main.cpp b/doc/src/snippets/xml/prettyprint/main.cpp index 90f9f15..fa13ff6 100644 --- a/doc/src/snippets/xml/prettyprint/main.cpp +++ b/doc/src/snippets/xml/prettyprint/main.cpp @@ -48,7 +48,7 @@ #include <QXmlStreamReader> /* - This class exists for the solve purpose of creating a translation context. + This class exists for the sole purpose of creating a translation context. */ class PrettyPrint { diff --git a/doc/src/trolltech-webpages.qdoc b/doc/src/trolltech-webpages.qdoc index 5483a61..3897fcf 100644 --- a/doc/src/trolltech-webpages.qdoc +++ b/doc/src/trolltech-webpages.qdoc @@ -45,7 +45,7 @@ */ /*! - \externalpage http://www.qtsoftware.com/developer/notes/platforms/bugreport-form + \externalpage http://www.qtsoftware.com/bugreport-form \title Bug Report Form */ diff --git a/doc/src/tutorials/addressbook-sdk.qdoc b/doc/src/tutorials/addressbook-sdk.qdoc deleted file mode 100644 index af0013e..0000000 --- a/doc/src/tutorials/addressbook-sdk.qdoc +++ /dev/null @@ -1,116 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Qt Software Information (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 qt-sales@nokia.com. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page tutorials-addressbook-sdk.html - - \startpage {index.html}{Qt Reference Documentation} - \nextpage \l{Designing the User Interface}{Chapter 1} - - \title Address Book Tutorial - \ingroup howto - \ingroup tutorials - \brief An introduction to GUI programming with Qt and Qt Creator, - describing in detail how to put together a simple yet fully- - functioning application. - - This tutorial gives an introduction to GUI programming using the Qt SDK. - - ### Screenshot - - In the process, we will learn about some basic technologies provided by - Qt, such as: - - \list - \o Widgets and layout managers - \o Container classes - \o Signals and slots - \o Input and output devices - \endlist - - If you are completely new to Qt, please read \l{How to Learn Qt} if you - have not already done so. - - The tutorial's source code is located in Qt's - \c{examples/tutorials/addressbook} directory. - - Tutorial chapters: - - \list 1 - \o \l{Designing the User Interface} - \o \l{Adding Addresses} - \o \l{Navigating between Entries} - \o \l{Editing and Removing Addresses} - \o \l{Adding a Find Function} - \o \l{Loading and Saving} - \o \l{Additional Features} - \endlist - - Although this little application does not look much like a fully-fledged - modern GUI application, it uses many of the basic techniques that are used - in more complex applications. After you have worked through it, we - recommend checking out the \l{mainwindows/application}{Application} - example, which presents a small GUI application, with menus, toolbars, a - status bar, and so on. -*/ - - -/*! - \page tutorials-addressbook-sdk-part1.html - \contentspage {Address Book Tutorial}{Contents} - \nextpage \l{Adding Addresses}{Chapter 2} - \title Address Book 1 - Designing the User Interface - - The first part of this tutorial covers the design of the basic graphical - user interface (GUI) we use for the Address Book application. - - The first step to creating a GUI program is to design the user interface. - In this chapter, our goal is to set up the labels and input fields needed - to implement a basic address book application. The figure below is a - screenshot of our expected output. - - ### screenshot - - We begin by launching Qt Creator and use it to generate a new project. To - do this, select \gui New from the \gui File menu. In the - \gui{New File or Project} - -*/ diff --git a/doc/src/tutorials/widgets-tutorial.qdoc b/doc/src/tutorials/widgets-tutorial.qdoc index ce977f3..ead44af 100644 --- a/doc/src/tutorials/widgets-tutorial.qdoc +++ b/doc/src/tutorials/widgets-tutorial.qdoc @@ -80,7 +80,7 @@ \raw HTML <table align="left" width="100%"> - <tr><td> + <tr class="qt-code"><td> \endraw \snippet snippets/widgets-tutorial/toplevel/main.cpp create, resize and show \raw HTML @@ -98,7 +98,7 @@ \raw HTML <table align="left" width="100%"> - <tr><td> + <tr class="qt-code"><td> \endraw \snippet snippets/widgets-tutorial/childwidget/main.cpp create, position and show \raw HTML @@ -123,7 +123,7 @@ \raw HTML <table align="left" width="100%"> - <tr><td> + <tr class="qt-code"><td> \endraw \snippet snippets/widgets-tutorial/windowlayout/main.cpp create, lay out widgets and show \raw HTML @@ -157,7 +157,7 @@ \raw HTML <table align="left" width="100%"> - <tr><td> + <tr class="qt-code"><td> \endraw \snippet snippets/widgets-tutorial/nestedlayouts/main.cpp create, lay out widgets and show \raw HTML @@ -171,23 +171,4 @@ As well as QHBoxLayout and QVBoxLayout, Qt also provides QGridLayout and QFormLayout classes to help with more complex user interfaces. - - - - \omit - In the simple example below, the widget is created on the stack and will - automatically be deleted when the \c{main()} function exits. - - {{{#include <QtGui> - - int main(int argc, char *argv[]) - { - QApplication app(argc, argv); - QWidget window; - window.resize(480, 360); - window.show(); - return app.exec(); - } - }}} - \endomit */ |
