diff options
| -rw-r--r-- | doc/src/datastorage.qdoc | 11 | ||||
| -rw-r--r-- | doc/src/development/qmake-manual.qdoc | 32 | ||||
| -rw-r--r-- | doc/src/external-resources.qdoc | 10 | ||||
| -rw-r--r-- | doc/src/externalsites/external-resources.qdoc | 5 | ||||
| -rw-r--r-- | doc/src/howtos/exceptionsafety.qdoc | 36 | ||||
| -rw-r--r-- | doc/src/howtos/third-party-libraries.qdoc | 154 | ||||
| -rw-r--r-- | sync.profile | 14 |
7 files changed, 242 insertions, 20 deletions
diff --git a/doc/src/datastorage.qdoc b/doc/src/datastorage.qdoc index cefa4fe6..90d69e02 100644 --- a/doc/src/datastorage.qdoc +++ b/doc/src/datastorage.qdoc @@ -267,4 +267,15 @@ with a qrc scheme. \list \li \l {The Qt Resource System} \endlist + +\section1 File Archiving + +An archive file is a collection of files or directories which are generally +compressed in order to reduce the space they would otherwise consume on a +drive. Examples of archive files are ZIP, TAR, RAR and 7z. + +Qt has support for archives produced by zlib (see +\l{How to compress data with Qt?}{qCompress() and qUncompress()}). There are +also several \l{Add-ons}{3rd party libraries} which can be used. + */ diff --git a/doc/src/development/qmake-manual.qdoc b/doc/src/development/qmake-manual.qdoc index 154c078e..eee96da0 100644 --- a/doc/src/development/qmake-manual.qdoc +++ b/doc/src/development/qmake-manual.qdoc @@ -65,6 +65,13 @@ \tableofcontents{1 qmake Common Projects} \endlist + The guide to \l{Third Party Libraries} shows you how to use simple third party libraries + in your Qt project using qmake. + \list + \li \l{Third Party Libraries} + \tableofcontents{1 Third Party Libraries} + \endlist + \section1 Table of Contents \list @@ -1051,6 +1058,18 @@ \row \li warn_on \li The compiler should output as many warnings as possible. This is ignored if \c warn_off is specified. \row \li warn_off \li The compiler should output as few warnings as possible. + \row \li exceptions \li Exception support is enabled. Set by default. + \row \li exceptions_off \li Exception support is disabled. + \row \li rtti \li RTTI support is enabled. By default, the compiler + default is used. + \row \li rtti_off \li RTTI support is disabled. By default, the compiler + default is used. + \row \li stl \li STL support is enabled. By default, the compiler + default is used. + \row \li stl_off \li STL support is disabled. By default, the compiler + default is used. + \row \li thread \li Thread support is enabled. This is enabled when CONFIG + includes \c qt, which is the default. \omit \row \li qt_debug \li Specifies that the project should be built against debug versions of the Qt libraries specified using the @@ -1156,19 +1175,6 @@ if defined. \endtable - These options are used to set the compiler flags: - - \table 95% - \header \li Option \li Description - \row \li 3dnow \li AMD 3DNow! instruction support is enabled. - \row \li exceptions \li Exception support is enabled. - \row \li mmx \li Intel MMX instruction support is enabled. - \row \li rtti \li RTTI support is enabled. - \row \li stl \li STL support is enabled. - \row \li sse \li SSE support is enabled. - \row \li sse2 \li SSE2 support is enabled. - \endtable - These options define specific features on Windows only: \table 95% diff --git a/doc/src/external-resources.qdoc b/doc/src/external-resources.qdoc index b843024f..7b5ec0c5 100644 --- a/doc/src/external-resources.qdoc +++ b/doc/src/external-resources.qdoc @@ -53,3 +53,13 @@ \externalpage http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html \title GNU Lesser General Public License, version 2.1 */ + +/*! + \externalpage http://qt-project.org/faq/answer/how_to_compress_data_with_qt + \title How to compress data with Qt? +*/ + +/*! + \externalpage http://qt-project.org/wiki/Category:Add-ons + \title Add-ons +*/ diff --git a/doc/src/externalsites/external-resources.qdoc b/doc/src/externalsites/external-resources.qdoc index 8d8f8557..aca78da2 100644 --- a/doc/src/externalsites/external-resources.qdoc +++ b/doc/src/externalsites/external-resources.qdoc @@ -487,3 +487,8 @@ \externalpage http://www.w3.org/TR/2009/WD-webdatabase-20091029/ \title HTML5 Web Database API */ + +/*! + \externalpage http://qt-project.org/doc/qtcreator/creator-project-qmake-libraries.html + \title Adding Libraries to Projects +*/ diff --git a/doc/src/howtos/exceptionsafety.qdoc b/doc/src/howtos/exceptionsafety.qdoc index bd290f73..9c2136c8 100644 --- a/doc/src/howtos/exceptionsafety.qdoc +++ b/doc/src/howtos/exceptionsafety.qdoc @@ -128,4 +128,40 @@ After an exception is thrown, the connection to the windowing server might already be closed. It is not safe to call a GUI related function after catching an exception. + + \section1 Exceptions in client code + + \section2 Signals and Slots + + Throwing an exception from a slot invoked by Qt's \l{Signals & Slots}{signal-slot} + connection mechanism is considered undefined behaviour, unless it is handled within the slot: + + \code + State state; + StateListener stateListener; + + // OK; the exception is handled before it leaves the slot. + QObject::connect(&state, SIGNAL(stateChanged()), &stateListener, SLOT(throwHandledException())); + // Undefined behaviour; upon invocation of the slot, the exception will be propagated to the + // point of emission, unwinding the stack of the Qt code (which is not guaranteed to be exception safe). + QObject::connect(&state, SIGNAL(stateChanged()), &stateListener, SLOT(throwUnhandledException())); + \endcode + + If the slot was invoked directly, like a regular function call, exceptions may be used. + This is because the connection mechanism is bypassed when invoking slots directly: + + \code + State state; + StateListener stateListener; + + // ... + + try { + // OK; invoking slot directly. + stateListener.throwException(); + } catch (...) { + qDebug() << "Handling exception not caught in slot."; + } + \endcode + */ diff --git a/doc/src/howtos/third-party-libraries.qdoc b/doc/src/howtos/third-party-libraries.qdoc new file mode 100644 index 00000000..521db95b --- /dev/null +++ b/doc/src/howtos/third-party-libraries.qdoc @@ -0,0 +1,154 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page third-party-libraries.html + \title Third Party Libraries + \brief A guide to using third party libraries with Qt + + Using a third-party library with Qt is a simple process. Suppose you know + of a cross-platform library that accepts audio samples of a cat's meows and + translates them into English words. This library is named \c CatWhisperer, + and has several files that it provides as part of its library. + Your project, \c MyQtApp, stores these files in a folder named \c 3rdparty: + + \list + \li MyQtApp/ + \list + \li MyQtApp.pro + \li src/ + \list + \li main.cpp + \endlist + \li 3rdparty/ + \list + \li CatWhisperer + \list + \li include/ + \list + \li CatWhisperer.h + \endlist + \li lib/ + \list + \li libCatWhisperer.so + \li CatWhisperer.lib + \endlist + \li bin/ + \list + \li CatWhisperer.dll + \endlist + \endlist + \endlist + \endlist + \endlist + + To use the \c CatWhisperer library in \c MyQtApp, \c qmake requires the + location and names of the \c CatWhisperer libraries. + Optionally, you can also: + + \list + \li Provide the location of the \c CatWhisperer source code so that you + don't have to type out the full path to each file when you include them + in your own code. + \li Choose the destination in which the \c MyQtApp executable will be + created. + \endlist + + The information above is provided in the \c .pro file, so that \c qmake can + parse it and produce makefiles. Makefiles contain all the information + needed by your compiler and linker to produce output, whether it is an + executable, another library file, etc. The next sections explain the syntax + with which \c qmake expects you to provide this information. + + \section1 Source code + + To be able to write + + \code + #include <CatWhisperer.h> + \endcode + + instead of + + \code + #include <3rdparty/CatWhisperer/include/CatWhisperer.h> + \endcode + + you can provide the path to the \c CatWhisperer \c include directory, + using the \l{qmake Variable Reference#INCLUDEPATH}{INCLUDEPATH} variable: + + \code + INCLUDEPATH += 3rdparty/CatWhisperer/include + \endcode + + \section1 Library files + + To let \c qmake know where to find the \c CatWhisperer library files, + use the \l{qmake Variable Reference#LIBS}{LIBS} variable: + + \code + LIBS += -L"3rdparty/CatWhisperer/lib" -lCatWhisperer + \endcode + + The first part of the expression lets the linker know in which directory + it should look for the library files. The double quotes are only necessary + when the path contains spaces, so we could have omitted them in this + example. + + The second part tells the linker which libraries to link against. We have + two different library files for UNIX platforms and Windows, respectively: + \c libCatWhisperer.so and \c CatWhisperer.lib. It is not necessary + to specify the \c .lib extension, nor the \c lib prefix + (on UNIX platforms). + + \section1 Destination directory + + By default, \c qmake creates the executable in the same directory as the + \c .pro file. We can choose our own directory using the + \l{qmake Variable Reference#DESTDIR}{DESTDIR} variable: + + \code + DESTDIR = bin + \endcode + + That's it! You can now use the \c CatWhisperer library in your project. + The final \c .pro file looks like this: + + \code + TARGET = MyQtApp + + TEMPLATE = app + + INCLUDEPATH += 3rdparty/CatWhisperer/include + + SOURCES += src/main.cpp + + LIBS += -L"3rdparty/CatWhisperer/lib" -lCatWhisperer + \endcode + + \sa {qmake Manual}, {Adding Libraries to Projects} +*/ diff --git a/sync.profile b/sync.profile index 6d3be16a..0d26ab21 100644 --- a/sync.profile +++ b/sync.profile @@ -5,11 +5,11 @@ # - any git symbolic ref resolvable from the module's repository (e.g. "refs/heads/master" to track master branch) # %dependencies = ( - "qtbase" => "refs/heads/stable", - "qtscript" => "refs/heads/stable", - "qtsvg" => "refs/heads/stable", - "qtxmlpatterns" => "refs/heads/stable", - "qttools" => "refs/heads/stable", - "qtdeclarative" => "refs/heads/stable", - "qtjsbackend" => "refs/heads/stable", + "qtbase" => "refs/heads/dev", + "qtscript" => "refs/heads/dev", + "qtsvg" => "refs/heads/dev", + "qtxmlpatterns" => "refs/heads/dev", + "qttools" => "refs/heads/dev", + "qtdeclarative" => "refs/heads/dev", + "qtjsbackend" => "refs/heads/dev", ); |