diff options
Diffstat (limited to 'src/corelib/doc/src')
| -rw-r--r-- | src/corelib/doc/src/containers.qdoc | 5 | ||||
| -rw-r--r-- | src/corelib/doc/src/datastreamformat.qdoc | 402 | ||||
| -rw-r--r-- | src/corelib/doc/src/dontdocument.qdoc | 41 | ||||
| -rw-r--r-- | src/corelib/doc/src/objectmodel/metaobjects.qdoc | 2 | ||||
| -rw-r--r-- | src/corelib/doc/src/resource-system.qdoc | 67 |
5 files changed, 161 insertions, 356 deletions
diff --git a/src/corelib/doc/src/containers.qdoc b/src/corelib/doc/src/containers.qdoc index a1c32bb007..e6c95129db 100644 --- a/src/corelib/doc/src/containers.qdoc +++ b/src/corelib/doc/src/containers.qdoc @@ -171,8 +171,9 @@ The values stored in the various containers can be of any \e{assignable data type}. To qualify, a type must provide a - default constructor, a copy constructor, and an assignment - operator. This covers most data types you are likely to want to + copy constructor, and an assignment operator. For some + operations a default constructor is also required. This + covers most data types you are likely to want to store in a container, including basic types such as \c int and \c double, pointer types, and Qt data types such as QString, QDate, and QTime, but it doesn't cover QObject or any QObject subclass diff --git a/src/corelib/doc/src/datastreamformat.qdoc b/src/corelib/doc/src/datastreamformat.qdoc index 73ca51974d..d6b60f10ce 100644 --- a/src/corelib/doc/src/datastreamformat.qdoc +++ b/src/corelib/doc/src/datastreamformat.qdoc @@ -28,357 +28,71 @@ /*! \page datastreamformat.html \title Serializing Qt Data Types - \brief Representations of data types that can be serialized by QDataStream. + \brief List 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 13}. + The \l QDataStream class allows you to serialize the Qt data types + listed in this section as of \l{QDataStream::setVersion()}{version 18}. It is always best to cast integers to a Qt integer type, such as - qint16 or quint32, when reading and writing. This ensures that + \l{qint16} or \l{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 \li bool - \li \list - \li boolean - \endlist - \row \li qint8 - \li \list - \li signed byte - \endlist - \row \li qint16 - \li \list - \li signed 16-bit integer - \endlist - \row \li qint32 - \li \list - \li signed 32-bit integer - \endlist - \row \li qint64 - \li \list - \li signed 64-bit integer - \endlist - \row \li quint8 - \li \list - \li unsigned byte - \endlist - \row \li quint16 - \li \list - \li unsigned 16-bit integer - \endlist - \row \li quint32 - \li \list - \li unsigned 32-bit integer - \endlist - \row \li quint64 - \li \list - \li unsigned 64-bit integer - \endlist - \row \li \c float - \li \list - \li 32-bit floating point number using the standard IEEE 754 format - \endlist - \row \li \c double - \li \list - \li 64-bit floating point number using the standard IEEE 754 format - \endlist - \row \li \c {const char *} - \li \list - \li The string length (quint32) - \li The string bytes, excluding the terminating 0 - \endlist - \row \li QBitArray - \li \list - \li The array size (quint32) - \li The array bits, i.e. (size + 7)/8 bytes - \endlist - \row \li QBrush - \li \list - \li The brush style (quint8) - \li The brush color (QColor) - \li If style is CustomPattern, the brush pixmap (QPixmap) - \endlist - \row \li QByteArray - \li \list - \li If the byte array is null: 0xFFFFFFFF (quint32) - \li Otherwise: the array size (quint32) followed by the array bytes, i.e. size bytes - \endlist - \row \li \l QColor - \li \list - \li Color spec (qint8) - \li Alpha value (quint16) - \li Red value (quint16) - \li Green value (quint16) - \li Blue value (quint16) - \li Pad value (quint16) - \endlist - \row \li QCursor - \li \list - \li Shape ID (qint16) - \li If shape is BitmapCursor: The bitmap (QPixmap), mask (QPixmap), and hot spot (QPoint) - \endlist - \row \li QDate - \li \list - \li Julian day (quint32) - \endlist - \row \li QDateTime - \li \list - \li Date (QDate) - \li Time (QTime) - \li The \l{Qt::TimeSpec}{time spec} - offsetFromUtc (qint32) if Qt::TimeSpec is offsetFromUtc - TimeZone(QTimeZone) if Qt::TimeSpec is TimeZone - \endlist - \row \li QEasingCurve - \li \list - \li type (quint8) - \li func (quint64) - \li hasConfig (bool) - \li If hasConfig is true then these fields follow: - \li list - \li period (double) - \li amplitude (double) - \li overshoot (double) - \endlist - \row \li QFont - \li \list - \li The family (QString) - \li The style name (QString) - \li The point size (double) - \li The pixel size (qint32) - \li The style hint (quint8) - \li The style strategy (quint16) - \li The char set (quint8) - \li The weight (quint8) - \li The font bits (quint8) - \li The font stretch (quint16) - \li The extended font bits (quint8) - \li The letter spacing (double) - \li The word spacing (double) - \li The hinting preference (quint8) - \endlist - \row \li QHash<Key, T> - \li \list - \li The number of items (quint32) - \li For all items, the key (Key) and value (T) - \endlist - \row \li QIcon - \li \list - \li The number of pixmap entries (quint32) - \li For all pixmap entries: - \list - \li The pixmap (QPixmap) - \li The file name (QString) - \li The pixmap size (QSize) - \li The \l{QIcon::Mode}{mode} (quint32) - \li The \l{QIcon::State}{state} (quint32) - \endlist - \endlist - \row \li QImage - \li \list - \li 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 QImageIOHandler/QImageIOPlugin) and stream - that. - \endlist - \row \li QKeySequence - \li \list - \li A QList<int>, where each integer is a key in the key sequence - \endlist - \row \li QLinkedList<T> - \li \list - \li The number of items (quint32) - \li The items (T) - \endlist - \row \li QList<T> - \li \list - \li The number of items (quint32) - \li The items (T) - \endlist - \row \li QMap<Key, T> - \li \list - \li The number of items (quint32) - \li For all items, the key (Key) and value (T) - \endlist - \row \li QMargins - \li \list - \li left (int) - \li top (int) - \li right (int) - \li bottom (int) - \endlist - \row \li QMatrix - \li \list - \li m11 (double) - \li m12 (double) - \li m21 (double) - \li m22 (double) - \li dx (double) - \li dy (double) - \endlist - \row \li QMatrix4x4 - \li \list - \li m11 (float) - \li m12 (float) - \li m13 (float) - \li m14 (float) - \li m21 (float) - \li m22 (float) - \li m23 (float) - \li m24 (float) - \li m31 (float) - \li m32 (float) - \li m33 (float) - \li m34 (float) - \li m41 (float) - \li m42 (float) - \li m43 (float) - \li m44 (float) - \endlist - \row \li QPair<T1, T2> - \li \list - \li first (T1) - \li second (T2) - \endlist - \row \li QPalette - \li The disabled, active, and inactive color groups, each of which consists - of the following: - \list - \li foreground (QBrush) - \li button (QBrush) - \li light (QBrush) - \li midlight (QBrush) - \li dark (QBrush) - \li mid (QBrush) - \li text (QBrush) - \li brightText (QBrush) - \li buttonText (QBrush) - \li base (QBrush) - \li background (QBrush) - \li shadow (QBrush) - \li highlight (QBrush) - \li highlightedText (QBrush) - \li link (QBrush) - \li linkVisited (QBrush) - \endlist - \row \li QPen - \li \list - \li The pen styles (quint8) - \li The pen width (quint16) - \li The pen color (QColor) - \endlist - \row \li QPicture - \li \list - \li The size of the picture data (quint32) - \li The raw bytes of picture data (char) - \endlist - \row \li QPixmap - \li \list - \li Save it as a PNG image. - \endlist - \row \li QPoint - \li \list - \li The x coordinate (qint32) - \li The y coordinate (qint32) - \endlist - \row \li QQuaternion - \li \list - \li The scalar component (float) - \li The x coordinate (float) - \li The y coordinate (float) - \li The z coordinate (float) - \endlist - \row \li QRect - \li \list - \li left (qint32) - \li top (qint32) - \li right (qint32) - \li bottom (qint32) - \endlist - \row \li QRegExp - \li \list - \li The regexp pattern (QString) - \li Case sensitivity (quint8) - \li Regular expression syntax (quint8) - \li Minimal matching (quint8) - \endlist - \row \li QRegularExpression - \li \list - \li The regular expression pattern (QString) - \li The pattern options (quint32) - \endlist - \row \li QRegion - \li \list - \li The size of the data, i.e. 8 + 16 * (number of rectangles) (quint32) - \li 10 (qint32) - \li The number of rectangles (quint32) - \li The rectangles in sequential order (QRect) - \endlist - \row \li QSize - \li \list - \li width (qint32) - \li height (qint32) - \endlist - \row \li QString - \li \list - \li If the string is null: 0xFFFFFFFF (quint32) - \li Otherwise: The string length in bytes (quint32) followed by the data in UTF-16 - \endlist - \row \li QTime - \li \list - \li Milliseconds since midnight (quint32) - \endlist - \row \li QTransform - \li \list - \li m11 (double) - \li m12 (double) - \li m13 (double) - \li m21 (double) - \li m22 (double) - \li m23 (double) - \li m31 (double) - \li m32 (double) - \li m33 (double) - \endlist - \row \li QUrl - \li \list - \li Holds an URL (QString) - \endlist - \row \li QVariant - \li \list - \li The type of the data (quint32) - \li The null flag (qint8) - \li The data of the specified type - \endlist - \row \li QVector2D - \li \list - \li the x coordinate (float) - \li the y coordinate (float) - \endlist - \row \li QVector3D - \li \list - \li the x coordinate (float) - \li the y coordinate (float) - \li the z coordinate (float) - \endlist - \row \li QVector4D - \li \list - \li the x coordinate (float) - \li the y coordinate (float) - \li the z coordinate (float) - \li the w coordinate (float) - \endlist - \row \li QVector<T> - \li \list - \li The number of items (quint32) - \li The items (T) - \endlist - \endtable + \list + \li bool + \li \l{qint8} + \li \l{qint16} + \li \l{qint32} + \li \l{qint64} + \li \l{quint8} + \li \l{quint16} + \li \l{quint32} + \li \l{quint64} + \li \c float + \li \c double + \li \c {const char *} + \li QBitArray + \li QBrush + \li QByteArray + \li QColor + \li QCursor + \li QDate + \li QDateTime + \li QEasingCurve + \li QFont + \li QGenericMatrix + \li QHash<Key, T> + \li QIcon + \li QImage + \li QKeySequence + \li QLinkedList<T> + \li QList<T> + \li QMap<Key, T> + \li QMargins + \li QMatrix4x4 + \li QPair<T1, T2> + \li QPalette + \li QPen + \li QPicture + \li QPixmap + \li QPoint + \li QQuaternion + \li QRect + \li QRegExp + \li QRegularExpression + \li QRegion + \li QSize + \li QString + \li QTime + \li QTransform + \li QUrl + \li QVariant + \li QVector2D + \li QVector3D + \li QVector4D + \li QVector<T> + \endlist \sa {JSON Support in Qt} */ diff --git a/src/corelib/doc/src/dontdocument.qdoc b/src/corelib/doc/src/dontdocument.qdoc new file mode 100644 index 0000000000..19ca7db299 --- /dev/null +++ b/src/corelib/doc/src/dontdocument.qdoc @@ -0,0 +1,41 @@ +/**************************************************************************** +** +** Copyright (C) 2019 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** 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 The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \dontdocument (QMacAutoReleasePool QIncompatibleFlag QGenericAtomicOps QAtomicTraits + QAtomicOps QBasicAtomicInteger QBasicAtomicPointer QBasicMutex QInternal + QArgument QReturnArgument QArrayData QTypedArrayData QStaticByteArrayData + QByteRef QStaticStringData QListSpecialMethods QListData QScopedPointerDeleter + QScopedPointerArrayDeleter QScopedPointerPodDeleter QScopedPointerObjectDeleteLater + QMetaTypeId2 QObjectData QObjectUserData QMapNodeBase QMapNode QMapDataBase + QMapData QHashData QHashNode QArrayDataPointer QTextStreamManipulator + QContiguousCacheData QContiguousCacheTypedData QNoDebug QUrlTwoFlags + QCborValueRef qfloat16 QDeferredDeleteEvent QSpecialInteger QLittleEndianStorageType + QBigEndianStorageType QFactoryInterface QFutureWatcherBase QJsonValuePtr + QJsonValueRefPtr QLinkedListNode QAbstractConcatenable QStringBuilderCommon + QTextCodec::ConverterState QThreadStorageData) +*/ diff --git a/src/corelib/doc/src/objectmodel/metaobjects.qdoc b/src/corelib/doc/src/objectmodel/metaobjects.qdoc index 5b3d8f9863..53b34fe120 100644 --- a/src/corelib/doc/src/objectmodel/metaobjects.qdoc +++ b/src/corelib/doc/src/objectmodel/metaobjects.qdoc @@ -86,7 +86,7 @@ that it doesn't require RTTI support and it works across dynamic library boundaries. It attempts to cast its argument to the pointer type specified in angle-brackets, returning a non-zero pointer if the - object is of the correct type (determined at run-time), or 0 + object is of the correct type (determined at run-time), or \nullptr if the object's type is incompatible. For example, let's assume \c MyWidget inherits from QWidget and diff --git a/src/corelib/doc/src/resource-system.qdoc b/src/corelib/doc/src/resource-system.qdoc index 9b6b613f79..69ec5e556b 100644 --- a/src/corelib/doc/src/resource-system.qdoc +++ b/src/corelib/doc/src/resource-system.qdoc @@ -100,6 +100,9 @@ See the QLocale documentation for a description of the format to use for locale strings. + See QFileSelector for an additional mechanism to select locale-specific + resources, in addition to the ability to select OS-specific and other + features. \section2 External Binary Resources @@ -143,24 +146,70 @@ \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. + \c rcc attempts to compress the content to optimize disk space usage in the + final binaries. By default, it will perform a heuristic check to determine + whether compressing is worth it and will store the content uncompressed if + it fails to sufficiently compress. To control the threshold, you can use + the \c {-threshold} option, which tells \c rcc the percentage of the + original file size that must be gained for it to store the file in + compressed form. + + \code + rcc -threshold 25 myresources.qrc + \endcode + + The default value is "70", indicating that the compressed file must be 70% + smaller than the original (no more than 30% of the original file size). + + It is possible to turn off compression, if desired. This can be useful if + your resources already contain a compressed format, such as \c .png files, + and you do not want to incur the CPU cost at build time to confirm that it + can't be compressed. Another reason is if disk usage is not a problem and + the application would prefer to keep the content as clean memory pages at + runtime. 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: + \c rcc also gives you some control over the compression level and + compression algorithm, for example: \code - rcc -compress 2 -threshold 3 myresources.qrc + rcc -compress 2 -compress-algo zlib myresources.qrc \endcode + \c rcc supports the following compression algorithms and compression + levels: + + \list + \li \c{best}: use the best algorithm among the ones below, at its highest + compression level, to achieve the most compression at the expense of + using a lot of CPU time during compilation. This value is useful in the + XML file to indicate a file should be most compressed, regardless of + which algorithms \c rcc supports. + + \li \c{zstd}: use the \l{Zstandard}{https://zstd.net} library to compress + contents. Valid compression levels range from 1 to 19, 1 is least + compression (least CPU time) and 19 is the most compression (most CPU + time). The default level is 14. A special value of 0 tells the \c{zstd} + library to choose an implementation-defined default. + + \li \c{zlib}: use the \l{zlib}{https://zlib.net} library to compress + contents. Valid compression levels range from 1 to 9, with 1the least + compression (least CPU time) and 9 the most compression (most CPU time). + The special value 0 means "no compression" and should not be used. The + default is implementation-defined, but usually is level 6. + + \li \c{none}: no compression. This is the same as the \c{-no-compress} + option. + \endlist + + Support for both Zstandard and zlib are optional. If a given library was + not detected at compile time, attempting to pass \c {-compress-algo} for + that library will result in an error. The default compression algorithm is + \c zstd if it is enabled, \c zlib if not. + \section1 Using Resources in the Application In the application, resource paths can be used in most places |