summaryrefslogtreecommitdiffstats
path: root/src/corelib/doc
diff options
context:
space:
mode:
Diffstat (limited to 'src/corelib/doc')
-rw-r--r--src/corelib/doc/qtcore.qdocconf16
-rw-r--r--src/corelib/doc/snippets/code/doc_src_plugins-howto.cpp17
-rw-r--r--src/corelib/doc/snippets/code/doc_src_plugins-howto.pro11
-rw-r--r--src/corelib/doc/snippets/code/src_corelib_io_qsettings.cpp2
-rw-r--r--src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp2
-rw-r--r--src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp2
-rw-r--r--src/corelib/doc/snippets/hellotrmain.cpp57
-rw-r--r--src/corelib/doc/src/custom-types.qdoc165
-rw-r--r--src/corelib/doc/src/implicit-sharing.qdoc2
-rw-r--r--src/corelib/doc/src/json.qdoc2
-rw-r--r--src/corelib/doc/src/objectmodel/object.qdoc3
-rw-r--r--src/corelib/doc/src/objectmodel/properties.qdoc4
-rw-r--r--src/corelib/doc/src/plugins-howto.qdoc25
-rw-r--r--src/corelib/doc/src/statemachine.qdoc2
-rw-r--r--src/corelib/doc/src/threads-basics.qdoc18
-rw-r--r--src/corelib/doc/src/threads.qdoc8
-rw-r--r--src/corelib/doc/src/timers.qdoc123
17 files changed, 407 insertions, 52 deletions
diff --git a/src/corelib/doc/qtcore.qdocconf b/src/corelib/doc/qtcore.qdocconf
index 2151d95f65..61c9d2bc00 100644
--- a/src/corelib/doc/qtcore.qdocconf
+++ b/src/corelib/doc/qtcore.qdocconf
@@ -3,21 +3,21 @@ include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
project = QtCore
description = Qt Core Reference Documentation
url = http://qt-project.org/doc/qtcore
-version = 5.0.0
+version = 5.0.1
examplesinstallpath = core
qhp.projects = QtCore
qhp.QtCore.file = qtcore.qhp
-qhp.QtCore.namespace = org.qt-project.qtcore.500
+qhp.QtCore.namespace = org.qt-project.qtcore.501
qhp.QtCore.virtualFolder = qtcore
qhp.QtCore.indexTitle = Qt Core
qhp.QtCore.indexRoot =
-qhp.QtCore.filterAttributes = qtcore 5.0.0 qtrefdoc
-qhp.QtCore.customFilters.Qt.name = QtCore 5.0.0
-qhp.QtCore.customFilters.Qt.filterAttributes = qtcore 5.0.0
+qhp.QtCore.filterAttributes = qtcore 5.0.1 qtrefdoc
+qhp.QtCore.customFilters.Qt.name = QtCore 5.0.1
+qhp.QtCore.customFilters.Qt.filterAttributes = qtcore 5.0.1
qhp.QtCore.subprojects = classes
qhp.QtCore.subprojects.classes.title = C++ Classes
qhp.QtCore.subprojects.classes.indexTitle = Qt Core C++ Classes
@@ -26,7 +26,7 @@ qhp.QtCore.subprojects.classes.sortPages = true
tagfile = ../../../doc/qtcore/qtcore.tags
-depends += qtgui qtwidgets qtnetwork qtdoc qtquick
+depends += qtgui qtwidgets qtnetwork qtdoc qtquick qtlinguist qtdesigner
headerdirs += ..
@@ -35,6 +35,8 @@ sourcedirs += ..
exampledirs += \
../ \
snippets \
- ../../../examples/threads
+ ../../../examples/threads/ \
+ ../../../examples/tools/ \
+ ../../../examples/widgets/widgets/analogclock
imagedirs += images
diff --git a/src/corelib/doc/snippets/code/doc_src_plugins-howto.cpp b/src/corelib/doc/snippets/code/doc_src_plugins-howto.cpp
index ca6e64a90e..a86441c822 100644
--- a/src/corelib/doc/snippets/code/doc_src_plugins-howto.cpp
+++ b/src/corelib/doc/snippets/code/doc_src_plugins-howto.cpp
@@ -65,20 +65,3 @@ QStyle *MyStylePlugin::create(const QString &key)
//! [2]
QApplication::setStyle(QStyleFactory::create("MyStyle"));
//! [2]
-
-
-//! [4]
-#include <QApplication>
-#include <QtPlugin>
-
-Q_IMPORT_PLUGIN(qjpeg)
-Q_IMPORT_PLUGIN(qgif)
-Q_IMPORT_PLUGIN(qkrcodecs)
-
-int main(int argc, char *argv[])
-{
- QApplication app(argc, argv);
- ...
- return app.exec();
-}
-//! [4]
diff --git a/src/corelib/doc/snippets/code/doc_src_plugins-howto.pro b/src/corelib/doc/snippets/code/doc_src_plugins-howto.pro
index 20d5f7e41b..b33db7942f 100644
--- a/src/corelib/doc/snippets/code/doc_src_plugins-howto.pro
+++ b/src/corelib/doc/snippets/code/doc_src_plugins-howto.pro
@@ -42,9 +42,20 @@
CONFIG += release
#! [3]
+#! [4]
+CONFIG += qpa_minimal_plugin
+#! [4]
#! [5]
QTPLUGIN += qjpeg \
qgif \
qkrcodecs
#! [5]
+
+#! [6]
+CONFIG -= import_qpa_plugin
+#! [6]
+
+#! [7]
+CONFIG -= import_plugins
+#! [7]
diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qsettings.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qsettings.cpp
index ab54033ef3..d3dde5be66 100644
--- a/src/corelib/doc/snippets/code/src_corelib_io_qsettings.cpp
+++ b/src/corelib/doc/snippets/code/src_corelib_io_qsettings.cpp
@@ -82,7 +82,7 @@ settings.value("HKEY_CURRENT_USER\\MySoft\\Star Runner\\Galaxy\\Default"); // re
//! [7]
-#ifdef Q_WS_MAC
+#ifdef Q_OS_MAC
QSettings settings("grenoullelogique.fr", "Squash");
#else
QSettings settings("Grenoulle Logique", "Squash");
diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp
index c462083328..1735efbfde 100644
--- a/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp
+++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp
@@ -377,7 +377,7 @@ Q_PROPERTY(type name
[DESIGNABLE bool]
[SCRIPTABLE bool]
[STORED bool]
- [USER bool]
+ [USER bool]
[CONSTANT]
[FINAL])
//! [36]
diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp
index 71c6fbd80f..eef026af75 100644
--- a/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp
+++ b/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp
@@ -251,7 +251,7 @@ ba.lastIndexOf("X"); // returns -1
//! [25]
-QByteArray url("ftp://ftp.qt.nokia.com/");
+QByteArray url("ftp://ftp.qt-project.org/");
if (url.startsWith("ftp:"))
...
//! [25]
diff --git a/src/corelib/doc/snippets/hellotrmain.cpp b/src/corelib/doc/snippets/hellotrmain.cpp
new file mode 100644
index 0000000000..fdb034c241
--- /dev/null
+++ b/src/corelib/doc/snippets/hellotrmain.cpp
@@ -0,0 +1,57 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the examples of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+** of its contributors may be used to endorse or promote products derived
+** from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+int main(int argc, char *argv[])
+{
+ QApplication app(argc, argv);
+
+ QTranslator translator;
+ translator.load("hellotr_la");
+ app.installTranslator(&translator);
+
+ QPushButton hello(QPushButton::tr("Hello world!"));
+ hello.resize(100, 30);
+
+ hello.show();
+ return app.exec();
+}
+//! [0]
+
diff --git a/src/corelib/doc/src/custom-types.qdoc b/src/corelib/doc/src/custom-types.qdoc
new file mode 100644
index 0000000000..95987ec014
--- /dev/null
+++ b/src/corelib/doc/src/custom-types.qdoc
@@ -0,0 +1,165 @@
+/****************************************************************************
+**
+** 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 custom-types.html
+ \title Creating Custom Qt Types
+ \brief How to create and register new types with Qt.
+
+ \ingroup best-practices
+
+ \tableofcontents
+
+ \section1 Overview
+
+ When creating user interfaces with Qt, particularly those with specialized controls and
+ features, developers sometimes need to create new data types that can be used alongside
+ or in place of Qt's existing set of value types.
+
+ 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
+ \li a public default constructor,
+ \li a public copy constructor, and
+ \li a public destructor.
+ \endlist
+
+ The following \c Message class definition includes these members:
+
+ \snippet 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 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 queuedcustomtype/main.cpp main start
+ \dots
+ \snippet queuedcustomtype/main.cpp register meta-type for queued communications
+ \dots
+ \snippet queuedcustomtype/main.cpp main finish
+
+ This type is later used in a signal-slot connection in the \c{window.cpp} file:
+
+ \snippet queuedcustomtype/window.cpp Window constructor start
+ \dots
+ \snippet queuedcustomtype/window.cpp connecting signal with custom type
+ \dots
+ \snippet 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 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 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 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/src/corelib/doc/src/implicit-sharing.qdoc b/src/corelib/doc/src/implicit-sharing.qdoc
index 39ba702d55..baed85fb18 100644
--- a/src/corelib/doc/src/implicit-sharing.qdoc
+++ b/src/corelib/doc/src/implicit-sharing.qdoc
@@ -135,7 +135,7 @@
\warning Do not copy an implicitly shared container (QMap,
QVector, etc.) while you are iterating over it using an non-const
- \l{STL-style iterator}.
+ \l{STL-style iterators}{STL-style iterator}.
\keyword implicitly shared classes
\annotatedlist shared
diff --git a/src/corelib/doc/src/json.qdoc b/src/corelib/doc/src/json.qdoc
index ff06b48008..109102f190 100644
--- a/src/corelib/doc/src/json.qdoc
+++ b/src/corelib/doc/src/json.qdoc
@@ -99,8 +99,6 @@
A valid JSON document is either an array or an object, so a document always starts
with a square or curly bracket.
- JSON support in Qt consists of a set of 4 classes.
-
\section1 The JSON Classes
diff --git a/src/corelib/doc/src/objectmodel/object.qdoc b/src/corelib/doc/src/objectmodel/object.qdoc
index 47f56372de..edf5673da0 100644
--- a/src/corelib/doc/src/objectmodel/object.qdoc
+++ b/src/corelib/doc/src/objectmodel/object.qdoc
@@ -47,7 +47,7 @@
properties}
\li powerful \l{The Event System}{events and event filters}
\li contextual \l{i18n}{string translation for internationalization}
- \li sophisticated interval driven \l timers that make it possible
+ \li sophisticated interval driven \l {Timers}{timers} that make it possible
to elegantly integrate many tasks in an event-driven GUI
\li hierarchical and queryable \l{Object Trees & Ownership}{object
trees} that organize object ownership in a natural way
@@ -56,6 +56,7 @@
pointers which become dangling pointers when their objects are destroyed
\li a \l{metaobjects.html#qobjectcast}{dynamic cast} that works across
library boundaries.
+ \li support for \l{Creating Custom Qt Types}{custom type} creation.
\endlist
Many of these Qt features are implemented with standard C++
diff --git a/src/corelib/doc/src/objectmodel/properties.qdoc b/src/corelib/doc/src/objectmodel/properties.qdoc
index 4ea52050b8..d818d1154c 100644
--- a/src/corelib/doc/src/objectmodel/properties.qdoc
+++ b/src/corelib/doc/src/objectmodel/properties.qdoc
@@ -89,8 +89,8 @@
\li The \c DESIGNABLE attribute indicates whether the property
should be visible in the property editor of GUI design tool (e.g.,
- \l {Qt Designer}). Most properties are \c DESIGNABLE (default
- true). Instead of true or false, you can specify a boolean
+ \l {Qt Designer Manual}{Qt Designer}). Most properties are \c DESIGNABLE
+ (default true). Instead of true or false, you can specify a boolean
member function.
\li The \c SCRIPTABLE attribute indicates whether this property
diff --git a/src/corelib/doc/src/plugins-howto.qdoc b/src/corelib/doc/src/plugins-howto.qdoc
index 332b92596b..d94bf2eadc 100644
--- a/src/corelib/doc/src/plugins-howto.qdoc
+++ b/src/corelib/doc/src/plugins-howto.qdoc
@@ -266,18 +266,22 @@
\row \li \c qsqltds \li SQL driver \li Sybase Adaptive Server (TDS)
\endtable
- To link statically against those plugins, you need to use the
- Q_IMPORT_PLUGIN() macro in your application and you need to add
+ To link statically against those plugins, you need to add
the required plugins to your build using \c QTPLUGIN.
- For example, in your \c main.cpp:
-
- \snippet code/doc_src_plugins-howto.cpp 4
+ Q_IMPORT_PLUGIN() macros are also needed in application code,
+ but those are automatically generated by qmake and added to
+ your application project.
In the \c .pro file for your application, you need the following
entry:
\snippet code/doc_src_plugins-howto.pro 5
+ If you do not want all plugins added to QTPLUGIN to be automatically
+ linked, remove \c import_plugins from the \c CONFIG variable:
+
+ \snippet code/doc_src_plugins-howto.pro 7
+
It is also possible to create your own static plugins, by
following these steps:
@@ -296,6 +300,17 @@
to make sure that the \c{QT_STATICPLUGIN} preprocessor macro is
defined.
+ The default Qt platform adaptation plugin is automatically added to QTPLUGIN
+ in static builds. If you want to add the minimal plugin instead, add \c qpa_minimal_plugin
+ to \c CONFIG:
+
+ \snippet code/doc_src_plugins-howto.pro 4
+
+ If you want neither the default nor the minimal QPA plugin to be linked automatically,
+ remove \c import_qpa_plugin from \c CONFIG:
+
+ \snippet code/doc_src_plugins-howto.pro 6
+
\section1 Deploying and Debugging Plugins
The \l{Deploying Plugins} document covers the process of deploying
diff --git a/src/corelib/doc/src/statemachine.qdoc b/src/corelib/doc/src/statemachine.qdoc
index b241b4aff4..e23b911f85 100644
--- a/src/corelib/doc/src/statemachine.qdoc
+++ b/src/corelib/doc/src/statemachine.qdoc
@@ -45,7 +45,7 @@
The State Machine framework provides classes for creating and executing
state graphs. The concepts and notation are based on those from Harel's
- \l{Statecharts: A visual formalism for complex systems}{Statecharts}, which
+ \l{http://www.wisdom.weizmann.ac.il/~dharel/SCANNED.PAPERS/Statecharts.pdf}{Statecharts: A visual formalism for complex systems}, which
is also the basis of UML state diagrams. The semantics of state machine
execution are based on \l{State Chart XML: State Machine Notation for
Control Abstraction}{State Chart XML (SCXML)}.
diff --git a/src/corelib/doc/src/threads-basics.qdoc b/src/corelib/doc/src/threads-basics.qdoc
index 501edb6ecf..ea804f2d6d 100644
--- a/src/corelib/doc/src/threads-basics.qdoc
+++ b/src/corelib/doc/src/threads-basics.qdoc
@@ -244,18 +244,18 @@
code that generates another thread which says hello in that thread and then
exits.
- \snippet tutorials/threads/hellothread/hellothread.h 1
+ \snippet ../widgets/tutorials/threads/hellothread/hellothread.h 1
We derive a class from QThread and reimplement the \l{QThread::}{run()}
method.
- \snippet tutorials/threads/hellothread/hellothread.cpp 1
+ \snippet ../widgets/tutorials/threads/hellothread/hellothread.cpp 1
The run method contains the code that will be run in a separate thread. In
this example, a message containing the thread ID will be printed.
QThread::start() will call the method in another thread.
- \snippet tutorials/threads/hellothread/main.cpp 1
+ \snippet ../widgets/tutorials/threads/hellothread/main.cpp 1
To start the thread, our thread object needs to be instantiated. The
\l{QThread::}{start()} method creates a new thread and calls the
@@ -453,7 +453,7 @@
another thread needs to be placed in the reimplemented QRunnable::run()
method.
- \snippet tutorials/threads/hellothreadpool/hellothreadpool.cpp 1
+ \snippet ../widgets/tutorials/threads/hellothreadpool/hellothreadpool.cpp 1
We instantiate Work in main(), locate the global thread pool and use the
QThreadPool::start() method. Now the thread pool runs our worker in another
@@ -463,7 +463,7 @@
\section2 Example 2: Using QtConcurrent
- \snippet tutorials/threads/helloconcurrent/helloconcurrent.cpp 1
+ \snippet ../widgets/tutorials/threads/helloconcurrent/helloconcurrent.cpp 1
We write a global function hello() to implement the work. QtConcurrent::run()
is used to run the function in another thread. The result is a QFuture.
@@ -499,17 +499,17 @@
Communication from the GUI to the worker thread is shown in the next
example.
- \snippet tutorials/threads/clock/main.cpp 1
+ \snippet ../widgets/tutorials/threads/clock/main.cpp 1
We've connected the \c clockThread with the label. The connection must be a
queued signal-slot connection because we want to put the call in the event
loop.
- \snippet tutorials/threads/clock/clockthread.h 1
+ \snippet ../widgets/tutorials/threads/clock/clockthread.h 1
We have derived a class from QThread and declared the \c sendTime() signal.
- \snippet tutorials/threads/clock/clockthread.cpp 1
+ \snippet ../widgets/tutorials/threads/clock/clockthread.cpp 1
The trickiest part of this example is that the timer is connected to its
slot via a direct connection. A default connection would produce a queued
@@ -541,7 +541,7 @@
The \c Thread class's code is short but somewhat involved, so we only show
how to use the class.
- \snippet tutorials/threads/movedobject/main.cpp 1
+ \snippet ../widgets/tutorials/threads/movedobject/main.cpp 1
QMetaObject::invokeMethod() calls a slot via the event loop. The worker
object's methods should not be called directly after the object has been
diff --git a/src/corelib/doc/src/threads.qdoc b/src/corelib/doc/src/threads.qdoc
index 9b8fe527d2..bcabfc3c8c 100644
--- a/src/corelib/doc/src/threads.qdoc
+++ b/src/corelib/doc/src/threads.qdoc
@@ -74,10 +74,10 @@
to threading see our Recommended Reading list:
\list
- \li \l{Threads Primer: A Guide to Multithreaded Programming}
- \li \l{Thread Time: The Multithreaded Programming Guide}
- \li \l{Pthreads Programming: A POSIX Standard for Better Multiprocessing}
- \li \l{Win32 Multithreaded Programming}
+ \li \l {http://www.amazon.com/Threads-Primer-Guide-Multithreaded-Programming/dp/0134436989}{Threads Primer: A Guide to Multithreaded Programming}
+ \li \l {http://www.amazon.com/Thread-Time-MultiThreaded-Programming-Guide/dp/0131900676}{Thread Time: The Multithreaded Programming Guide}
+ \li \l {http://www.amazon.com/Pthreads-Programming-Standard-Multiprocessing-Nutshell/dp/1565921151a}{Pthreads Programming: A POSIX Standard for Better Multiprocessing}
+ \li \l {http://www.amazon.com/WIN32-Multithreaded-Programming-Aaron-Cohen/dp/1565922964}{Win32 Multithreaded Programming}
\endlist
\section1 The Threading Classes
diff --git a/src/corelib/doc/src/timers.qdoc b/src/corelib/doc/src/timers.qdoc
new file mode 100644
index 0000000000..eddb600559
--- /dev/null
+++ b/src/corelib/doc/src/timers.qdoc
@@ -0,0 +1,123 @@
+/****************************************************************************
+**
+** 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 timers.html
+ \title Timers
+ \brief How to use Qt timers in your application.
+
+ \ingroup best-practices
+
+ QObject, the base class of all Qt objects, provides the basic
+ timer support in Qt. With QObject::startTimer(), you start a
+ timer with an interval in milliseconds as argument. The function
+ returns a unique integer timer ID. The timer will now fire at
+ regular intervals until you explicitly call QObject::killTimer()
+ with the timer ID.
+
+ For this mechanism to work, the application must run in an event
+ loop. You start an event loop with QApplication::exec(). When a
+ timer fires, the application sends a QTimerEvent, and the flow of
+ control leaves the event loop until the timer event is processed.
+ This implies that a timer cannot fire while your application is
+ busy doing something else. In other words: the accuracy of timers
+ depends on the granularity of your application.
+
+ In multithreaded applications, you can use the timer mechanism in
+ any thread that has an event loop. To start an event loop from a
+ non-GUI thread, use QThread::exec(). Qt uses the object's
+ \l{QObject::thread()}{thread affinity} to determine which thread
+ will deliver the QTimerEvent. Because of this, you must start and
+ stop all timers in the object's thread; it is not possible to
+ start timers for objects in another thread.
+
+ The upper limit for the interval value is determined by the number
+ of milliseconds that can be specified in a signed integer
+ (in practice, this is a period of just over 24 days). The accuracy
+ depends on the underlying operating system. Windows 2000 has 15
+ millisecond accuracy; other systems that we have tested can handle
+ 1 millisecond intervals.
+
+ The main API for the timer functionality is QTimer. That class
+ provides regular timers that emit a signal when the timer fires, and
+ inherits QObject so that it fits well into the ownership structure
+ of most GUI programs. The normal way of using it is like this:
+
+ \snippet timers/timers.cpp 0
+ \snippet timers/timers.cpp 1
+ \snippet timers/timers.cpp 2
+
+ The QTimer object is made into a child of this widget so that,
+ when this widget is deleted, the timer is deleted too.
+ Next, its \l{QTimer::}{timeout()} signal is connected to the slot
+ that will do the work, it is started with a value of 1000
+ milliseconds, indicating that it will time out every second.
+
+ QTimer also provides a static function for single-shot timers.
+ For example:
+
+ \snippet timers/timers.cpp 3
+
+ 200 milliseconds (0.2 seconds) after this line of code is
+ executed, the \c updateCaption() slot will be called.
+
+ For QTimer to work, you must have an event loop in your
+ application; that is, you must call QCoreApplication::exec()
+ somewhere. Timer events will be delivered only while the event
+ loop is running.
+
+ In multithreaded applications, you can use QTimer in any thread
+ that has an event loop. To start an event loop from a non-GUI
+ thread, use QThread::exec(). Qt uses the timer's
+ \l{QObject::thread()}{thread affinity} to determine which thread
+ will emit the \l{QTimer::}{timeout()} signal. Because of this, you
+ must start and stop the timer in its thread; it is not possible to
+ start a timer from another thread.
+
+ The \l{widgets/analogclock}{Analog Clock} example shows how to use
+ QTimer to redraw a widget at regular intervals. From \c{AnalogClock}'s
+ implementation:
+
+ \snippet analogclock.cpp 0
+ \snippet analogclock.cpp 2
+ \snippet analogclock.cpp 3
+ \snippet analogclock.cpp 4
+ \snippet analogclock.cpp 5
+ \snippet analogclock.cpp 6
+ \dots
+ \snippet analogclock.cpp 7
+
+ Every second, QTimer will call the QWidget::update() slot to
+ refresh the clock's display.
+
+ If you already have a QObject subclass and want an easy
+ optimization, you can use QBasicTimer instead of QTimer. With
+ QBasicTimer, you must reimplement
+ \l{QObject::timerEvent()}{timerEvent()} in your QObject subclass
+ and handle the timeout there. The \l{widgets/wiggly}{Wiggly}
+ example shows how to use QBasicTimer.
+*/
generated by cgit v1.2.3 (git 2.25.1) at 2024-06-04 19:57:28 +0000