summaryrefslogtreecommitdiffstats
path: root/doc/src/network/files-and-resources
diff options
context:
space:
mode:
authorCasper van Donderen <casper.vandonderen@nokia.com>2011-09-16 14:14:43 +0200
committerQt by Nokia <qt-info@nokia.com>2011-09-19 10:24:25 +0200
commitcd621c201ca637385c6e3409d5c84ecec5fb5418 (patch)
tree981b062e3bbc5c513498b18c10ad55f8252e8486 /doc/src/network/files-and-resources
parent20009ed797fb30952a889df5716aa2399102be58 (diff)
Move the module qdoc files from qtdoc and split up doc/src.
Change-Id: I7d992889379d78e07a0b7023facebd7421cf6d22 Reviewed-on: http://codereview.qt-project.org/5092 Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com> Reviewed-by: Jerome Pasion <jerome.pasion@nokia.com>
Diffstat (limited to 'doc/src/network/files-and-resources')
-rw-r--r--doc/src/network/files-and-resources/datastreamformat.qdoc361
-rw-r--r--doc/src/network/files-and-resources/resources.qdoc214
2 files changed, 575 insertions, 0 deletions
diff --git a/doc/src/network/files-and-resources/datastreamformat.qdoc b/doc/src/network/files-and-resources/datastreamformat.qdoc
new file mode 100644
index 0000000000..6fe888b52e
--- /dev/null
+++ b/doc/src/network/files-and-resources/datastreamformat.qdoc
@@ -0,0 +1,361 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page datastreamformat.html
+ \title Serializing Qt Data Types
+ \ingroup qt-network
+ \brief Representations of data types that can be serialized by QDataStream.
+
+ The \l QDataStream allows you to serialize some of the Qt data types.
+ The table below lists the data types that QDataStream can serialize
+ and how they are represented. The format described below is
+ \l{QDataStream::setVersion()}{version 12}.
+
+ It is always best to cast integers to a Qt integer type, such as
+ qint16 or quint32, when reading and writing. This ensures that
+ you always know exactly what size integers you are reading and
+ writing, no matter what the underlying platform and architecture
+ the application happens to be running on.
+
+ \table
+ \row \o bool
+ \o \list
+ \o boolean
+ \endlist
+ \row \o qint8
+ \o \list
+ \o signed byte
+ \endlist
+ \row \o qint16
+ \o \list
+ \o signed 16-bit integer
+ \endlist
+ \row \o qint32
+ \o \list
+ \o signed 32-bit integer
+ \endlist
+ \row \o qint64
+ \o \list
+ \o signed 64-bit integer
+ \endlist
+ \row \o quint8
+ \o \list
+ \o unsigned byte
+ \endlist
+ \row \o quint16
+ \o \list
+ \o unsigned 16-bit integer
+ \endlist
+ \row \o quint32
+ \o \list
+ \o unsigned 32-bit integer
+ \endlist
+ \row \o quint64
+ \o \list
+ \o unsigned 64-bit integer
+ \endlist
+ \row \o \c float
+ \o \list
+ \o 32-bit floating point number using the standard IEEE 754 format
+ \endlist
+ \row \o \c double
+ \o \list
+ \o 64-bit floating point number using the standard IEEE 754 format
+ \endlist
+ \row \o \c {const char *}
+ \o \list
+ \o The string length (quint32)
+ \o The string bytes, excluding the terminating 0
+ \endlist
+ \row \o QBitArray
+ \o \list
+ \o The array size (quint32)
+ \o The array bits, i.e. (size + 7)/8 bytes
+ \endlist
+ \row \o QBrush
+ \o \list
+ \o The brush style (quint8)
+ \o The brush color (QColor)
+ \o If style is CustomPattern, the brush pixmap (QPixmap)
+ \endlist
+ \row \o QByteArray
+ \o \list
+ \o If the byte array is null: 0xFFFFFFFF (quint32)
+ \o Otherwise: the array size (quint32) followed by the array bytes, i.e. size bytes
+ \endlist
+ \row \o \l QColor
+ \o \list
+ \o Color spec (qint8)
+ \o Alpha value (quint16)
+ \o Red value (quint16)
+ \o Green value (quint16)
+ \o Blue value (quint16)
+ \o Pad value (quint16)
+ \endlist
+ \row \o QCursor
+ \o \list
+ \o Shape ID (qint16)
+ \o If shape is BitmapCursor: The bitmap (QPixmap), mask (QPixmap), and hot spot (QPoint)
+ \endlist
+ \row \o QDate
+ \o \list
+ \o Julian day (quint32)
+ \endlist
+ \row \o QDateTime
+ \o \list
+ \o Date (QDate)
+ \o Time (QTime)
+ \o 0 for Qt::LocalTime, 1 for Qt::UTC (quint8)
+ \endlist
+ \row \o QEasingCurve
+ \o \list
+ \o type (quint8)
+ \o func (quint64)
+ \o hasConfig (bool)
+ \o If hasConfig is true then these fields follow:
+ \o list
+ \o period (double)
+ \o amplitude (double)
+ \o overshoot (double)
+ \endlist
+ \row \o QFont
+ \o \list
+ \o The family (QString)
+ \o The point size (qint16)
+ \o The style hint (quint8)
+ \o The char set (quint8)
+ \o The weight (quint8)
+ \o The font bits (quint8)
+ \endlist
+ \row \o QHash<Key, T>
+ \o \list
+ \o The number of items (quint32)
+ \o For all items, the key (Key) and value (T)
+ \endlist
+ \row \o QIcon
+ \o \list
+ \o The number of pixmap entries (quint32)
+ \o For all pixmap entries:
+ \list
+ \o The pixmap (QPixmap)
+ \o The file name (QString)
+ \o The pixmap size (QSize)
+ \o The \l{QIcon::Mode}{mode} (quint32)
+ \o The \l{QIcon::State}{state} (quint32)
+ \endlist
+ \endlist
+ \row \o QImage
+ \o \list
+ \o If the image is null a "null image" marker is saved;
+ otherwise the image is saved in PNG or BMP format (depending
+ on the stream version). If you want control of the format,
+ stream the image into a QBuffer (using QImageIO) and stream
+ that.
+ \endlist
+ \row \o QKeySequence
+ \o \list
+ \o A QList<int>, where each integer is a key in the key sequence
+ \endlist
+ \row \o QLinkedList<T>
+ \o \list
+ \o The number of items (quint32)
+ \o The items (T)
+ \endlist
+ \row \o QList<T>
+ \o \list
+ \o The number of items (quint32)
+ \o The items (T)
+ \endlist
+ \row \o QMap<Key, T>
+ \o \list
+ \o The number of items (quint32)
+ \o For all items, the key (Key) and value (T)
+ \endlist
+ \row \o QMatrix
+ \o \list
+ \o m11 (double)
+ \o m12 (double)
+ \o m21 (double)
+ \o m22 (double)
+ \o dx (double)
+ \o dy (double)
+ \endlist
+ \row \o QMatrix4x4
+ \o \list
+ \o m11 (double)
+ \o m12 (double)
+ \o m13 (double)
+ \o m14 (double)
+ \o m21 (double)
+ \o m22 (double)
+ \o m23 (double)
+ \o m24 (double)
+ \o m31 (double)
+ \o m32 (double)
+ \o m33 (double)
+ \o m34 (double)
+ \o m41 (double)
+ \o m42 (double)
+ \o m43 (double)
+ \o m44 (double)
+ \endlist
+ \row \o QPair<T1, T2>
+ \o \list
+ \o first (T1)
+ \o second (T2)
+ \endlist
+ \row \o QPalette
+ \o The disabled, active, and inactive color groups, each of which consists
+ of the following:
+ \list
+ \o foreground (QBrush)
+ \o button (QBrush)
+ \o light (QBrush)
+ \o midlight (QBrush)
+ \o dark (QBrush)
+ \o mid (QBrush)
+ \o text (QBrush)
+ \o brightText (QBrush)
+ \o buttonText (QBrush)
+ \o base (QBrush)
+ \o background (QBrush)
+ \o shadow (QBrush)
+ \o highlight (QBrush)
+ \o highlightedText (QBrush)
+ \o link (QBrush)
+ \o linkVisited (QBrush)
+ \endlist
+ \row \o QPen
+ \o \list
+ \o The pen styles (quint8)
+ \o The pen width (quint16)
+ \o The pen color (QColor)
+ \endlist
+ \row \o QPicture
+ \o \list
+ \o The size of the picture data (quint32)
+ \o The raw bytes of picture data (char)
+ \endlist
+ \row \o QPixmap
+ \o \list
+ \o Save it as a PNG image.
+ \endlist
+ \row \o QPoint
+ \o \list
+ \o The x coordinate (qint32)
+ \o The y coordinate (qint32)
+ \endlist
+ \row \o QQuaternion
+ \o \list
+ \o The scalar component (double)
+ \o The x coordinate (double)
+ \o The y coordinate (double)
+ \o The z coordinate (double)
+ \endlist
+ \row \o QRect
+ \o \list
+ \o left (qint32)
+ \o top (qint32)
+ \o right (qint32)
+ \o bottom (qint32)
+ \endlist
+ \row \o QRegExp
+ \o \list
+ \o The regexp pattern (QString)
+ \o Case sensitivity (quint8)
+ \o Regular expression syntax (quint8)
+ \o Minimal matching (quint8)
+ \endlist
+ \row \o QRegion
+ \o \list
+ \o The size of the data, i.e. 8 + 16 * (number of rectangles) (quint32)
+ \o 10 (qint32)
+ \o The number of rectangles (quint32)
+ \o The rectangles in sequential order (QRect)
+ \endlist
+ \row \o QSize
+ \o \list
+ \o width (qint32)
+ \o height (qint32)
+ \endlist
+ \row \o QString
+ \o \list
+ \o If the string is null: 0xFFFFFFFF (quint32)
+ \o Otherwise: The string length in bytes (quint32) followed by the data in UTF-16
+ \endlist
+ \row \o QTime
+ \o \list
+ \o Milliseconds since midnight (quint32)
+ \endlist
+ \row \o QTransform
+ \o \list
+ \o m11 (double)
+ \o m12 (double)
+ \o m13 (double)
+ \o m21 (double)
+ \o m22 (double)
+ \o m23 (double)
+ \o m31 (double)
+ \o m32 (double)
+ \o m33 (double)
+ \endlist
+ \row \o QUrl
+ \o \list
+ \o Holds an URL (QString)
+ \endlist
+ \row \o QVariant
+ \o \list
+ \o The type of the data (quint32)
+ \o The null flag (qint8)
+ \o The data of the specified type
+ \endlist
+ \row \o QVector2D
+ \o \list
+ \o the x coordinate (double)
+ \o the y coordinate (double)
+ \endlist
+ \row \o QVector3D
+ \o \list
+ \o the x coordinate (double)
+ \o the y coordinate (double)
+ \o the z coordinate (double)
+ \endlist
+ \row \o QVector4D
+ \o \list
+ \o the x coordinate (double)
+ \o the y coordinate (double)
+ \o the z coordinate (double)
+ \o the w coordinate (double)
+ \endlist
+ \row \o QVector<T>
+ \o \list
+ \o The number of items (quint32)
+ \o The items (T)
+ \endlist
+ \endtable
+*/
diff --git a/doc/src/network/files-and-resources/resources.qdoc b/doc/src/network/files-and-resources/resources.qdoc
new file mode 100644
index 0000000000..d6e320bf04
--- /dev/null
+++ b/doc/src/network/files-and-resources/resources.qdoc
@@ -0,0 +1,214 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \group io
+ \title Input/Output and Networking
+ \ingroup groups
+
+ \brief Classes providing file input and output along with directory and
+ network handling.
+
+ These classes are used to handle input and output to and from external
+ devices, processes, files etc. as well as manipulating files and directories.
+*/
+
+/*!
+ \page resources.html
+ \title The Qt Resource System
+ \ingroup qt-network
+ \brief A platform-independent mechanism for storing binary files in an application.
+
+ \keyword resource system
+
+ The Qt resource system is a platform-independent mechanism for
+ storing binary files in the application's executable. This is
+ useful if your application always needs a certain set of files
+ (icons, translation files, etc.) and you don't want to run the
+ risk of losing the files.
+
+ The resource system is based on tight cooperation between \l qmake,
+ \l rcc (Qt's resource compiler), and QFile. It obsoletes Qt 3's
+ \c qembed tool and the
+ \l{http://qt.nokia.com/doc/qq/qq05-iconography.html#imagestorage}{image
+ collection} mechanism.
+
+ \section1 Resource Collection Files (\c{.qrc})
+
+ The resources associated with an application are specified in a
+ \c .qrc file, an XML-based file format that lists files on the
+ disk and optionally assigns them a resource name that the
+ application must use to access the resource.
+
+ Here's an example \c .qrc file:
+
+ \quotefile mainwindows/application/application.qrc
+
+ The resource files listed in the \c .qrc file are files that are
+ part of the application's source tree. The specified paths are
+ relative to the directory containing the \c .qrc file. Note that
+ the listed resource files must be located in the same directory as
+ the \c .qrc file, or one of its subdirectories.
+
+ Resource data can either be compiled into the binary and thus accessed
+ immediately in application code, or a binary resource can be created
+ and at a later point in application code registered with the resource
+ system.
+
+ By default, resources are accessible in the application under the
+ same file name as they have in the source tree, with a \c :/ prefix,
+ or by a \link QUrl URL\endlink with a \c qrc scheme.
+
+ For example, the file path \c :/images/cut.png or the URL
+ \c qrc:///images/cut.png would give access to the
+ \c cut.png file, whose location in the application's source tree
+ is \c images/cut.png. This can be changed using the \c file tag's
+ \c alias attribute:
+
+ \snippet doc/src/snippets/code/doc_src_resources.qdoc 0
+
+ The file is then accessible as \c :/cut-img.png from the
+ application. It is also possible to specify a path prefix for all
+ files in the \c .qrc file using the \c qresource tag's \c prefix
+ attribute:
+
+ \snippet doc/src/snippets/code/doc_src_resources.qdoc 1
+
+ In this case, the file is accessible as \c
+ :/myresources/cut-img.png.
+
+ Some resources, such as translation files and icons, many need to
+ change based on the user's locale. This is done by adding a \c lang
+ attribute to the \c qresource tag, specifying a suitable locale
+ string. For example:
+
+ \snippet doc/src/snippets/code/doc_src_resources.qdoc 2
+
+ If the user's locale is French (i.e., QLocale::system().name() returns
+ "fr_FR"), \c :/cut.jpg becomes a reference to the \c cut_fr.jpg
+ image. For other locales, \c cut.jpg is used.
+
+ See the QLocale documentation for a description of the format to use
+ for locale strings.
+
+
+ \section2 External Binary Resources
+
+ For an external binary resource to be created you must create the resource
+ data (commonly given the \c .rcc extension) by passing the -binary switch to
+ \l rcc. Once the binary resource is created you can register the resource
+ with the QResource API.
+
+ For example, a set of resource data specified in a \c .qrc file can be
+ compiled in the following way:
+
+ \snippet doc/src/snippets/code/doc_src_resources.qdoc 3
+
+ In the application, this resource would be registered with code like this:
+
+ \snippet doc/src/snippets/code/doc_src_resources.cpp 4
+
+ \section2 Compiled-In Resources
+
+ For a resource to be compiled into the binary the \c .qrc file must be
+ mentioned in the application's \c .pro file so that \c qmake knows
+ about it. For example:
+
+ \snippet examples/mainwindows/application/application.pro 0
+
+ \c qmake will produce make rules to generate a file called \c
+ qrc_application.cpp that is linked into the application. This
+ file contains all the data for the images and other resources as
+ static C++ arrays of compressed binary data. The \c
+ qrc_application.cpp file is automatically regenerated whenever
+ the \c .qrc file changes or one of the files that it refers to
+ changes. If you don't use \c .pro files, you can either invoke
+ \c rcc manually or add build rules to your build system.
+
+ \image resources.png Building resources into an application
+
+ Currently, Qt always stores the data directly in the executable,
+ even on Windows and Mac OS X, where the operating system provides
+ native support for resources. This might change in a future Qt
+ release.
+
+ \section1 Compression
+
+ Resources are compressed by default (in the \c ZIP format). It is
+ possible to turn off compression. This can be useful if your
+ resources already contain a compressed format, such as \c .png
+ files. You do this by giving the \c {-no-compress} command line
+ argument.
+
+ \code
+ rcc -no-compress myresources.qrc
+ \endcode
+
+ \c rcc also gives you some control over the compression. You can
+ specify the compression level and the threshold level to consider
+ while compressing files, for example:
+
+ \code
+ rcc -compress 2 -threshold 3 myresources.qrc
+ \endcode
+
+ \section1 Using Resources in the Application
+
+ In the application, resource paths can be used in most places
+ instead of ordinary file system paths. In particular, you can
+ pass a resource path instead of a file name to the QIcon, QImage,
+ or QPixmap constructor:
+
+ \snippet examples/mainwindows/application/mainwindow.cpp 21
+
+ See the \l{mainwindows/application}{Application} example for an
+ actual application that uses Qt's resource system to store its
+ icons.
+
+ In memory, resources are represented by a tree of resource
+ objects. The tree is automatically built at startup and used by
+ QFile for resolving paths to resources. You can use a QDir initialized
+ with ":/" to navigate through the resource tree from the root.
+
+ Qt's resources support the concept of a search path list. If you then
+ refer to a resource with \c : instead of \c :/ as the prefix, the
+ resource will be looked up using the search path list. The search
+ path list is empty at startup; call QDir::addSearchPath() to
+ add paths to it.
+
+ If you have resources in a static library, you might need to
+ force initialization of your resources by calling \l
+ Q_INIT_RESOURCE() with the base name of the \c .qrc file. For
+ example:
+
+ \snippet doc/src/snippets/code/doc_src_resources.cpp 5
+
+ Similarly, if you must unload a set of resources explicitly
+ (because a plugin is being unloaded or the resources are not valid
+ any longer), you can force removal of your resources by calling
+ Q_CLEANUP_RESOURCE() with the same base name as above.
+*/