Move examples to proper location.

Change-Id: Ib808f5d99cb8217f8786411b531fa5bc7fa5250a
Reviewed-by: Martin Smith <martin.smith@digia.com>

36 files changed, 2500 insertions, 26 deletions

diff --git a/examples/tools/doc/completer-example-country.png b/examples/tools/doc/completer-example-country.png
new file mode 100644
index 0000000000..fa7c8a9938
--- /dev/null
+++ b/examples/tools/doc/completer-example-country.png
diff --git a/examples/tools/doc/completer-example-word.png b/examples/tools/doc/completer-example-word.png
new file mode 100644
index 0000000000..aa3fb9c333
--- /dev/null
+++ b/examples/tools/doc/completer-example-word.png
diff --git a/examples/tools/doc/completer-example.png b/examples/tools/doc/completer-example.png
new file mode 100644
index 0000000000..dcaa253bd8
--- /dev/null
+++ b/examples/tools/doc/completer-example.png
diff --git a/examples/tools/doc/completer.qdoc b/examples/tools/doc/completer.qdoc
new file mode 100644
index 0000000000..2fabb4d852
--- /dev/null
+++ b/examples/tools/doc/completer.qdoc
@@ -0,0 +1,249 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \example completer
+    \title Completer Example
+
+    The Completer example shows how to provide string-completion facilities
+    for an input widget based on data provided by a model.
+
+    \image completer-example.png
+
+    This example uses a custom item model, \c FileSystemModel, and a QCompleter object.
+    QCompleter is a class that provides completions based on an item model. The
+    type of model, the completion mode, and the case sensitivity can be
+    selected using combo boxes.
+
+    \section1 The Resource File
+
+    The Completer example requires a resource file in order to store the
+    \e{countries.txt} and \e{words.txt}. The resource file contains the
+    following code:
+
+    \quotefile completer/completer.qrc
+
+    \section1 FileSystemModel Class Definition
+
+    The \c FileSystemModel class is a subclass of QFileSystemModel, which provides a data
+    model for the local filesystem.
+
+    \snippet completer/fsmodel.h 0
+
+    This class only has a constructor and a \c data() function as it is only
+    created to enable \c data() to return the entire file path for the
+    display role, unlike \l{QFileSystemModel}'s \c data() function that only returns
+    the folder and not the drive label. This is further explained in
+    \c FileSystemModel's implementation.
+
+    \section1 FileSystemModel Class Implementation
+
+    The constructor for the \c FileSystemModel class is used to pass \a parent to
+    QFileSystemModel.
+
+    \snippet completer/fsmodel.cpp 0
+
+    As mentioned earlier, the \c data() function is reimplemented in order to
+    get it to return the entire file parth for the display role. For example,
+    with a QFileSystemModel, you will see "Program Files" in the view. However, with
+    \c FileSystemModel, you will see "C:\\Program Files".
+
+    \snippet completer/fsmodel.cpp 1
+
+    The screenshots below illustrate this difference:
+
+    \table
+    \row \li \inlineimage completer-example-qdirmodel.png
+         \li \inlineimage completer-example-dirmodel.png
+    \endtable
+
+    The Qt::EditRole, which QCompleter uses to look for matches, is left
+    unchanged.
+
+    \section1 MainWindow Class Definition
+
+    The \c MainWindow class is a subclass of QMainWindow and implements five
+    private slots - \c about(), \c changeCase(), \c changeMode(), \c changeModel(),
+    and \c changeMaxVisible().
+
+    \snippet completer/mainwindow.h 0
+
+    Within the \c MainWindow class, we have two private functions:
+    \c createMenu() and \c modelFromFile(). We also declare the private widgets
+    needed - three QComboBox objects, a QCheckBox, a QCompleter, a QLabel, and
+    a QLineEdit.
+
+    \snippet completer/mainwindow.h 1
+
+    \section1 MainWindow Class Implementation
+
+    The constructor of \c MainWindow constructs a \c MainWindow with a parent
+    widget and initializes the private members. The \c createMenu() function
+    is then invoked.
+
+    We set up three QComboBox objects, \c modelComb, \c modeCombo and
+    \c caseCombo. By default, the \c modelCombo is set to QFileSystemModel,
+    the \c modeCombo is set to "Filtered Popup" and the \c caseCombo is set
+    to "Case Insensitive".
+
+    \snippet completer/mainwindow.cpp 0
+
+    The \c maxVisibleSpinBox is created and determines the number of visible
+    item in the completer
+
+    The \c wrapCheckBox is then set up. This \c checkBox determines if the
+    \c{completer}'s \l{QCompleter::setWrapAround()}{setWrapAround()} property
+    is enabled or disabled.
+
+    \snippet completer/mainwindow.cpp 1
+
+    We instantiate \c contentsLabel and set its size policy to
+    \l{QSizePolicy::Fixed}{fixed}. The combo boxes' \l{QComboBox::activated()}
+    {activated()} signals are then connected to their respective slots.
+
+    \snippet completer/mainwindow.cpp 2
+
+    The \c lineEdit is set up and then we arrange all the widgets using a
+    QGridLayout. The \c changeModel() function is called, to initialize the
+    \c completer.
+
+    \snippet completer/mainwindow.cpp 3
+
+    The \c createMenu() function is used to instantiate the QAction objects
+    needed to fill the \c fileMenu and \c helpMenu. The actions'
+    \l{QAction::triggered()}{triggered()} signals are connected to their
+    respective slots.
+
+    \snippet completer/mainwindow.cpp 4
+
+    The \c modelFromFile() function accepts the \a fileName of a file and
+    processes it depending on its contents.
+
+    We first validate the \c file to ensure that it can be opened in
+    QFile::ReadOnly mode. If this is unsuccessful, the function returns an
+    empty QStringListModel.
+
+    \snippet completer/mainwindow.cpp 5
+
+    The mouse cursor is then overridden with Qt::WaitCursor before we fill
+    a QStringList object, \c words, with the contents of \c file. Once this
+    is done, we restore the mouse cursor.
+
+    \snippet completer/mainwindow.cpp 6
+
+    As mentioned earlier, the resources file contains two files -
+    \e{countries.txt} and \e{words.txt}. If the \c file read is \e{words.txt},
+    we return a QStringListModel with \c words as its QStringList and
+    \c completer as its parent.
+
+    \snippet completer/mainwindow.cpp 7
+
+    If the \c file read is \e{countries.txt}, then we require a
+    QStandardItemModel with \c words.count() rows, 2 columns, and \c completer
+    as its parent.
+
+    \snippet completer/mainwindow.cpp 8
+
+    A standard line in \e{countries.txt} is:
+    \quotation
+        Norway                          NO
+    \endquotation
+
+    Hence, to populate the QStandardItemModel object, \c m, we have to
+    split the country name and its symbol. Once this is done, we return
+    \c m.
+
+    \snippet completer/mainwindow.cpp 9
+
+    The \c changeMode() function sets the \c{completer}'s mode, depending on
+    the value of \c index.
+
+    \snippet completer/mainwindow.cpp 10
+
+    The \c changeModel() function changes the item model used based on the
+    model selected by the user.
+
+    A \c switch statement is used to change the item model based on the index
+    of \c modelCombo. If \c case is 0, we use an unsorted QFileSystemModel, providing
+    us with a file path excluding the drive label.
+
+    \snippet completer/mainwindow.cpp 11
+
+    Note that we create the model with \c completer as the parent as this
+    allows us to replace the model with a new model. The \c completer will
+    ensure that the old one is deleted the moment a new model is assigned
+    to it.
+
+    If \c case is 1, we use the \c DirModel we defined earlier, resulting in
+    full paths for the files.
+
+    \snippet completer/mainwindow.cpp 12
+
+    When \c case is 2, we attempt to complete names of countries. This requires
+    a QTreeView object, \c treeView. The country names are extracted from
+    \e{countries.txt} and set the popup used to display completions to
+    \c treeView.
+
+    \snippet completer/mainwindow.cpp 13
+
+    The screenshot below shows the Completer with the country list model.
+
+    \image completer-example-country.png
+
+    If \c case is 3, we attempt to complete words. This is done using a
+    QStringListModel that contains data extracted from \e{words.txt}. The
+    model is sorted \l{QCompleter::CaseInsensitivelySortedModel}
+    {case insensitively}.
+
+    The screenshot below shows the Completer with the word list model.
+
+    \image completer-example-word.png
+
+    Once the model type is selected, we call the \c changeMode() function and
+    the \c changeCase() function and set the wrap option accordingly. The
+    \c{wrapCheckBox}'s \l{QCheckBox::clicked()}{clicked()} signal is connected
+    to the \c{completer}'s \l{QCompleter::setWrapAround()}{setWrapAround()}
+    slot.
+
+    \snippet completer/mainwindow.cpp 14
+
+    The \c changeMaxVisible() update the maximum number of visible items in
+    the completer.
+
+    \snippet completer/mainwindow.cpp 15
+
+    The \c about() function provides a brief description about the example.
+
+    \snippet completer/mainwindow.cpp 16
+
+    \section1 \c main() Function
+
+    The \c main() function instantiates QApplication and \c MainWindow and
+    invokes the \l{QWidget::show()}{show()} function.
+
+    \snippet completer/main.cpp 0
+    */
diff --git a/examples/tools/doc/contiguouscache.qdoc b/examples/tools/doc/contiguouscache.qdoc
new file mode 100644
index 0000000000..f906c7a07f
--- /dev/null
+++ b/examples/tools/doc/contiguouscache.qdoc
@@ -0,0 +1,83 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \example contiguouscache
+    \title Contiguous Cache Example
+
+    The Contiguous Cache example shows how to use QContiguousCache to manage memory usage for
+    very large models.  In some environments memory is limited and, even when it
+    isn't, users still dislike an application using excessive memory.
+    Using QContiguousCache to manage a list, rather than loading
+    the entire list into memory, allows the application to limit the amount
+    of memory it uses, regardless of the size of the data set it accesses
+
+    The simplest way to use QContiguousCache is to cache as items are requested. When
+    a view requests an item at row N it is also likely to ask for items at rows near
+    to N.
+
+    \snippet contiguouscache/randomlistmodel.cpp 0
+
+    After getting the row, the class determines if the row is in the bounds
+    of the contiguous cache's current range.  It would have been equally valid to
+    simply have the following code instead.
+
+    \code
+    while (row > m_rows.lastIndex())
+        m_rows.append(fetchWord(m_rows.lastIndex()+1);
+    while (row < m_rows.firstIndex())
+        m_rows.prepend(fetchWord(m_rows.firstIndex()-1);
+    \endcode
+
+    However a list will often jump rows if the scroll bar is used directly, resulting in
+    the code above causing every row between the old and new rows to be fetched.
+
+    Using QContiguousCache::lastIndex() and QContiguousCache::firstIndex() allows
+    the example to determine what part of the list the cache is currently caching.
+    These values don't represent the indexes into the cache's own memory, but rather
+    a virtual infinite array that the cache represents.
+
+    By using QContiguousCache::append() and QContiguousCache::prepend() the code ensures
+    that items that may be still on the screen are not lost when the requested row
+    has not moved far from the current cache range.  QContiguousCache::insert() can
+    potentially remove more than one item from the cache as QContiguousCache does not
+    allow for gaps.  If your cache needs to quickly jump back and forth between
+    rows with significant gaps between them consider using QCache instead.
+
+    And thats it.  A perfectly reasonable cache, using minimal memory for a very large
+    list.  In this case the accessor for getting the words into the cache
+    generates random information rather than fixed information.  This allows you 
+    to see how the cache range is kept for a local number of rows when running the
+    example.
+
+    \snippet contiguouscache/randomlistmodel.cpp 1
+
+    It is also worth considering pre-fetching items into the cache outside of the
+    application's paint routine.  This can be done either with a separate thread
+    or using a QTimer to incrementally expand the range of the cache prior to
+    rows being requested out of the current cache range.
+*/
diff --git a/examples/tools/doc/echoplugin.qdoc b/examples/tools/doc/echoplugin.qdoc
new file mode 100644
index 0000000000..31afa0ee0b
--- /dev/null
+++ b/examples/tools/doc/echoplugin.qdoc
@@ -0,0 +1,208 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \example echoplugin
+    \title Echo Plugin Example
+
+    This example shows how to create a Qt plugin.
+
+    \image echopluginexample.png
+
+    There are two kinds of plugins in Qt: plugins that extend Qt
+    itself and plugins that extend applications written in Qt. In this
+    example, we show the procedure of implementing plugins that extend
+    applications. When you create a plugin you declare an interface,
+    which is a class with only pure virtual functions. This interface
+    is inherited by the class that implements the plugin. The class is
+    stored in a shared library and can therefore be loaded by
+    applications at run-time. When loaded, the plugin is dynamically
+    cast to the interface using Qt's \l{Meta-Object
+    System}{meta-object system}. The plugin \l{How to Create Qt
+    Plugins}{overview document} gives a high-level introduction to
+    plugins.
+    
+    We have implemented a plugin, the \c EchoPlugin, which implements
+    the \c EchoInterface. The interface consists of \c echo(), which
+    takes a QString as argument. The \c EchoPlugin returns the string
+    unaltered (i.e., it works as the familiar echo command found in
+    both Unix and Windows).
+
+    We test the plugin in \c EchoWindow: when you push the QPushButton
+    (as seen in the image above), the application sends the text in
+    the QLineEdit to the plugin, which echoes it back to the
+    application. The answer from the plugin is displayed in the
+    QLabel.
+
+
+    \section1 EchoWindow Class Definition
+
+    The \c EchoWindow class lets us test the \c EchoPlugin through a
+    GUI.
+
+    \snippet echoplugin/echowindow/echowindow.h 0
+
+    We load the plugin in \c loadPlugin() and cast it to \c
+    EchoInterface. When the user clicks the \c button we take the 
+    text in \c lineEdit and call the interface's \c echo() with it. 
+
+
+    \section1 EchoWindow Class Implementation
+
+    We start with a look at the constructor:
+
+    \snippet echoplugin/echowindow/echowindow.cpp 0
+
+    We create the widgets and set a title for the window. We then load
+    the plugin. \c loadPlugin() returns false if the plugin could not
+    be loaded, in which case we disable the widgets. If you wish a
+    more detailed error message, you can use
+    \l{QPluginLoader::}{errorString()}; we will look more closely at
+    QPluginLoader later.
+
+    Here is the implementation of \c sendEcho():
+
+    \snippet echoplugin/echowindow/echowindow.cpp 1
+
+    This slot is called when the user pushes \c button or presses
+    enter in \c lineEdit. We call \c echo() of the echo interface. In
+    our example this is the \c EchoPlugin, but it could be any plugin
+    that inherit the \c EchoInterface. We take the QString returned
+    from \c echo() and display it in the \c label.
+
+    Here is the implementation of \c createGUI():
+
+    \snippet echoplugin/echowindow/echowindow.cpp 2
+
+    We create the widgets and lay them out in a grid layout. We
+    connect the label and line edit to our \c sendEcho() slot.
+
+    Here is the \c loadPlugin() function:
+
+    \snippet echoplugin/echowindow/echowindow.cpp 3
+
+    Access to plugins at run-time is provided by QPluginLoader. You
+    supply it with the filename of the shared library the plugin is
+    stored in and call \l{QPluginLoader::}{instance()}, which loads
+    and returns the root component of the plugin (i.e., it resolves
+    the type of the plugin and creates a QObject instance of it). If
+    the plugin was not successfully loaded, it will be null, so we
+    return false. If it was loaded correctly, we can cast the plugin
+    to our \c EchoInterface and return true. In the case that the
+    plugin loaded does not implement the \c EchoInterface, \c
+    instance() will return null, but this cannot happen in our
+    example. Notice that the location of the plugin is not the same
+    for all platforms.
+
+
+    \section1 EchoInterface Class Definition
+
+    The \c EchoInterface defines the functions that the plugin will
+    provide. An interface is a class that only consists of pure
+    virtual functions. If non virtual functions were present in the
+    class you would get misleading compile errors in the moc files.
+
+    \snippet echoplugin/echowindow/echointerface.h 0
+
+    We declare \c echo(). In our \c EchoPlugin we use this method to
+    return, or echo, \a message.
+
+    We use the Q_DECLARE_INTERFACE macro to let \l{Meta-Object
+    System}{Qt's meta object system} aware of the interface. We do
+    this so that it will be possible to identify plugins that
+    implements the interface at run-time. The second argument is a
+    string that must identify the interface in a unique way. 
+
+
+    \section1 EchoPlugin Class Definition
+
+    We inherit both QObject and \c EchoInterface to make this class a
+    plugin. The Q_INTERFACES macro tells Qt which interfaces the class
+    implements. In our case we only implement the \c EchoInterface. 
+    If a class implements more than one interface, they are given as 
+    a comma separated list.
+
+    \snippet echoplugin/plugin/echoplugin.h 0
+
+
+    \section1 EchoPlugin Class Implementation
+
+    Here is the implementation of \c echo():
+
+    \snippet echoplugin/plugin/echoplugin.cpp 0
+
+    We simply return the functions parameter. 
+
+    \snippet echoplugin/plugin/echoplugin.cpp 1
+
+    We use the Q_EXPORT_PLUGIN2 macro to let Qt know that the \c
+    EchoPlugin class is a plugin. The first parameter is the name of
+    the plugin; it is usual to give the plugin and the library file it
+    is stored in the same name.
+
+    \section1 The \c main() function
+
+    \snippet echoplugin/echowindow/main.cpp 0
+
+    We create an \c EchoWindow and display it as a top-level window.
+
+    \section1 The Profiles
+
+    When creating plugins the profiles need to be adjusted.
+    We show here what changes need to be done. 
+
+    The profile in the echoplugin directory uses the \c subdirs
+    template and simply includes includes to directories in which
+    the echo window and echo plugin lives:
+
+    \snippet echoplugin/echoplugin.pro 0
+
+    The profile for the echo window does not need any plugin specific
+    settings. We move on to the plugin profile:
+
+    \snippet echoplugin/plugin/plugin.pro 0
+
+    We need to set the TEMPLATE as we now want to make a library
+    instead of an executable. We also need to tell qmake that we are
+    creating a plugin. The \c EchoInterface that the plugin implements
+    lives in the \c echowindow directory, so we need to add that
+    directory to the include path. We set the TARGET of the project,
+    which is the name of the library file in which the plugin will be
+    stored; qmake appends the appropriate file extension depending on
+    the platform. By convention the target should have the same name
+    as the plugin (set with Q_EXPORT_PLUGIN2)
+
+    \section1 Further reading and examples
+
+    You can find an overview of the macros needed to create plugins
+    \l{Macros for Defining Plugins}{here}.
+    
+    We give an example of a plugin that extend Qt in the \l{Style
+    Plugin Example}{style plugin} example. The \l{Plug & Paint
+    Example}{plug and paint} example shows how to create static
+    plugins.
+*/
diff --git a/examples/tools/doc/echopluginexample.png b/examples/tools/doc/echopluginexample.png
new file mode 100644
index 0000000000..7cb1e4d63b
--- /dev/null
+++ b/examples/tools/doc/echopluginexample.png
diff --git a/examples/tools/doc/i18n.qdoc b/examples/tools/doc/i18n.qdoc
new file mode 100644
index 0000000000..e5c888aeda
--- /dev/null
+++ b/examples/tools/doc/i18n.qdoc
@@ -0,0 +1,37 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \example i18n
+    \title I18N Example
+
+    The Internationalization (I18N) example demonstrates Qt's support for translated
+    text. Developers can write the initial application text in one language, and
+    translations can be provided later without any modifications to the code.
+
+    \image i18n-example.png
+*/
diff --git a/examples/tools/doc/plugandpaint-plugindialog.png b/examples/tools/doc/plugandpaint-plugindialog.png
new file mode 100644
index 0000000000..4b601bd58b
--- /dev/null
+++ b/examples/tools/doc/plugandpaint-plugindialog.png
diff --git a/examples/tools/doc/plugandpaint.png b/examples/tools/doc/plugandpaint.png
new file mode 100644
index 0000000000..bd5d001f91
--- /dev/null
+++ b/examples/tools/doc/plugandpaint.png
diff --git a/examples/tools/doc/plugandpaint.qdoc b/examples/tools/doc/plugandpaint.qdoc
new file mode 100644
index 0000000000..bf9f1d12f2
--- /dev/null
+++ b/examples/tools/doc/plugandpaint.qdoc
@@ -0,0 +1,540 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \example plugandpaint
+    \title Plug & Paint Example
+
+    The Plug & Paint example demonstrates how to write Qt
+    applications that can be extended through plugins.
+
+    \image plugandpaint.png Screenshot of the Plug & Paint example
+
+    A plugin is a dynamic library that can be loaded at run-time to
+    extend an application. Qt makes it possible to create custom
+    plugins and to load them using QPluginLoader. To ensure that
+    plugins don't get lost, it is also possible to link them
+    statically to the executable. The Plug & Paint example uses
+    plugins to support custom brushes, shapes, and image filters. A
+    single plugin can provide multiple brushes, shapes, and/or
+    filters.
+
+    If you want to learn how to make your own application extensible
+    through plugins, we recommend that you start by reading this
+    overview, which explains how to make an application use plugins.
+    Afterward, you can read the
+    \l{plugandpaintplugins/basictools}{Basic Tools} and
+    \l{plugandpaintplugins/extrafilters}{Extra Filters}
+    overviews, which show how to implement static and dynamic
+    plugins, respectively.
+
+    Plug & Paint consists of the following classes:
+
+    \list
+    \li \c MainWindow is a QMainWindow subclass that provides the menu
+       system and that contains a \c PaintArea as the central widget.
+    \li \c PaintArea is a QWidget that allows the user to draw using a
+       brush and to insert shapes.
+    \li \c PluginDialog is a dialog that shows information about the
+       plugins detected by the application.
+    \li \c BrushInterface, \c ShapeInterface, and \c FilterInterface are
+       abstract base classes that can be implemented by plugins to
+       provide custom brushes, shapes, and image filters.
+    \endlist
+
+    \section1 The Plugin Interfaces
+
+    We will start by reviewing the interfaces defined in \c
+    interfaces.h. These interfaces are used by the Plug & Paint
+    application to access extra functionality. They are implemented
+    in the plugins.
+
+
+    \snippet plugandpaint/interfaces.h 0
+
+    The \c BrushInterface class declares four pure virtual functions.
+    The first pure virtual function, \c brushes(), returns a list of
+    strings that identify the brushes provided by the plugin. By
+    returning a QStringList instead of a QString, we make it possible
+    for a single plugin to provide multiple brushes. The other
+    functions have a \c brush parameter to identify which brush
+    (among those returned by \c brushes()) is used.
+
+    \c mousePress(), \c mouseMove(), and \c mouseRelease() take a
+    QPainter and one or two \l{QPoint}s, and return a QRect
+    identifying which portion of the image was altered by the brush.
+
+    The class also has a virtual destructor. Interface classes
+    usually don't need such a destructor (because it would make
+    little sense to \c delete the object that implements the
+    interface through a pointer to the interface), but some compilers
+    emit a warning for classes that declare virtual functions but no
+    virtual destructor. We provide the destructor to keep these
+    compilers happy.
+
+    \snippet plugandpaint/interfaces.h 1
+
+    The \c ShapeInterface class declares a \c shapes() function that
+    works the same as \c{BrushInterface}'s \c brushes() function, and
+    a \c generateShape() function that has a \c shape parameter.
+    Shapes are represented by a QPainterPath, a data type that can
+    represent arbitrary 2D shapes or combinations of shapes. The \c
+    parent parameter can be used by the plugin to pop up a dialog
+    asking the user to specify more information.
+
+    \snippet plugandpaint/interfaces.h 2
+
+    The \c FilterInterface class declares a \c filters() function
+    that returns a list of filter names, and a \c filterImage()
+    function that applies a filter to an image.
+
+    \snippet plugandpaint/interfaces.h 4
+
+    To make it possible to query at run-time whether a plugin
+    implements a given interface, we must use the \c
+    Q_DECLARE_INTERFACE() macro. The first argument is the name of
+    the interface. The second argument is a string identifying the
+    interface in a unique way. By convention, we use a "Java package
+    name" syntax to identify interfaces. If we later change the
+    interfaces, we must use a different string to identify the new
+    interface; otherwise, the application might crash. It is therefore
+    a good idea to include a version number in the string, as we did
+    above.
+
+    The \l{plugandpaintplugins/basictools}{Basic Tools} plugin
+    and the \l{plugandpaintplugins/extrafilters}{Extra Filters}
+    plugin shows how to derive from \c BrushInterface, \c
+    ShapeInterface, and \c FilterInterface.
+
+    A note on naming: It might have been tempting to give the \c
+    brushes(), \c shapes(), and \c filters() functions a more generic
+    name, such as \c keys() or \c features(). However, that would
+    have made multiple inheritance impractical. When creating
+    interfaces, we should always try to give unique names to the pure
+    virtual functions.
+
+    \section1 The MainWindow Class
+
+    The \c MainWindow class is a standard QMainWindow subclass, as
+    found in many of the other examples (e.g.,
+    \l{mainwindows/application}{Application}). Here, we'll
+    concentrate on the parts of the code that are related to plugins.
+
+    \snippet plugandpaint/mainwindow.cpp 4
+
+    The \c loadPlugins() function is called from the \c MainWindow
+    constructor to detect plugins and update the \uicontrol{Brush},
+    \uicontrol{Shapes}, and \uicontrol{Filters} menus. We start by handling static
+    plugins (available through QPluginLoader::staticInstances())
+
+    To the application that uses the plugin, a Qt plugin is simply a
+    QObject. That QObject implements plugin interfaces using multiple
+    inheritance.
+
+    \snippet plugandpaint/mainwindow.cpp 5
+
+    The next step is to load dynamic plugins. We initialize the \c
+    pluginsDir member variable to refer to the \c plugins
+    subdirectory of the Plug & Paint example. On Unix, this is just a
+    matter of initializing the QDir variable with
+    QApplication::applicationDirPath(), the path of the executable
+    file, and to do a \l{QDir::cd()}{cd()}. On Windows and Mac OS X,
+    this file is usually located in a subdirectory, so we need to
+    take this into account.
+
+    \snippet plugandpaint/mainwindow.cpp 6
+    \snippet plugandpaint/mainwindow.cpp 7
+    \snippet plugandpaint/mainwindow.cpp 8
+
+    We use QDir::entryList() to get a list of all files in that
+    directory. Then we iterate over the result using \l foreach and
+    try to load the plugin using QPluginLoader.
+
+    The QObject provided by the plugin is accessible through
+    QPluginLoader::instance(). If the dynamic library isn't a Qt
+    plugin, or if it was compiled against an incompatible version of
+    the Qt library, QPluginLoader::instance() returns a null pointer.
+
+    If QPluginLoader::instance() is non-null, we add it to the menus.
+
+    \snippet plugandpaint/mainwindow.cpp 9
+
+    At the end, we enable or disable the \uicontrol{Brush}, \uicontrol{Shapes},
+    and \uicontrol{Filters} menus based on whether they contain any items.
+
+    \snippet plugandpaint/mainwindow.cpp 10
+
+    For each plugin (static or dynamic), we check which interfaces it
+    implements using \l qobject_cast(). First, we try to cast the
+    plugin instance to a \c BrushInterface; if it works, we call the
+    private function \c addToMenu() with the list of brushes returned
+    by \c brushes(). Then we do the same with the \c ShapeInterface
+    and the \c FilterInterface.
+
+    \snippet plugandpaint/mainwindow.cpp 3
+
+    The \c aboutPlugins() slot is called on startup and can be
+    invoked at any time through the \uicontrol{About Plugins} action. It
+    pops up a \c PluginDialog, providing information about the loaded
+    plugins.
+
+    \image plugandpaint-plugindialog.png Screenshot of the Plugin dialog
+
+
+    The \c addToMenu() function is called from \c loadPlugin() to
+    create \l{QAction}s for custom brushes, shapes, or filters and
+    add them to the relevant menu. The QAction is created with the
+    plugin from which it comes from as the parent; this makes it
+    convenient to get access to the plugin later.
+
+    \snippet plugandpaint/mainwindow.cpp 0
+
+    The \c changeBrush() slot is invoked when the user chooses one of
+    the brushes from the \uicontrol{Brush} menu. We start by finding out
+    which action invoked the slot using QObject::sender(). Then we
+    get the \c BrushInterface out of the plugin (which we
+    conveniently passed as the QAction's parent) and we call \c
+    PaintArea::setBrush() with the \c BrushInterface and the string
+    identifying the brush. Next time the user draws on the paint
+    area, \c PaintArea will use this brush.
+
+    \snippet plugandpaint/mainwindow.cpp 1
+
+    The \c insertShape() is invoked when the use chooses one of the
+    shapes from the \uicontrol{Shapes} menu. We retrieve the QAction that
+    invoked the slot, then the \c ShapeInterface associated with that
+    QAction, and finally we call \c ShapeInterface::generateShape()
+    to obtain a QPainterPath.
+
+    \snippet plugandpaint/mainwindow.cpp 2
+
+    The \c applyFilter() slot is similar: We retrieve the QAction
+    that invoked the slot, then the \c FilterInterface associated to
+    that QAction, and finally we call \c
+    FilterInterface::filterImage() to apply the filter onto the
+    current image.
+
+    \section1 The PaintArea Class
+
+    The \c PaintArea class contains some code that deals with \c
+    BrushInterface, so we'll review it briefly.
+
+    \snippet plugandpaint/paintarea.cpp 0
+
+    In \c setBrush(), we simply store the \c BrushInterface and the
+    brush that are given to us by \c MainWindow.
+
+    \snippet plugandpaint/paintarea.cpp 1
+
+    In the \l{QWidget::mouseMoveEvent()}{mouse move event handler},
+    we call the \c BrushInterface::mouseMove() function on the
+    current \c BrushInterface, with the current brush. The mouse
+    press and mouse release handlers are very similar.
+
+    \section1 The PluginDialog Class
+
+    The \c PluginDialog class provides information about the loaded
+    plugins to the user. Its constructor takes a path to the plugins
+    and a list of plugin file names. It calls \c findPlugins()
+    to fill the QTreeWdiget with information about the plugins:
+
+    \snippet plugandpaint/plugindialog.cpp 0
+
+    The \c findPlugins() is very similar to \c
+    MainWindow::loadPlugins(). It uses QPluginLoader to access the
+    static and dynamic plugins. Its helper function \c
+    populateTreeWidget() uses \l qobject_cast() to find out which
+    interfaces are implemented by the plugins:
+
+    \snippet plugandpaint/plugindialog.cpp 1
+
+    \section1 Importing Static Plugins
+
+    The \l{plugandpaintplugins/basictools}{Basic Tools} plugin
+    is built as a static plugin, to ensure that it is always
+    available to the application. This requires using the
+    Q_IMPORT_PLUGIN() macro somewhere in the application (in a \c
+    .cpp file) and specifying the plugin in the \c .pro file.
+
+    For Plug & Paint, we have chosen to put Q_IMPORT_PLUGIN() in \c
+    main.cpp:
+
+    \snippet plugandpaint/main.cpp 0
+
+    The argument to Q_IMPORT_PLUGIN() is the plugin's name, as
+    specified with Q_EXPORT_PLUGIN2() in the \l{Exporting the
+    Plugin}{plugin}.
+
+    In the \c .pro file, we need to specify the static library.
+    Here's the project file for building Plug & Paint:
+
+    \snippet plugandpaint/plugandpaint.pro 0
+
+    The \c LIBS line variable specifies the library \c pnp_basictools
+    located in the \c ../plugandpaintplugins/basictools directory.
+    (Although the \c LIBS syntax has a distinct Unix flavor, \c qmake
+    supports it on all platforms.)
+
+    The \c CONFIG() code at the end is necessary for this example
+    because the example is part of the Qt distribution and Qt can be
+    configured to be built simultaneously in debug and in release
+    modes. You don't need to for your own plugin applications.
+
+    This completes our review of the Plug & Paint application. At
+    this point, you might want to take a look at the
+    \l{plugandpaintplugins/basictools}{Basic Tools} example
+    plugin.
+*/
+
+/*!
+    \example plugandpaintplugins/basictools
+    \title Plug & Paint Basic Tools Example
+
+    The Basic Tools example is a static plugin for the
+    \l{plugandpaint}{Plug & Paint} example. It provides a set
+    of basic brushes, shapes, and filters. Through the Basic Tools
+    example, we will review the four steps involved in writing a Qt
+    plugin:
+
+    \list 1
+    \li Declare a plugin class.
+    \li Implement the interfaces provided by the plugin.
+    \li Export the plugin using the Q_EXPORT_PLUGIN2() macro.
+    \li Build the plugin using an adequate \c .pro file.
+    \endlist
+
+    \section1 Declaration of the Plugin Class
+
+    \snippet plugandpaintplugins/basicbasictoolsplugin.h 0
+
+    We start by including \c interfaces.h, which defines the plugin
+    interfaces for the \l{plugandpaint}{Plug & Paint}
+    application. For the \c #include to work, we need to add an \c
+    INCLUDEPATH entry to the \c .pro file with the path to Qt's \c
+    examples/tools directory.
+
+    The \c BasicToolsPlugin class is a QObject subclass that
+    implements the \c BrushInterface, the \c ShapeInterface, and the
+    \c FilterInterface. This is done through multiple inheritance.
+    The \c Q_INTERFACES() macro is necessary to tell \l{moc}, Qt's
+    meta-object compiler, that the base classes are plugin
+    interfaces. Without the \c Q_INTERFACES() macro, we couldn't use
+    \l qobject_cast() in the \l{plugandpaint}{Plug & Paint}
+    application to detect interfaces.
+
+    \snippet plugandpaintplugins/basicbasictoolsplugin.h 2
+
+    In the \c public section of the class, we declare all the
+    functions from the three interfaces.
+
+    \section1 Implementation of the Brush Interface
+
+    Let's now review the implementation of the \c BasicToolsPlugin
+    member functions inherited from \c BrushInterface.
+
+    \snippet plugandpaintplugins/basicbasictoolsplugin.cpp 0
+
+    The \c brushes() function returns a list of brushes provided by
+    this plugin. We provide three brushes: \uicontrol{Pencil}, \uicontrol{Air
+    Brush}, and \uicontrol{Random Letters}.
+
+    \snippet plugandpaintplugins/basicbasictoolsplugin.cpp 1
+
+    On a mouse press event, we just call \c mouseMove() to draw the
+    spot where the event occurred.
+
+    \snippet plugandpaintplugins/basicbasictoolsplugin.cpp 2
+
+    In \c mouseMove(), we start by saving the state of the QPainter
+    and we compute a few variables that we'll need later.
+
+    \snippet plugandpaintplugins/basicbasictoolsplugin.cpp 3
+
+    Then comes the brush-dependent part of the code:
+
+    \list
+    \li If the brush is \uicontrol{Pencil}, we just call
+       QPainter::drawLine() with the current QPen.
+
+    \li If the brush is \uicontrol{Air Brush}, we start by setting the
+       painter's QBrush to Qt::Dense6Pattern to obtain a dotted
+       pattern. Then we draw a circle filled with that QBrush several
+       times, resulting in a thick line.
+
+    \li If the brush is \uicontrol{Random Letters}, we draw a random letter
+       at the new cursor position. Most of the code is for setting
+       the font to be bold and larger than the default font and for
+       computing an appropriate bounding rect.
+    \endlist
+
+    At the end, we restore the painter state to what it was upon
+    entering the function and we return the bounding rectangle.
+
+    \snippet plugandpaintplugins/basicbasictoolsplugin.cpp 4
+
+    When the user releases the mouse, we do nothing and return an
+    empty QRect.
+
+    \section1 Implementation of the Shape Interface
+
+    \snippet plugandpaintplugins/basicbasictoolsplugin.cpp 5
+
+    The plugin provides three shapes: \uicontrol{Circle}, \uicontrol{Star}, and
+    \uicontrol{Text...}. The three dots after \uicontrol{Text} are there because
+    the shape pops up a dialog asking for more information. We know
+    that the shape names will end up in a menu, so we include the
+    three dots in the shape name.
+
+    A cleaner but more complicated design would have been to
+    distinguish between the internal shape name and the name used in
+    the user interface.
+
+    \snippet plugandpaintplugins/basicbasictoolsplugin.cpp 6
+
+    The \c generateShape() creates a QPainterPath for the specified
+    shape. If the shape is \uicontrol{Text}, we pop up a QInputDialog to
+    let the user enter some text.
+
+    \section1 Implementation of the Filter Interface
+
+    \snippet plugandpaintplugins/basicbasictoolsplugin.cpp 7
+
+    The plugin provides three filters: \uicontrol{Invert Pixels}, \uicontrol{Swap
+    RGB}, and \uicontrol{Grayscale}.
+
+    \snippet plugandpaintplugins/basicbasictoolsplugin.cpp 8
+
+    The \c filterImage() function takes a filter name and a QImage as
+    parameters and returns an altered QImage. The first thing we do
+    is to convert the image to a 32-bit RGB format, to ensure that
+    the algorithms will work as expected. For example,
+    QImage::invertPixels(), which is used to implement the
+    \uicontrol{Invert Pixels} filter, gives counterintuitive results for
+    8-bit images, because they invert the indices into the color
+    table instead of inverting the color table's entries.
+
+    \section1 Exporting the Plugin
+
+    Whereas applications have a \c main() function as their entry
+    point, plugins need to contain exactly one occurrence of the
+    Q_EXPORT_PLUGIN2() macro to specify which class provides the
+    plugin:
+
+    \snippet plugandpaintplugins/basicbasictoolsplugin.cpp 9
+
+    This line may appear in any \c .cpp file that is part of the
+    plugin's source code.
+
+    \section1 The .pro File
+
+    Here's the project file for building the Basic Tools plugin:
+
+    \snippet plugandpaintplugins/basicbasictools.pro 0
+
+    The \c .pro file differs from typical \c .pro files in many
+    respects. First, it starts with a \c TEMPLATE entry specifying \c
+    lib. (The default template is \c app.) It also adds \c plugin to
+    the \c CONFIG variable. This is necessary on some platforms to
+    avoid generating symbolic links with version numbers in the file
+    name, which is appropriate for most dynamic libraries but not for
+    plugins.
+
+    To make the plugin a static plugin, all that is required is to
+    specify \c static in addition to \c plugin. The
+    \l{plugandpaintplugins/extrafilters}{Extra Filters} plugin,
+    which is compiled as a dynamic plugin, doesn't specify \c static
+    in its \c .pro file.
+
+    The \c INCLUDEPATH variable sets the search paths for global
+    headers (i.e., header files included using \c{#include <...>}).
+    We add Qt's \c examples/tools directory (strictly speaking,
+    \c{examples/tools/plugandpaintplugins/basictools/../..}) to the
+    list, so that we can include \c <plugandpaint/interfaces.h>.
+
+    The \c TARGET variable specifies which name we want to give the
+    target library. We use \c pnp_ as the prefix to show that the
+    plugin is designed to work with Plug & Paint. On Unix, \c lib is
+    also prepended to that name. On all platforms, a
+    platform-specific suffix is appended (e.g., \c .dll on Windows,
+    \c .a on Linux).
+
+    The \c CONFIG() code at the end is necessary for this example
+    because the example is part of the Qt distribution and Qt can be
+    configured to be built simultaneously in debug and in release
+    modes. You don't need to for your own plugins.
+*/
+
+/*!
+    \example plugandpaintplugins/extrafilters
+    \title Plug & Paint Extra Filters Example
+
+    The Extra Filters example is a plugin for the
+    \l{plugandpaint}{Plug & Paint} example. It provides a set
+    of filters in addition to those provided by the
+    \l{plugandpaintplugins/basictools}{Basic Tools} plugin.
+
+    Since the approach is identical to
+    \l{plugandpaintplugins/basictools}{Basic Tools}, we won't
+    review the code here. The only part of interest is the
+    \c .pro file, since Extra Filters is a dynamic plugin
+    (\l{plugandpaintplugins/basictools}{Basic Tools} is
+    linked statically into the Plug & Paint executable).
+
+    Here's the project file for building the Extra Filters plugin:
+
+    \snippet plugandpaintplugins/extrafilters/extrafilters.pro 0
+
+    The \c .pro file differs from typical \c .pro files in many
+    respects. First, it starts with a \c TEMPLATE entry specifying \c
+    lib. (The default template is \c app.) It also adds \c plugin to
+    the \c CONFIG variable. This is necessary on some platforms to
+    avoid generating symbolic links with version numbers in the file
+    name, which is appropriate for most dynamic libraries but not for
+    plugins.
+
+    The \c INCLUDEPATH variable sets the search paths for global
+    headers (i.e., header files included using \c{#include <...>}).
+    We add Qt's \c examples/tools directory (strictly speaking,
+    \c{examples/tools/plugandpaintplugins/basictools/../..}) to the
+    list, so that we can include \c <plugandpaint/interfaces.h>.
+
+    The \c TARGET variable specifies which name we want to give the
+    target library. We use \c pnp_ as the prefix to show that the
+    plugin is designed to work with Plug & Paint. On Unix, \c lib is
+    also prepended to that name. On all platforms, a
+    platform-specific suffix is appended (e.g., \c .dll on Windows,
+    \c .so on Linux).
+
+    The \c DESTDIR variable specifies where we want to install the
+    plugin. We put it in Plug & Paint's \c plugins subdirectory,
+    since that's where the application looks for dynamic plugins.
+
+    The \c CONFIG() code at the end is necessary for this example
+    because the example is part of the Qt distribution and Qt can be
+    configured to be built simultaneously in debug and in release
+    modes. You don't need to for your own plugins.
+*/
diff --git a/examples/tools/doc/regexp-example.png b/examples/tools/doc/regexp-example.png
new file mode 100644
index 0000000000..0f31a2f93f
--- /dev/null
+++ b/examples/tools/doc/regexp-example.png
diff --git a/examples/tools/doc/regexp.qdoc b/examples/tools/doc/regexp.qdoc
new file mode 100644
index 0000000000..cef89fd7e3
--- /dev/null
+++ b/examples/tools/doc/regexp.qdoc
@@ -0,0 +1,37 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** 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$
+**
+****************************************************************************/
+
+/*! 
+    \example regexp
+    \title Regular Expressions Example
+
+    The Regular Expressions (RegExp) example shows how regular expressions in Qt are
+    applied to text by providing an environment in which new regular expressions can be
+    created and tested on custom text strings.
+
+    \image regexp-example.png
+*/
diff --git a/examples/tools/doc/settingseditor-example.png b/examples/tools/doc/settingseditor-example.png
new file mode 100644
index 0000000000..7a5be05fd0
--- /dev/null
+++ b/examples/tools/doc/settingseditor-example.png
diff --git a/examples/tools/doc/settingseditor.qdoc b/examples/tools/doc/settingseditor.qdoc
new file mode 100644
index 0000000000..a141df6e06
--- /dev/null
+++ b/examples/tools/doc/settingseditor.qdoc
@@ -0,0 +1,37 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** 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$
+**
+****************************************************************************/
+
+/*! 
+    \example settingseditor
+    \title Settings Editor Example
+
+    The Settings Editor example shows how Qt's standard settings support is used in an
+    application by providing an editor that enables the user to view the settings for
+    installed applications, and modify those that can be edited.
+
+    \image settingseditor-example.png
+*/
diff --git a/examples/tools/doc/src/customcompleter.qdoc b/examples/tools/doc/src/customcompleter.qdoc
index 98a95e47a4..7cf00a275b 100644
--- a/examples/tools/doc/src/customcompleter.qdoc
+++ b/examples/tools/doc/src/customcompleter.qdoc
@@ -43,7 +43,7 @@
     that has a list of words to help QCompleter complete words. This file
     contains the following:
 
-    \quotefile examples/tools/customcompleter/customcompleter.qrc
+    \quotefile customcompleter/customcompleter.qrc
 
     \section1 TextEdit Class Definition
 
@@ -54,7 +54,7 @@
     contains a private function \c textUnderCursor() and a private instance
     of QCompleter, \c c.
 
-    \snippet examples/tools/customcompleter/textedit.h 0
+    \snippet customcompleter/textedit.h 0
 
     \section1 TextEdit Class Implementation
 
@@ -63,11 +63,11 @@
     the \c TextEdit object, using the
     \l{QTextEdit::setPlainText()}{setPlainText()} function.
 
-    \snippet examples/tools/customcompleter/textedit.cpp 0
+    \snippet customcompleter/textedit.cpp 0
 
     In addition, \c TextEdit also includes a default destructor:
 
-    \snippet examples/tools/customcompleter/textedit.cpp 1
+    \snippet customcompleter/textedit.cpp 1
 
     The \c setCompleter() function accepts a \a completer and sets it up.
     We use \c{if (c)} to check if \c c has been initialized. If it has been
@@ -75,7 +75,7 @@
     the signal from the slot. This is to ensure that no previous completer
     object is still connected to the slot.
 
-    \snippet examples/tools/customcompleter/textedit.cpp 2
+    \snippet customcompleter/textedit.cpp 2
 
     We then instantiate \c c with \a completer and set it as \c{TextEdit}'s
     widget. The completion mode and case sensitivity are also set and then
@@ -84,7 +84,7 @@
 
     The \c completer() function is a getter function that returns \c c.
 
-    \snippet examples/tools/customcompleter/textedit.cpp 3
+    \snippet customcompleter/textedit.cpp 3
 
     The completer pops up the options available, based on the contents of
     \e wordlist.txt, but the text cursor is responsible for filling in the
@@ -99,7 +99,7 @@
     completer's widget is \c TextEdit before using \c tc to insert the extra
     characters to complete the word.
 
-    \snippet examples/tools/customcompleter/textedit.cpp 4
+    \snippet customcompleter/textedit.cpp 4
 
     The figure below illustrates this process:
 
@@ -116,13 +116,13 @@
     The \c textUnderCursor() function uses a QTextCursor, \c tc, to select a
     word under the cursor and return it.
 
-    \snippet examples/tools/customcompleter/textedit.cpp 5
+    \snippet customcompleter/textedit.cpp 5
 
     The \c TextEdit class reimplements \l{QWidget::focusInEvent()}
     {focusInEvent()} function, which is an event handler used to receive
     keyboard focus events for the widget.
 
-    \snippet examples/tools/customcompleter/textedit.cpp 6
+    \snippet customcompleter/textedit.cpp 6
 
     The \l{QAbstractScrollArea::keyPressEvent()}{keyPressEvent()} is
     reimplemented to ignore key events like Qt::Key_Enter, Qt::Key_Return,
@@ -131,12 +131,12 @@
 
     If there is an active completer, we cannot process the shortcut, Ctrl+E.
 
-    \snippet examples/tools/customcompleter/textedit.cpp 7
+    \snippet customcompleter/textedit.cpp 7
 
     We also handle other modifiers and shortcuts for which we do not want the
     completer to respond to.
 
-    \snippet examples/tools/customcompleter/textedit.cpp 8
+    \snippet customcompleter/textedit.cpp 8
 
     Finally, we pop up the completer.
 
@@ -147,7 +147,7 @@
     \c createMenu() and \c modelFromFile() as well as private instances of
     QCompleter and \c TextEdit.
 
-    \snippet examples/tools/customcompleter/mainwindow.h 0
+    \snippet customcompleter/mainwindow.h 0
 
     \section1 MainWindow Class Implementation
 
@@ -157,31 +157,31 @@
     to populate the \c completer. The \c{MainWindow}'s central widget is set
     to \c TextEdit and its size is set to 500 x 300.
 
-    \snippet examples/tools/customcompleter/mainwindow.cpp 0
+    \snippet customcompleter/mainwindow.cpp 0
 
     The \c createMenu() function creates the necessary QAction objects needed
     for the "File" and "Help" menu and their \l{QAction::triggered()}
     {triggered()} signals are connected to the \c quit(), \c about(), and
     \c aboutQt() slots respectively.
 
-    \snippet examples/tools/customcompleter/mainwindow.cpp 1
+    \snippet customcompleter/mainwindow.cpp 1
 
     The \c modelFromFile() function accepts a \a fileName and attempts to
     extract the contents of this file into a QStringListModel. We display the
     Qt::WaitCursor when we are populating the QStringList, \c words, and
     restore the mouse cursor when we are done.
 
-    \snippet examples/tools/customcompleter/mainwindow.cpp 2
+    \snippet customcompleter/mainwindow.cpp 2
 
     The \c about() function provides a brief description about the Custom
     Completer example.
 
-    \snippet examples/tools/customcompleter/mainwindow.cpp 3
+    \snippet customcompleter/mainwindow.cpp 3
 
     \section1 \c main() Function
 
     The \c main() function instantiates \c MainWindow and invokes the
     \l{QWidget::show()}{show()} function.
 
-    \snippet examples/tools/customcompleter/main.cpp 0
+    \snippet customcompleter/main.cpp 0
 */
diff --git a/examples/tools/doc/src/customtype.qdoc b/examples/tools/doc/src/customtype.qdoc
index b2f86d6890..e6511a08b4 100644
--- a/examples/tools/doc/src/customtype.qdoc
+++ b/examples/tools/doc/src/customtype.qdoc
@@ -56,7 +56,7 @@
     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
+    \snippet 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
@@ -67,14 +67,14 @@
     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
+    \snippet 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
+    \snippet customtype/message.h custom type streaming operator
 
     This facility is useful if you need to insert tracing statements in your
     code for debugging purposes.
@@ -84,11 +84,11 @@
     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
+    \snippet 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
+    \snippet 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
@@ -99,7 +99,7 @@
 
     We include the code for the getter functions for completeness:
 
-    \snippet examples/tools/customtype/message.cpp getter functions
+    \snippet customtype/message.cpp getter functions
 
     With the type fully defined, implemented, and integrated with the
     meta-object system, we can now use it.
@@ -109,13 +109,13 @@
     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
+    \snippet 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
+    \snippet customtype/main.cpp storing a custom value
 
     Alternatively, the QVariant::fromValue() and qVariantSetValue() functions
     can be used if you are using a compiler without support for member template
@@ -124,7 +124,7 @@
     The value can be retrieved using the QVariant::value() member template
     function:
 
-    \snippet examples/tools/customtype/main.cpp retrieving a custom value
+    \snippet 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.
diff --git a/examples/tools/doc/styleplugin.qdoc b/examples/tools/doc/styleplugin.qdoc
new file mode 100644
index 0000000000..0a55a7c29d
--- /dev/null
+++ b/examples/tools/doc/styleplugin.qdoc
@@ -0,0 +1,133 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \example styleplugin
+    \title Style Plugin Example
+
+    This example shows how to create a plugin that extends Qt with a new 
+    GUI look and feel. 
+
+    \image stylepluginexample.png
+
+    On some platforms, the native style will prevent the button
+    from having a red background. In this case, try to run the example
+    in another style (e.g., plastique).
+
+    A plugin in Qt is a class stored in a shared library that can be
+    loaded by a QPluginLoader at run-time. When you create plugins in
+    Qt, they either extend a Qt application or Qt itself. Writing a
+    plugin that extends Qt itself is achieved by inheriting one of the
+    plugin \l{Plugin Classes}{base classes}, reimplementing functions
+    from that class, and adding a macro. In this example we extend Qt
+    by adding a new GUI look and feel (i.e., making a new QStyle
+    available). A high-level introduction to plugins is given in the
+    plugin \l{How to Create Qt Plugins}{overview document}. 
+
+    Plugins that provide new styles inherit the QStylePlugin base
+    class. Style plugins are loaded by Qt and made available through
+    QStyleFactory; we will look at this later. We have implemented \c
+    SimpleStylePlugin, which provides \c SimpleStyle. The new style
+    inherits QWindowsStyle and contributes to widget styling by
+    drawing button backgrounds in red - not a major contribution, but
+    it still makes a new style. We test the plugin with \c
+    StyleWindow, in which we display a QPushButton.
+
+    The \c SimpleStyle and \c StyleWindow classes do not contain any
+    plugin specific functionality and their implementations are
+    trivial; we will therefore leap past them and head on to the \c
+    SimpleStylePlugin and the \c main() function. After we have looked
+    at that, we examine the plugin's profile.
+
+
+    \section1 SimpleStylePlugin Class Definition
+
+    \c SimpleStylePlugin inherits QStylePlugin and is the plugin
+    class. 
+
+    \snippet styleplugin/plugin/simplestyleplugin.h 0
+
+    \c keys() returns a list of style names that this plugin can
+    create, while \c create() takes such a string and returns the
+    QStyle corresponding to the key. Both functions are pure virtual
+    functions reimplemented from QStylePlugin. When an application
+    requests an instance of the \c SimpleStyle style, which this
+    plugin creates, Qt will create it with this plugin.
+
+
+    \section1 SimpleStylePlugin Class Implementation
+
+    Here is the implementation of \c keys():
+
+    \snippet styleplugin/plugin/simplestyleplugin.cpp 0
+
+    Since this plugin only supports one style, we return a QStringList
+    with the class name of that style.
+
+    Here is the \c create() function:
+
+    \snippet styleplugin/plugin/simplestyleplugin.cpp 1
+
+    Note that the key for style plugins are case insensitive.
+    The case sensitivity varies from plugin to plugin, so you need to
+    check this when implementing new plugins.
+
+    \section1 The \c main() function
+
+    \snippet styleplugin/stylewindow/main.cpp 0
+
+    Qt loads the available style plugins when the QApplication object
+    is initialized. The QStyleFactory class knows about all styles and
+    produces them with \l{QStyleFactory::}{create()} (it is a
+    wrapper around all the style plugins).
+
+    \section1 The Simple Style Plugin Profile
+
+    The \c SimpleStylePlugin lives in its own directory and have
+    its own profile:
+
+    \snippet styleplugin/plugin/plugin.pro 0
+
+    In the plugin profile we need to set the lib template as we are
+    building a shared library instead of an executable. We must also
+    set the config to plugin. We set the library to be stored in the
+    styles folder under stylewindow because this is a path in which Qt
+    will search for style plugins.
+
+    \section1 Related articles and examples
+
+    In addition to the plugin \l{How to Create Qt Plugins}{overview
+    document}, we have other examples and articles that concern
+    plugins.
+
+    In the \l{Echo Plugin Example}{echo plugin example} we show how to
+    implement plugins that extends Qt applications rather than Qt
+    itself, which is the case with the style plugin of this example.
+    The \l{Plug & Paint Example}{plug & paint} example shows how to
+    implement a static plugin as well as being a more involved example
+    on plugins that extend applications.
+*/
diff --git a/examples/tools/doc/stylepluginexample.png b/examples/tools/doc/stylepluginexample.png
new file mode 100644
index 0000000000..05d8c6b5cf
--- /dev/null
+++ b/examples/tools/doc/stylepluginexample.png
diff --git a/examples/tools/doc/textfinder-example-userinterface.png b/examples/tools/doc/textfinder-example-userinterface.png
new file mode 100644
index 0000000000..2bebe2e9dd
--- /dev/null
+++ b/examples/tools/doc/textfinder-example-userinterface.png
diff --git a/examples/tools/doc/textfinder.qdoc b/examples/tools/doc/textfinder.qdoc
new file mode 100644
index 0000000000..2b83e86318
--- /dev/null
+++ b/examples/tools/doc/textfinder.qdoc
@@ -0,0 +1,159 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \example uitools/textfinder
+    \title Text Finder Example
+
+    The Text Finder example demonstrates how to dynamically process forms
+    using the QtUiTools module. Dynamic form processing enables a form to
+    be processed at run-time only by changing the UI file for the project.
+    The program allows the user to look up a particular word within the
+    contents of a text file. This text file is included in the project's
+    resource and is loaded into the display at startup.
+
+    \table
+    \row \li \inlineimage textfinder-example-find.png
+         \li \inlineimage textfinder-example-find2.png
+    \endtable
+
+    \section1 Setting Up The Resource File
+
+    The resources required for Text Finder are:
+    \list
+        \li \e{textfinder.ui} - the user interface file created in QtDesigner
+        \li \e{input.txt} - a text file containing some text to be displayed
+                           in the QTextEdit
+    \endlist
+
+    \e{textfinder.ui} contains all the necessary QWidget objects for the
+    Text Finder. A QLineEdit is used for the user input, a QTextEdit is
+    used to display the contents of \e{input.txt}, a QLabel is used to
+    display the text "Keyword", and a QPushButton is used for the "Find"
+    button. The screenshot below shows the preview obtained in QtDesigner.
+
+    \image textfinder-example-userinterface.png
+
+    A \e{textfinder.qrc} file is used to store both the \e{textfinder.ui}
+    and \e{input.txt} in the application's executable. The file contains 
+    the following code:
+
+    \quotefile examples/uitools/textfinder/textfinder.qrc
+
+    For more information on resource files, see \l{The Qt Resource System}.
+
+    To generate a form at run-time, the example is linked against the
+    QtUiTools module library. This is done in the \c{textfinder.pro} file
+    that contains the following lines:
+
+    \snippet doc/src/snippets/code/doc_src_examples_textfinder.pro 0
+
+    \section1 TextFinder Class Definition
+
+    The \c TextFinder class is a subclass of QWidget and it hosts the
+    \l{QWidget}s we need to access in the user interface. The QLabel in the
+    user interface is not declared here as we do not need to access it.
+
+    \snippet examples/uitools/textfinder/textfinder.h 0
+
+    The slot \c{on_findButton_clicked()} is a slot named according to the
+    \l{Using a Designer UI File in Your Application#Automatic Connections}
+    {Automatic Connection} naming convention required
+    by \c uic.
+
+    \section1 TextFinder Class Implementation
+
+    The \c TextFinder class's constructor calls the \c loadUiFile() function
+    and then uses \c qFindChild() to access the user interface's
+    \l{QWidget}s.
+
+    \snippet examples/uitools/textfinder/textfinder.cpp 0
+
+    We then use QMetaObject's system to enable signal and slot connections.
+
+    \snippet examples/uitools/textfinder/textfinder.cpp 2
+
+    The loadTextFile() function is called to load \c{input.txt} into
+    QTextEdit to displays its contents.
+
+    \snippet examples/uitools/textfinder/textfinder.cpp 3a
+
+    The \c{TextFinder}'s layout is set with \l{QWidget::}{setLayout()}.
+
+    \snippet examples/uitools/textfinder/textfinder.cpp 3b
+
+    Finally, the window title is set to \e {Text Finder} and \c isFirstTime is
+    set to true.
+
+    \c isFirstTime is used as a flag to indicate whether the search operation
+    has been performed more than once. This is further explained with the
+    \c{on_findButton_clicked()} function.
+
+    The \c{loadUiFile()} function is used to load the user interface file
+    previously created in QtDesigner. The QUiLoader class is instantiated
+    and its \c load() function is used to load the form into \c{formWidget}
+    that acts as a place holder for the user interface. The function then
+    returns \c{formWidget} to its caller.
+
+    \snippet examples/uitools/textfinder/textfinder.cpp 4
+
+    As mentioned earlier, the loadTextFile() function loads \e{input.txt}
+    into QTextEdit to display its contents. Data is read using QTextStream
+    into a QString object, \c line with the QTextStream::readAll() function.
+    The contents of \c line are then appended to \c{ui_textEdit}.
+
+    \snippet examples/uitools/textfinder/textfinder.cpp 5
+
+    The \c{on_findButton_clicked()} function is a slot that is connected to
+    \c{ui_findButton}'s \c clicked() signal. The \c searchString is extracted
+    from the \c ui_lineEdit and the \c document is extracted from \c textEdit.
+    In event there is an empty \c searchString, a QMessageBox is used,
+    requesting the user to enter a word. Otherwise, we traverse through the
+    words in \c ui_textEdit, and highlight all ocurrences of the
+    \c searchString . Two QTextCursor objects are used: One to traverse through
+    the words in \c line and another to keep track of the edit blocks.
+
+    \snippet examples/uitools/textfinder/textfinder.cpp 7
+
+    The \c isFirstTime flag is set to false the moment \c findButton is
+    clicked. This is necessary to undo the previous text highlight before
+    highlighting the user's next search string. Also, the \c found flag
+    is used to indicate if the \c searchString was found within the contents
+    of \c ui_textEdit. If it was not found, a QMessageBox is used
+    to inform the user.
+
+    \snippet examples/uitools/textfinder/textfinder.cpp 9
+
+    \section1 \c main() Function
+
+    \snippet examples/uitools/textfinder/main.cpp 0
+
+    The \c main() function initialises the \e{textfinder.qrc} resource file
+    and instantiates as well as displays \c TextFinder.
+
+    \sa {Calculator Builder Example}, {World Time Clock Builder Example}
+    */
diff --git a/examples/tools/doc/treemodelcompleter-example.png b/examples/tools/doc/treemodelcompleter-example.png
new file mode 100644
index 0000000000..000405fe39
--- /dev/null
+++ b/examples/tools/doc/treemodelcompleter-example.png
diff --git a/examples/tools/doc/treemodelcompleter.qdoc b/examples/tools/doc/treemodelcompleter.qdoc
new file mode 100644
index 0000000000..d233834d0d
--- /dev/null
+++ b/examples/tools/doc/treemodelcompleter.qdoc
@@ -0,0 +1,171 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \example treemodelcompleter
+    \title Tree Model Completer Example
+
+    The Tree Model Completer example shows how to provide completion
+    facilities for a hierarchical model, using a period as the separator
+    to access Child, GrandChild and GrandGrandChild level objects.
+
+    \image treemodelcompleter-example.png
+
+    Similar to the \l{Completer Example}, we provide QComboBox objects to
+    enable selection for completion mode and case sensitivity, as well as
+    a QCheckBox for wrap completions.
+
+    \section1 The Resource File
+
+    The contents of the TreeModelCompleter is read from \e treemodel.txt.
+    This file is embedded within the \e treemodelcompleter.qrc resource file,
+    which contains the following:
+
+    \quotefile treemodelcompleter/treemodelcompleter.qrc
+
+    \section1 TreeModelCompleter Class Definition
+
+    The \c TreeModelCompleter is a subclass of QCompleter with two
+    constructors - one with \a parent as an argument and another with
+    \a parent and \a model as arguments.
+
+    \snippet treemodelcompleter/treemodelcompleter.h 0
+
+    The class reimplements the protected functions
+    \l{QCompleter::splitPath()}{splitPath()}  and
+    \l{QCompleter::pathFromIndex()}{pathFromIndex()} to suit a tree model.
+    For more information on customizing QCompleter to suit tree models, refer
+    to \l{QCompleter#Handling Tree Models}{Handling Tree Models}.
+
+    \c TreeModelCompleter also has a separator property which is declared
+    using the Q_PROPERTY() macro. The separator has READ and WRITE attributes
+    and the corresponding functions \c separator() and \c setSeparator(). For
+    more information on Q_PROPERTY(), refer to \l{Qt's Property System}.
+
+    \section1 TreeModelCompleter Class Implementation
+
+    The first constructor constructs a \c TreeModelCompleter object with a
+    parent while the second constructor constructs an object with a parent
+    and a QAbstractItemModel, \a model.
+
+    \snippet treemodelcompleter/treemodelcompleter.cpp 0
+    \codeline
+    \snippet treemodelcompleter/treemodelcompleter.cpp 1
+
+    The \c separator() function is a getter function that returns the
+    separator string.
+
+    \snippet treemodelcompleter/treemodelcompleter.cpp 2
+
+    As mentioned earlier, the \c splitPath() function is reimplemented because
+    the default implementation is more suited to QDirModel or list models. In
+    order for QCompleter to split the path into a list of strings that are
+    matched at each level, we split it using QString::split() with \c sep as its
+    separator.
+
+    \snippet treemodelcompleter/treemodelcompleter.cpp 3
+
+    The \c pathFromIndex() function returns data for the completionRole() for a
+    tree model. This function is reimplemented as its default implementation is
+    more suitable for list models. If there is no separator, we use
+    \l{QCompleter}'s default implementation, otherwise we use the
+    \l{QStringList::prepend()}{prepend()} function to navigate upwards and
+    accumulate the data. The function then returns a QStringList, \c dataList,
+    using a separator to join objects of different levels.
+
+    \snippet treemodelcompleter/treemodelcompleter.cpp 4
+
+    \section1 MainWindow Class Definition
+
+    The \c MainWindow class is a subclass of QMainWindow and implements five
+    custom slots: \c about(), \c changeCase(), \c changeMode(),
+    \c highlight(), and \c updateContentsLabel().
+
+    \snippet treemodelcompleter/mainwindow.h 0
+
+    In addition, the class has two private functions, \c createMenu() and
+    \c modelFromFile(), as well as private instances of QTreeView, QComboBox,
+    QLabel, \c TreeModelCompleter and QLineEdit.
+
+    \snippet treemodelcompleter/mainwindow.h 1
+
+    \section1 MainWindow Class Implementation
+
+    The \c{MainWindow}'s constructor creates a \c MainWindow object with a
+    parent and initializes the \c completer and \c lineEdit. The
+    \c createMenu() function is invoked to set up the "File" menu and "Help"
+    menu. The \c{completer}'s model is set to the QAbstractItemModel obtained
+    from \c modelFromFile(), and the \l{QCompleter::highlighted()}
+    {highlighted()} signal is connected to \c{MainWindow}'s \c highlight()
+    slot.
+
+    \snippet treemodelcompleter/mainwindow.cpp 0
+
+    The QLabel objects \c modelLabel, \c modeLabel and \c caseLabel are
+    instantiated. Also, the QComboBox objects, \c modeCombo and \c caseCombo,
+    are instantiated and populated. By default, the \c{completer}'s mode is
+    "Filtered Popup" and the case is insensitive.
+
+    \snippet treemodelcompleter/mainwindow.cpp 1
+    \codeline
+    \snippet treemodelcompleter/mainwindow.cpp 2
+
+    We use a QGridLayout to place all the objects in the \c MainWindow.
+
+    \snippet treemodelcompleter/mainwindow.cpp 3
+
+    The \c createMenu() function sets up the QAction objects required and
+    adds them to the "File" menu and "Help" menu. The
+    \l{QAction::triggered()}{triggered()} signals from these actions are
+    connected to their respective slots.
+
+    \snippet treemodelcompleter/mainwindow.cpp 4
+
+    The \c changeMode() function accepts an \a index corresponding to the
+    user's choice of completion mode and changes the \c{completer}'s mode
+    accordingly.
+
+    \snippet treemodelcompleter/mainwindow.cpp 5
+
+    The \c about() function provides a brief description on the Tree Model
+    Completer example.
+
+    \snippet treemodelcompleter/mainwindow.cpp 6
+
+    The \c changeCase() function alternates between \l{Qt::CaseSensitive}
+    {Case Sensitive} and \l{Qt::CaseInsensitive}{Case Insensitive} modes,
+    depending on the value of \a cs.
+
+    \snippet treemodelcompleter/mainwindow.cpp 7
+
+    \section1 \c main() Function
+
+    The \c main() function instantiates \c MainWindow and invokes the
+    \l{QWidget::show()}{show()} function to display it.
+
+    \snippet treemodelcompleter/main.cpp 0
+*/
diff --git a/examples/tools/doc/undo.qdoc b/examples/tools/doc/undo.qdoc
new file mode 100644
index 0000000000..31c698f6c7
--- /dev/null
+++ b/examples/tools/doc/undo.qdoc
@@ -0,0 +1,43 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \example undo
+    \title Undo Framework
+
+    This example shows Qt's undo framework in action.
+
+    \image undodemo.png
+
+    Qt's undo framework is an implementation of the Command
+    pattern, which provides advanced undo/redo functionality. 
+
+    To show the abilities of the framework, we have implemented a
+    small diagram application in which the diagram items are geometric
+    primitives.  You can edit the diagram in the following ways: add,
+    move, change the color of, and delete the items.
+*/
diff --git a/examples/tools/doc/undodemo.png b/examples/tools/doc/undodemo.png
new file mode 100644
index 0000000000..85c3622738
--- /dev/null
+++ b/examples/tools/doc/undodemo.png
diff --git a/examples/tools/doc/undoframework.qdoc b/examples/tools/doc/undoframework.qdoc
new file mode 100644
index 0000000000..abdfab3861
--- /dev/null
+++ b/examples/tools/doc/undoframework.qdoc
@@ -0,0 +1,291 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \example undoframework
+    \title Undo Framework Example
+
+    This example shows how to implement undo/redo functionality 
+    with the Qt undo framework.
+
+    \image undoframeworkexample.png The Undo Diagram Example
+
+    In the Qt undo framework, all actions that the user performs are
+    implemented in classes that inherit QUndoCommand. An undo command
+    class knows how to both \l{QUndoCommand::}{redo()} - or just do
+    the first time - and \l{QUndoCommand::}{undo()} an action. For
+    each action the user performs, a command is placed on a
+    QUndoStack.  Since the stack contains all commands executed
+    (stacked in chronological order) on the document, it can roll the
+    state of the document backwards and forwards by undoing and redoing
+    its commands. See the \l{Overview of Qt's Undo Framework}{overview
+    document} for a high-level introduction to the undo framework.
+
+    The undo example implements a simple diagram application. It is
+    possible to add and delete items, which are either box or
+    rectangular shaped, and move the items by dragging them with the
+    mouse. The undo stack is shown in a QUndoView, which is a list in
+    which the commands are shown as list items. Undo and redo are
+    available through the edit menu. The user can also select a command
+    from the undo view.
+
+    We use the \l{Graphics View Framework}{graphics view
+    framework} to implement the diagram. We only treat the related
+    code briefly as the framework has examples of its own (e.g., the
+    \l{Diagram Scene Example}).
+
+    The example consists of the following classes:
+
+    \list 
+        \li \c MainWindow is the main window and arranges the
+              example's widgets. It creates the commands based 
+              on user input and keeps them on the command stack.
+        \li \c AddCommand adds an item to the scene.
+        \li \c DeleteCommand deletes an item from the scene.
+        \li \c MoveCommand when an item is moved the MoveCommand keeps record
+              of the start and stop positions of the move, and it
+              moves the item according to these when \c redo() and \c undo()
+              is called.
+        \li \c DiagramScene inherits QGraphicsScene and
+              emits signals for the \c MoveComands when an item is moved.
+        \li \c DiagramItem inherits QGraphicsPolygonItem and represents
+              an item in the diagram.
+    \endlist
+
+    \section1 MainWindow Class Definition
+
+    \snippet undoframework/mainwindow.h 0
+
+    The \c MainWindow class maintains the undo stack, i.e., it creates
+    \l{QUndoCommand}s and pushes and pops them from the stack when it
+    receives the \c triggered() signal from \c undoAction and \c
+    redoAction.
+    
+    \section1 MainWindow Class Implementation
+
+    We will start with a look at the constructor:    
+
+    \snippet undoframework/mainwindow.cpp 0
+
+    In the constructor, we set up the DiagramScene and QGraphicsView. 
+
+    Here is the \c createUndoView() function:    
+
+    \snippet undoframework/mainwindow.cpp 1
+
+    The QUndoView is a widget that display the text, which is set with
+    the \l{QUndoCommand::}{setText()} function, for each QUndoCommand
+    in the undo stack in a list.
+    
+    Here is the \c createActions() function:
+
+    \snippet undoframework/mainwindow.cpp 2
+    \codeline
+    \snippet undoframework/mainwindow.cpp 3
+    \dots
+    \snippet undoframework/mainwindow.cpp 5
+
+    The \c createActions() function sets up all the examples actions
+    in the manner shown above. The
+    \l{QUndoStack::}{createUndoAction()} and
+    \l{QUndoStack::}{createRedoAction()} helps us crate actions that
+    are disabled and enabled based on the state of the stack.  Also,
+    the text of the action will be updated automatically based on the
+    \l{QUndoCommand::}{text()} of the undo commands. For the other
+    actions we have implemented slots in the \c MainWindow class.
+
+    Here is the \c createMenus() function:
+
+    \snippet undoframework/mainwindow.cpp 6
+
+    \dots
+    \snippet undoframework/mainwindow.cpp 7
+    \dots
+    \snippet undoframework/mainwindow.cpp 8
+
+    We have to use the QMenu \c aboutToShow() and \c aboutToHide()
+    signals since we only want \c deleteAction to be enabled when we
+    have selected an item.     
+
+    Here is the \c itemMoved() slot:
+
+    \snippet undoframework/mainwindow.cpp 9
+
+    We simply push a MoveCommand on the stack, which calls \c redo()
+    on it.
+
+    Here is the \c deleteItem() slot:
+
+    \snippet undoframework/mainwindow.cpp 10
+
+    An item must be selected to be deleted.  We need to check if it is
+    selected as the \c deleteAction may be enabled even if an item is
+    not selected. This can happen as we do not catch a signal or event
+    when an item is selected.
+
+    Here is the \c itemMenuAboutToShow() and itemMenuAboutToHide() slots:
+
+    \snippet undoframework/mainwindow.cpp 11
+    \codeline
+    \snippet undoframework/mainwindow.cpp 12
+
+    We implement \c itemMenuAboutToShow() and \c itemMenuAboutToHide()
+    to get a dynamic item menu. These slots are connected to the 
+    \l{QMenu::}{aboutToShow()} and \l{QMenu::}{aboutToHide()} signals.
+    We need this to disable or enable the \c deleteAction. 
+
+    Here is the \c addBox() slot:
+
+    \snippet undoframework/mainwindow.cpp 13
+
+    The \c addBox() function creates an AddCommand and pushes it on
+    the undo stack.
+
+    Here is the \c addTriangle() sot:
+
+    \snippet undoframework/mainwindow.cpp 14
+
+    The \c addTriangle() function creates an AddCommand and pushes it
+    on the undo stack.    
+
+    Here is the implementation of \c about():
+
+    \snippet undoframework/mainwindow.cpp 15
+    
+    The about slot is triggered by the \c aboutAction and displays an
+    about box for the example.
+
+    \section1 AddCommand Class Definition
+    
+    \snippet undoframework/commands.h 2
+
+    The \c AddCommand class adds DiagramItem graphics items to the
+    DiagramScene.  
+
+    \section1 AddCommand Class Implementation
+
+    We start with the constructor:
+
+    \snippet undoframework/commands.cpp 7
+
+    We first create the DiagramItem to add to the DiagramScene.  The
+    \l{QUndoCommand::}{setText()} function let us set a QString that
+    describes the command. We use this to get custom messages in the
+    QUndoView and in the menu of the main window.
+
+    \snippet undoframework/commands.cpp 8
+
+    \c undo() removes the item from the scene.
+
+    \snippet undoframework/commands.cpp 9
+
+    We set the position of the item as we do not do this in the
+    constructor.
+
+    \section1 DeleteCommand Class Definition
+    
+    \snippet undoframework/commands.h 1
+
+    The DeleteCommand class implements the functionality to remove an
+    item from the scene.
+    
+    \section1 DeleteCommand Class Implementation
+
+    \snippet undoframework/commands.cpp 4
+
+    We know that there must be one selected item as it is not possible
+    to create a DeleteCommand unless the item to be deleted is
+    selected and that only one item can be selected at any time. 
+    The item must be unselected if it is inserted back into the 
+    scene.
+
+    \snippet undoframework/commands.cpp 5
+
+    The item is simply reinserted into the scene.
+
+    \snippet undoframework/commands.cpp 6
+
+    The item is removed from the scene.
+
+    \section1 MoveCommand Class Definition
+
+    \snippet undoframework/commands.h 0
+
+    The \l{QUndoCommand::}{mergeWith()} is reimplemented to make
+    consecutive moves of an item one MoveCommand, i.e, the item will
+    be moved back to the start position of the first move.
+
+    \section1 MoveCommand Class Implementation
+
+    
+    The constructor of MoveCommand looks like this:
+
+    \snippet undoframework/commands.cpp 0
+
+    We save both the old and new positions for undo and redo
+    respectively.
+
+    \snippet undoframework/commands.cpp 2
+
+    We simply set the items old position and update the scene.    
+
+    \snippet undoframework/commands.cpp 3
+
+    We set the item to its new position.
+    
+    \snippet undoframework/commands.cpp 1
+
+    Whenever a MoveCommand is created, this function is called to
+    check if it should be merged with the previous command. It is the
+    previous command object that is kept on the stack. The function
+    returns true if the command is merged; otherwise false.
+
+    We first check whether it is the same item that has been moved
+    twice, in which case we merge the commands. We update the position
+    of the item so that it will take the last position in the move
+    sequence when undone. 
+
+    \section1 DiagramScene Class Definition
+
+    \snippet undoframework/diagramscene.h 0
+
+    The DiagramScene implements the functionality to move a
+    DiagramItem with the mouse. It emits a signal when a move is
+    completed. This is caught by the \c MainWindow, which makes
+    MoveCommands. We do not examine the implementation of DiagramScene
+    as it only deals with graphics framework issues.
+
+    \section1 The \c main() Function
+    
+    The \c main() function of the program looks like this:
+
+    \snippet undoframework/main.cpp 0
+
+    We draw a grid in the background of the DiagramScene, so we use a
+    resource file. The rest of the function creates the \c MainWindow and
+    shows it as a top level window.
+*/
diff --git a/examples/tools/doc/undoframeworkexample.png b/examples/tools/doc/undoframeworkexample.png
new file mode 100644
index 0000000000..7e0a1df260
--- /dev/null
+++ b/examples/tools/doc/undoframeworkexample.png
diff --git a/examples/widgets/doc/dropsite.qdoc b/examples/widgets/doc/dropsite.qdoc
new file mode 100644
index 0000000000..6e4b21a9be
--- /dev/null
+++ b/examples/widgets/doc/dropsite.qdoc
@@ -0,0 +1,249 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \example draganddrop/dropsite
+    \title Drop Site Example
+
+    The example shows how to distinguish the various MIME formats available
+    in a drag and drop operation.
+
+    \image dropsite-example.png Screenshot of the Drop Site example
+
+    The Drop Site example accepts drops from other applications, and displays
+    the MIME formats provided by the drag object.
+
+    There are two classes, \c DropArea and \c DropSiteWindow, and a \c main()
+    function in this example. A \c DropArea object is instantiated in
+    \c DropSiteWindow; a \c DropSiteWindow object is then invoked in the
+    \c main() function.
+
+    \section1 DropArea Class Definition
+
+    The \c DropArea class is a subclass of QLabel with a public slot,
+    \c clear(), and a \c changed() signal.
+
+    \snippet draganddrop/dropsite/droparea.h DropArea header part1
+
+    In addition, \c DropArea also contains a private instance of QLabel and
+    reimplementations of four \l{QWidget} event handlers:
+
+    \list 1
+        \li \l{QWidget::dragEnterEvent()}{dragEnterEvent()}
+        \li \l{QWidget::dragMoveEvent()}{dragMoveEvent()}
+        \li \l{QWidget::dragLeaveEvent()}{dragLeaveEvent()}
+        \li \l{QWidget::dropEvent()}{dropEvent()}
+    \endlist
+
+    These event handlers are further explained in the implementation of the
+    \c DropArea class.
+
+    \snippet draganddrop/dropsite/droparea.h DropArea header part2
+
+    \section1 DropArea Class Implementation
+
+    In the \c DropArea constructor, we set the \l{QWidget::setMinimumSize()}
+    {minimum size} to 200x200 pixels, the \l{QFrame::setFrameStyle()}
+    {frame style} to both QFrame::Sunken and QFrame::StyledPanel, and we align
+    its contents to the center.
+
+    \snippet draganddrop/dropsite/droparea.cpp DropArea constructor
+
+    Also, we enable drop events in \c DropArea by setting the
+    \l{QWidget::acceptDrops()}{acceptDrops} property to \c true. Then,
+    we enable the \l{QWidget::autoFillBackground()}{autoFillBackground}
+    property and invoke the \c clear() function.
+
+    The \l{QWidget::dragEnterEvent()}{dragEnterEvent()} event handler is
+    called when a drag is in progress and the mouse enters the \c DropArea
+    object. For the \c DropSite example, when the mouse enters \c DropArea,
+    we set its text to "<drop content>" and highlight its background.
+
+    \snippet draganddrop/dropsite/droparea.cpp dragEnterEvent() function
+
+    Then, we invoke \l{QDropEvent::acceptProposedAction()}
+    {acceptProposedAction()} on \a event, setting the drop action to the one
+    proposed. Lastly, we emit the \c changed() signal, with the data that was
+    dropped and its MIME type information as a parameter.
+
+    For \l{QWidget::dragMoveEvent()}{dragMoveEvent()}, we just accept the
+    proposed QDragMoveEvent object, \a event, with
+    \l{QDropEvent::acceptProposedAction()}{acceptProposedAction()}.
+
+    \snippet draganddrop/dropsite/droparea.cpp dragMoveEvent() function
+
+    The \c DropArea class's implementation of \l{QWidget::dropEvent()}
+    {dropEvent()} extracts the \a{event}'s mime data and displays it
+    accordingly.
+
+    \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part1
+
+    The \c mimeData object can contain one of the following objects: an image,
+    HTML text, plain text, or a list of URLs.
+
+    \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part2
+
+    \list
+        \li If \c mimeData contains an image, we display it in \c DropArea with
+           \l{QLabel::setPixmap()}{setPixmap()}.
+        \li If \c mimeData contains HTML, we display it with
+           \l{QLabel::setText()}{setText()} and set \c{DropArea}'s text format
+           as Qt::RichText.
+        \li If \c mimeData contains plain text, we display it with
+           \l{QLabel::setText()}{setText()} and set \c{DropArea}'s text format
+           as Qt::PlainText. In the event that \c mimeData contains URLs, we
+           iterate through the list of URLs to display them on individual
+           lines.
+        \li If \c mimeData contains other types of objects, we set
+           \c{DropArea}'s text, with \l{QLabel::setText()}{setText()} to
+           "Cannot display data" to inform the user.
+    \endlist
+
+    We then set \c{DropArea}'s \l{QWidget::backgroundRole()}{backgroundRole} to
+    QPalette::Dark and we accept \c{event}'s proposed action.
+
+    \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part3
+
+    The \l{QWidget::dragLeaveEvent()}{dragLeaveEvent()} event handler is
+    called when a drag is in progress and the mouse leaves the widget.
+
+    \snippet draganddrop/dropsite/droparea.cpp dragLeaveEvent() function
+
+    For \c{DropArea}'s implementation, we clear invoke \c clear() and then
+    accept the proposed event.
+
+    The \c clear() function sets the text in \c DropArea to "<drop content>"
+    and sets the \l{QWidget::backgroundRole()}{backgroundRole} to
+    QPalette::Dark. Lastly, it emits the \c changed() signal.
+
+    \snippet draganddrop/dropsite/droparea.cpp clear() function
+
+    \section1 DropSiteWindow Class Definition
+
+    The \c DropSiteWindow class contains a constructor and a public slot,
+    \c updateFormatsTable().
+
+    \snippet draganddrop/dropsite/dropsitewindow.h DropSiteWindow header
+
+    The class also contains a private instance of \c DropArea, \c dropArea,
+    QLabel, \c abstractLabel, QTableWidget, \c formatsTable, QDialogButtonBox,
+    \c buttonBox, and two QPushButton objects, \c clearButton and
+    \c quitButton.
+
+    \section1 DropSiteWindow Class Implementation
+
+    In the constructor of \c DropSiteWindow, we instantiate \c abstractLabel
+    and set its \l{QLabel::setWordWrap()}{wordWrap} property to \c true. We
+    also call the \l{QLabel::adjustSize()}{adjustSize()} function to adjust
+    \c{abstractLabel}'s size according to its contents.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part1
+
+    Then we instantiate \c dropArea and connect its \c changed() signal to
+    \c{DropSiteWindow}'s \c updateFormatsTable() slot.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part2
+
+    We now set up the QTableWidget object, \c formatsTable. Its
+    horizontal header is set using a QStringList object, \c labels. The number
+    of columms are set to two and the table is not editable. Also, the
+    \c{formatTable}'s horizontal header is formatted to ensure that its second
+    column stretches to occupy additional space available.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part3
+
+    Two QPushButton objects, \c clearButton and \c quitButton, are instantiated
+    and added to \c buttonBox - a QDialogButtonBox object. We use
+    QDialogButtonBox here to ensure that the push buttons are presented in a
+    layout that conforms to the platform's style.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part4
+
+    The \l{QPushButton::clicked()}{clicked()} signals for \c quitButton and
+    \c clearButton are connected to \l{QWidget::close()}{close()} and
+    \c clear(), respectively.
+
+    For the layout, we use a QVBoxLayout, \c mainLayout, to arrange our widgets
+    vertically. We also set the window title to "Drop Site" and the minimum
+    size to 350x500 pixels.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part5
+
+    We move on to the \c updateFormatsTable() function. This function updates
+    the \c formatsTable, displaying the MIME formats of the object dropped onto
+    the \c DropArea object. First, we set \l{QTableWidget}'s
+    \l{QTableWidget::setRowCount()}{rowCount} property to 0. Then, we validate
+    to ensure that the QMimeData object passed in is a valid object.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part1
+
+    Once we are sure that \c mimeData is valid, we iterate through its
+    supported formats using the \l{The foreach Keyword}{foreach keyword}.
+    This keyword has the following format:
+
+    \snippet code/doc_src_examples_dropsite.qdoc 0
+
+    In our example, \c format is the \a variable and the \a container is a
+    QStringList, obtained from \c mimeData->formats().
+
+    \note The \l{QMimeData::formats()}{formats()} function returns a
+    QStringList object, containing all the formats supported by the
+    \c mimeData.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part2
+
+    Within each iteration, we create a QTableWidgetItem, \c formatItem and we
+    set its \l{QTableWidgetItem::setFlags()}{flags} to Qt::ItemIsEnabled, and
+    its \l{QTableWidgetItem::setTextAlignment()}{text alignment} to Qt::AlignTop
+    and Qt::AlignLeft.
+
+    A QString object, \c text, is customized to display data according to the
+    contents of \c format. We invoke {QString}'s \l{QString::simplified()}
+    {simplified()} function on \c text, to obtain a string that has no
+    additional space before, after or in between words.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part3
+
+    If \c format contains a list of URLs, we iterate through them, using spaces
+    to separate them. On the other hand, if \c format contains an image, we
+    display the data by converting the text to hexadecimal.
+
+    \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part4
+
+    Once \c text has been customized to contain the appropriate data, we insert
+    both \c format and \c text into \c formatsTable with
+    \l{QTableWidget::setItem()}{setItem()}. Lastly, we invoke
+    \l{QTableView::resizeColumnToContents()}{resizeColumnToContents()} on
+    \c{formatsTable}'s first column.
+
+    \section1 The main() Function
+
+    Within the \c main() function, we instantiate \c DropSiteWindow and invoke
+    its \l{QWidget::show()}{show()} function.
+
+    \snippet draganddrop/dropsite/main.cpp main() function
+*/
diff --git a/examples/widgets/doc/images/dropsite-example.png b/examples/widgets/doc/images/dropsite-example.png
new file mode 100644
index 0000000000..42b988d733
--- /dev/null
+++ b/examples/widgets/doc/images/dropsite-example.png
diff --git a/examples/widgets/doc/images/mousebutton-buttontester.png b/examples/widgets/doc/images/mousebutton-buttontester.png
new file mode 100644
index 0000000000..82fcb7617f
--- /dev/null
+++ b/examples/widgets/doc/images/mousebutton-buttontester.png
diff --git a/examples/widgets/doc/images/orientation-landscape-ui.png b/examples/widgets/doc/images/orientation-landscape-ui.png
new file mode 100644
index 0000000000..c591ff14d2
--- /dev/null
+++ b/examples/widgets/doc/images/orientation-landscape-ui.png
diff --git a/examples/widgets/doc/images/orientation-landscape.png b/examples/widgets/doc/images/orientation-landscape.png
new file mode 100644
index 0000000000..e606804d21
--- /dev/null
+++ b/examples/widgets/doc/images/orientation-landscape.png
diff --git a/examples/widgets/doc/images/orientation-portrait-ui.png b/examples/widgets/doc/images/orientation-portrait-ui.png
new file mode 100644
index 0000000000..304835b93e
--- /dev/null
+++ b/examples/widgets/doc/images/orientation-portrait-ui.png
diff --git a/examples/widgets/doc/images/orientation-portrait.png b/examples/widgets/doc/images/orientation-portrait.png
new file mode 100644
index 0000000000..3d778e8d90
--- /dev/null
+++ b/examples/widgets/doc/images/orientation-portrait.png
diff --git a/examples/widgets/doc/mousebuttons.qdoc b/examples/widgets/doc/mousebuttons.qdoc
new file mode 100644
index 0000000000..10d1f9a116
--- /dev/null
+++ b/examples/widgets/doc/mousebuttons.qdoc
@@ -0,0 +1,94 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Copyright (C) 2012 Rick Stockton <rickstockton@reno-computerhelp.com>
+** Contact: http://www.qt-project.org/
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \example widgets/mousebuttons
+    \title Mouse Button Tester
+
+    \brief The 'Mouse Button Tester' example demonstrates how to reimplement
+    mouse events within a custom class. You can also use this program to
+    verify that Qt is actually receiving mouse events from your mouse.
+
+    Many 'gamer' mouse devices are configured with high-numbered "buttons"
+    sending text shortcuts for certain games. With such a mouse, no mouse
+    button events occur: The "mouse" sends keystrokes, and the
+    'Mouse Button Tester' Window will not see the event. Receiving no event,
+    it will not repaint the Window with new text describing a button event.
+
+    And so, in addition to it's use as Qt example code, the program may be
+    useful s a mouse device tester. Note that there is another example
+    mouse buttons example which provides the same function, written in QML.
+
+    This program (the Widget-based example) consists of three classes,
+    in addition to the main() parent program:
+
+    \list
+        \li \c A QPushButton, "Quit".
+        \li \c ButtonTester. This is derived from Qt's TextArea class, for
+            purpose of customizing/re-implementing the mouse and wheel event
+            member functions.
+        \li \c A simple QVBoxLayout layout.
+    \endlist
+
+    First we will review the main program, with it's layout and "Quit"
+    QPushButton. Then we will take a look at the \c ButtonTester class.
+
+    \section1 The Main Program
+
+    Note that the QPushButton, "Quit", is defined directly within the main()
+    program, rather than another class. This is a correct way of defining a
+    "Quit" QPushButton: A "Quit" Button defined inside another
+    class would result in the destructor of that second class being
+    called twice. This "Quit" Button uses the traditional Signal/Slot
+    connection to invoke termination of the QApp, which will properly destroy
+    its child classes before terminating itself.
+
+    The remainder of the main() program is concerned with defining the layout,
+    and applying a minimum size to the customized ButtonTester.
+
+    \section1 ButtonTester Class Definition
+
+    The \c ButtonTester class inherits from QTextEdit, and listens for
+    mouse events on all possible Qt::MouseButton values. It also listens for
+    wheel events from the mouse, and indicates the direction of wheel motion
+    ("up", down", "left", or "right"). It prints short debug messages into
+    the Window, and also on the console QDebug() stream, when mouse button
+    and wheel events occur. Our reimplementation of mousePressEvent(),
+    mouseReleaseEvent(), mouseDoubleClickEvent(), and wheelEvent() "drive"
+    the program; the other functions simply convert the Qt::MouseButton
+    values into text strings.
+
+    You should call the ignore() function on any mouse event (or other event)
+    which your widget-based classes do not use and consume. This function
+    assures that Qt will propagate the event through each parent widget,
+    until it is used or propagated to the Window Manager. (Qt attempts to do
+    this automatically, but it is better programming practice to explicitly
+    invoke the function.)
+
+    \image mousebutton-buttontester.png
+*/
diff --git a/examples/widgets/doc/orientation.qdoc b/examples/widgets/doc/orientation.qdoc
new file mode 100644
index 0000000000..b39bbf981a
--- /dev/null
+++ b/examples/widgets/doc/orientation.qdoc
@@ -0,0 +1,143 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** 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$
+**
+****************************************************************************/
+
+/*! \example widgets/orientation
+    \group all-examples
+    \title Orientation Example
+
+    The example shows a simple way to use different UIs depending on the screen
+    orientation of a mobile device.
+
+    \image orientation-landscape.png The UI in landscape mode
+    \image orientation-portrait.png The UI in portrait mode
+
+    The screen on many mobile devices can be viewed in both portrait and
+    landscape orientation. The orientation can be swiched with the help of a
+    hardware or software trigger. Due to the often small physical screen size,
+    user interfaces has to be very simple and compact to stay usable, and
+    applications usually occupy the whole screen. Designing a user interface
+    that works equally well in both landscape and portrait mode is not always
+    possible, however, so making a different layout for each case usually pays
+    off.
+
+    The example application makes use of two different UI widgets created with
+    the Qt Designer, one for portrait and one for landscape orientation. The
+    application has a widget that contains an image and the user is able to
+    select one of three images for it to show. In addition to the two UIs, the
+    application consists of a \c MainWindow class.
+
+    \section1 Landscape UI
+
+    If the screen is in landscape mode, the user probably holds the device with
+    both hands and is ready to give full attention to the application. The
+    landscape UI looks like this:
+
+    \image orientation-landscape-ui.png The landscape UI
+
+    To the left is a QWidget called \c choiceWidget, which will show the
+    current image, and to the right are three QRadioButton instances. The
+    active radio button specifies the image to show.
+
+    \section1 Portrait UI
+
+    When the device is in portrait mode, it usually means that the user holds
+    it with one hand, and can comfortably use the thumb for small amounts of
+    input. The layout is simpler, and is focused on consuming content. The
+    portrait UI looks like this:
+
+    \image orientation-portrait-ui.png The portrait UI
+
+    Similarly, it contains a QWidget, also called \c choiceWidget, that will
+    show the current image. In contrast to the landscape UI, this one doesn't
+    provide any controls to change the image.
+
+    \section1 MainWindow Class Definition
+
+    \c MainWindow inherits from QWidget and acts as the top level widget of the
+    application.
+
+    \snippet widgets/orientation/mainwindow.h 0
+
+    The \c resizeEvent() method is re-implemented, and used to check which
+    UI to show. The \c onRadioButtonClicked() slot is connected to the
+    landscape UI's radio button group and selects the current image.
+
+    \c landscapeWidget and \c portraitWidget will contain the UI layouts. Only
+    one of them is visible at a time.
+
+    \section1 MainWindow Class Implementation
+
+    In the constructor, the widgets that will hold the UIs are created and set
+    up.
+
+    \snippet widgets/orientation/mainwindow.cpp 0
+
+    Since the exit buttons on the layouts are different from each other, both
+    of them have to have their \c clicked() signal connected to the \c close()
+    slot of the main widget. The first image is also made current with the call
+    to \c onRadioButtonClicked().
+
+    \snippet widgets/orientation/mainwindow.cpp 1
+
+    On the Maemo platform, windows are stuck in landscape mode by default. The
+    application has to explicitly say that rotation is supported.
+
+    \snippet widgets/orientation/mainwindow.cpp 2
+
+    The \c resizeEvent() is called when the main window is first created, and
+    also whenever the window has been resized. If the window is shown in
+    full screen, this is an indication that the orientation of the screen has
+    changed.
+
+    The dimensions of \c landscapeWidget is the transpose of the dimensions of
+    \c portraitWidget. When the orientation is known, both are set to the
+    (possibly transposed) size of the window. Depending on the orientation, one
+    widget is made visible and the other invisible.
+
+    \snippet widgets/orientation/mainwindow.cpp 3
+
+    When the user selects one of the radio buttons in the landscape UI, the
+    current image is changed. The image is displayed by specifying the
+    background style of the choice widget. Since both \c portrait and
+    \c landscape have a \c choiceWidget of their own, the change has to be
+    reflected in both instances.
+
+    \snippet widgets/orientation/mainwindow.cpp 4
+
+    Synchronizing both UIs like this might become unfeasible when there are
+    many things that can change. In that case it is better to make use of the
+    \l{Introduction to Model/View Programming}{Model-View-Controller pattern}
+    more extensively and share the content between both portrait and landscape
+    widgets. Then an interface for displaying and manipulating it can be tailor
+    made for both orientations.
+
+    \section1 The \c main() Function
+
+    The main function creates a \c MainWindow instance and shows it full
+    screen.
+    \snippet widgets/orientation/main.cpp 0
+*/