Merge remote branch 'qt/4.6' into kinetic-declarativeui

12 files changed, 257 insertions, 22 deletions

diff --git a/doc/src/examples/googlesuggest.qdoc b/doc/src/examples/googlesuggest.qdoc
index bec242d..ab8ab57 100644
--- a/doc/src/examples/googlesuggest.qdoc
+++ b/doc/src/examples/googlesuggest.qdoc
@@ -43,10 +43,152 @@
     \example network/googlesuggest
     \title Google Suggest Example
 
-    The Google Suggest example shows how to use the network access manager
-    to get the list of suggested search terms from Google.
+    The Google Suggest example demonstrates how to use the QNetworkAccessManager
+    class to obtain a list of suggestions from the Google search engine as the 
+    user types into a QLineEdit.
 
     \image googlesuggest-example.png
 
-    \note The Google Suggest suggestion service is a registered trademark of Google Inc.
+    The application makes use of the \c get function in
+    QNetworkAccessManager to post a request and obtain the result of the search
+    query sent to the Google search engine. The results returned are listed as
+    clickable links appearing below the search box as a drop-down menu.
+
+    The widget is built up by a QLineEdit as the search box, and a QTreeView
+    used as a popup menu below the search box.
+
+    \section1 GSuggestCompletion Class Declaration
+
+    This class implements an event filter and a number of functions to display
+    the search results and to determent when and how to perform the search.
+
+    \snippet examples/network/googlesuggest/googlesuggest.h 1
+
+    The class connects to a QLineEdit and uses a QTreeWidget to display the
+    results. A QTimer controls the start of the network requests that are
+    executed using a QNetworkAccessManager.
+
+    \section1 GSuggestCompletion Class Implementation
+
+    We start by defining a constant containing the URL to be used in the Google
+    queries. This is the basis for the query. The letters typed into the search
+    box will be added to the query to perform the search itself.
+
+    \snippet examples/network/googlesuggest/googlesuggest.cpp 1
+
+    In the constructor, we set the parent of this GSuggestCompletion instance
+    to be the QLineEdit passed in. For simplicity, the QLineEdit is also stored
+    in the explicit \c editor member variable.
+
+    We then create a QTreeWidget as a toplevel widget and configure the various
+    properties to give it the look of a popup widget.
+
+    The popup will be populated by the results returned from Google. We set
+    the number of columns to be two, since we want to display both the
+    suggested search term and the number of hits it will trigger in the search
+    engine.
+
+    Furthermore, we install the GSuggestCompletion instance as an event filter
+    on the QTreeWidget, and connect the \c itemClicked() signal with the \c
+    doneCompletion() slot.
+
+    A single-shot QTimer is used to start the request when the user has stopped
+    typing for 500 ms.
+
+    Finally, we connect the networkManagers \c finished() signal with the \c
+    handleNetworkData() slot to handle the incoming data.
+
+    \snippet examples/network/googlesuggest/googlesuggest.cpp 2
+
+    Since the QTreeWidget popup has been instantiated as a toplevel widget, the
+    destructor has to delete it explicitly from memory to avoid a memory leak.
+
+    \snippet examples/network/googlesuggest/googlesuggest.cpp 3
+
+    The event filter handles mouse press and key press events that are
+    delivered to the popup. For mouse press events we just hide the popup and
+    return focus to the editor widget, and then return true to prevent further
+    event processing.
+
+    Key event handling is implemented so that Enter and Return execute the
+    selected link, while the Escape key hides the popup. Sine we want to be
+    able to navigate the list of suggestions using the different navigation
+    keys on the keyboard we let Qt continue regular event processing for those
+    by returning false from the eventFilter reimplementation.
+
+    For all other keys, the event will be passed on to the editor widget and the
+    popup is hidden. This way the user's typing will not be interrupted by the
+    popping up of the completion list.
+
+    \snippet examples/network/googlesuggest/googlesuggest.cpp 4
+
+    The \c showCompletion() function populates the QTreeWidget with the results
+    returned from the query. It takes two QStringLists, one with the suggested
+    search terms and the other with the corresponding number of hits.
+
+    \snippet examples/network/googlesuggest/googlesuggest.cpp 5
+
+    A QTreeWidgetItem is created for each index in the list and inserted into
+    the QTreeWidget. Finally, we adjust position and size of the popup to make
+    sure that it pops up in the correct position below the editor, and show it.
+
+    The \c doneCompletion() function, which is called by the event filter when
+    either Enter or Return keys are pressed, stops the timer to prevent further
+    requests and passes the text of the selected item to the editor. We then
+    make the \c editor QLineEdit emit the returnPressed() signal, to which the
+    application can connect to open the respective web page.
+
+    \snippet examples/network/googlesuggest/googlesuggest.cpp 6
+
+    The \c autoSuggest() slot is called when the timer times out, and uses the
+    text in the editor to build the complete search query. The query is then
+    passed to the QNetworkAccessManager's \c get() function to start the
+    request.
+
+    \snippet examples/network/googlesuggest/googlesuggest.cpp 7
+
+    The function \c preventSuggest() stops the timer to prevent further
+    requests from being started.
+
+    \snippet examples/network/googlesuggest/googlesuggest.cpp 8
+
+    When the network request is finished, the QNetworkAccessManager delivers the
+    data received from the server through the networkReply object.
+
+    \snippet examples/network/googlesuggest/googlesuggest.cpp 9
+
+    To extract the data from the reply we use the \c readAll() function, which
+    is inherited from QIODevice and returns a QByteArray. Since this data is
+    encoded in XML we can use a QXmlStreamReader to traverse the data and
+    extract the search result as QStrings, which we can stream into two
+    QStringLists used to populate the popup.
+
+    Finally, we schedule the QNetworkReply object for deletion using the \c
+    deleteLater function.
+
+    \section1 SearchBox Class Declaration
+
+    The SearchBox class inherits QLineEdit and adds the protected slot \c
+    doSearch().
+
+    A \c GSuggestCompletion member provides the SearchBox with the request
+    functionality and the suggestions returned from the Google search engine.
+
+    \snippet examples/network/googlesuggest/searchbox.h 1
+
+    \section1 SearchBox Class Implementation
+
+    The search box constructor instantiates the GSuggestCompletion object and
+    connects the returnPressed() signal to the doSearch() slot.
+
+    \snippet examples/network/googlesuggest/searchbox.cpp 1
+
+    The function \c doSearch() stops the completer from sending any further
+    queries to the search engine.
+
+    Further, the function extracts the selected search phrase and opens it
+    in the default web browser using QDesktopServices.
+
+    \snippet examples/network/googlesuggest/searchbox.cpp 2
+
 */
diff --git a/doc/src/getting-started/installation.qdoc b/doc/src/getting-started/installation.qdoc
index 1eefed3..c8e225c 100644
--- a/doc/src/getting-started/installation.qdoc
+++ b/doc/src/getting-started/installation.qdoc
@@ -39,10 +39,6 @@
 **
 ****************************************************************************/
 
-/****************************************************************************
-** Please remember to update the corresponding INSTALL files.
-****************************************************************************/
-
 /*!
 \group installation
 \title Installation
@@ -484,6 +480,7 @@ in the \l{Qt for Windows CE Requirements} document.
         \o \l{Windows CE - Introduction to using Qt}
         \o \l{Windows CE - Working with Custom SDKs}
         \o \l{Windows CE - Using shadow builds}
+        \o \l{Windows CE - Signing}
         \endlist
 
         Information on feature and performance tuning for embedded builds can
diff --git a/doc/src/images/googlesuggest-example.png b/doc/src/images/googlesuggest-example.png
index 4ef072a..477d444 100644
--- a/doc/src/images/googlesuggest-example.png
+++ b/doc/src/images/googlesuggest-example.png
diff --git a/doc/src/images/graphicseffect-bloom.png b/doc/src/images/graphicseffect-bloom.png
deleted file mode 100644
index dace7eb..0000000
--- a/doc/src/images/graphicseffect-bloom.png
+++ /dev/null
diff --git a/doc/src/images/graphicseffect-effects.png b/doc/src/images/graphicseffect-effects.png
deleted file mode 100644
index 609bef9..0000000
--- a/doc/src/images/graphicseffect-effects.png
+++ /dev/null
diff --git a/doc/src/images/graphicseffect-grayscale.png b/doc/src/images/graphicseffect-grayscale.png
deleted file mode 100644
index 8b6e5c6..0000000
--- a/doc/src/images/graphicseffect-grayscale.png
+++ /dev/null
diff --git a/doc/src/images/graphicseffect-pixelize.png b/doc/src/images/graphicseffect-pixelize.png
deleted file mode 100644
index 57a0057..0000000
--- a/doc/src/images/graphicseffect-pixelize.png
+++ /dev/null
diff --git a/doc/src/images/hoverevents.png b/doc/src/images/hoverevents.png
new file mode 100644
index 0000000..ccc079b
--- /dev/null
+++ b/doc/src/images/hoverevents.png
diff --git a/doc/src/platforms/supported-platforms.qdoc b/doc/src/platforms/supported-platforms.qdoc
index 302ecb4..560ddfe 100644
--- a/doc/src/platforms/supported-platforms.qdoc
+++ b/doc/src/platforms/supported-platforms.qdoc
@@ -86,7 +86,7 @@
     \row    \o Apple Mac OS X 10.5 "Leopard" x86_64 (Carbon, Cocoa 32 and 64bit)
                                      \o As provided by Apple
     \row    \o Embedded Linux QWS (ARM)
-                                     \o gcc (\l{http:\\www.codesourcery.com}{Codesourcery version)}
+                                     \o gcc (\l{http://www.codesourcery.com/}{Codesourcery version)}
     \row    \o Windows CE 5.0 (ARMv4i, x86, MIPS)
                                      \o MSVC 2005 WinCE 5.0 Standard (x86, pocket, smart, mipsii)
     \row    \o Symbian (S60 3.1, 3.2 and 5.0)
@@ -125,7 +125,7 @@
     \row    \o Linux
                                      \o Intel Compiler
     \row    \o Embedded Linux QWS (Mips, PowerPC)
-                                     \o gcc (\l{http:\\www.codesourcery.com}{Codesourcery version)}
+                                     \o gcc (\l{http://www.codesourcery.com/}{Codesourcery version)}
     \row    \o Embedded Linux X11 (ARM)
                                      \o gcc (\l{http://www.scratchbox.org/}{Scratchbox)}
     \row    \o Windows CE 6.0 (ARMv4i, x86, MIPS)
diff --git a/doc/src/platforms/wince-signing.qdoc b/doc/src/platforms/wince-signing.qdoc
new file mode 100644
index 0000000..fa383b3
--- /dev/null
+++ b/doc/src/platforms/wince-signing.qdoc
@@ -0,0 +1,96 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page windowsce-signing.html
+    \ingroup qtce
+    \title Windows CE - Signing
+    \brief How to sign Qt projects for use with Windows CE.
+
+    \section1 Signing on Windows CE
+
+Windows CE provides a security mechanism to ask the user to confirm
+that they want to use an application/library that is unknown to the
+system. This process gets repeated for each dependency of an 
+application, meaning each library the application links to, which is
+not recognized yet.
+
+To simplify this process you can use signatures and certificates. A 
+certificate gets installed on the device and each file which is
+signed with the according certificate can be launched without the
+security warning.
+
+If you want to use signatures for your project written in Qt,
+configure provides the \c -signature option. You need to specify the
+location of the .pfx file and qmake adds the signing step to the
+build rules.
+
+If you need to select a separate signature for a specific project,
+or you only want to sign a single project, you can use the 
+"SIGNATURE_FILE = foo.pfx" rule inside the project file.
+
+The above described rules apply for command line makefiles as well as
+Visual Studio projects generated by qmake.
+
+Microsoft usually ships development signatures inside the SDK packages.
+You can find them in the Tools subdirectory of the SDK root folder.
+
+Example:
+
+\list
+\o Calling configure with signing enabled:
+\code
+configure.exe -platform win32-msvc2005 -xplatform wincewm50pocket-msvc2005 -signature C:\some\path\SDKSamplePrivDeveloper.pfx
+\endcode
+
+\o Using pro file to specify signature
+\code
+...
+TARGET = foo
+
+wince*: {
+   SIGNATURE_FILE = somepath\customSignature.pfx
+}
+...
+\endcode
+\endlist
+
+*/
diff --git a/doc/src/qt4-intro.qdoc b/doc/src/qt4-intro.qdoc
index 4911426..2f74451 100644
--- a/doc/src/qt4-intro.qdoc
+++ b/doc/src/qt4-intro.qdoc
@@ -608,19 +608,19 @@
     \section1 Graphics Effects
 
     Effects can be used to alter the appearance of UI elements such as
-    \l{QGraphicsItem}s and \l{QWidget}s. A range of standard effects such
-    as blurring, colorizing or blooming is provided, and it is possible to
-    implement custom effects.
+    \l{QGraphicsItem}s and \l{QWidget}s. A couple of standard effects such
+    as blurring, colorizing and drop shadow are provided, and it is
+    possible to implement custom effects.
 
     \table
     \row
-    \o
-    \o \img graphicseffect-plain.png
-    \o
+    \o{2,1} \img graphicseffect-plain.png
     \row
     \o \img graphicseffect-blur.png
     \o \img graphicseffect-colorize.png
-    \o \img graphicseffect-bloom.png
+    \row
+    \o \img graphicseffect-opacity.png
+    \o \img graphicseffect-drop-shadow.png
     \endtable
 
     See the QGraphicsEffect class documentation for more information.
diff --git a/doc/src/snippets/code/src_gui_effects_qgraphicseffect.cpp b/doc/src/snippets/code/src_gui_effects_qgraphicseffect.cpp
index 35689f4..5ef6609 100644
--- a/doc/src/snippets/code/src_gui_effects_qgraphicseffect.cpp
+++ b/doc/src/snippets/code/src_gui_effects_qgraphicseffect.cpp
@@ -40,11 +40,11 @@
 ****************************************************************************/
 
 //! [0]
-MyGraphicsOpacityEffect::draw(QPainter *painter, QGraphicsEffectSource *source)
+MyGraphicsOpacityEffect::draw(QPainter *painter)
 {
     // Fully opaque; draw directly without going through a pixmap.
     if (qFuzzyCompare(m_opacity, 1)) {
-        source->draw(painter);
+        drawSource(painter);
         return;
     }
     ...
@@ -52,18 +52,18 @@ MyGraphicsOpacityEffect::draw(QPainter *painter, QGraphicsEffectSource *source)
 //! [0]
 
 //! [1]
-MyGraphicsEffect::draw(QPainter *painter, QGraphicsEffectSource *source)
+MyGraphicsEffect::draw(QPainter *painter)
 {
     ...
     QPoint offset;
-    if (source->isPixmap()) {
+    if (sourceIsPixmap()) {
         // No point in drawing in device coordinates (pixmap will be scaled anyways).
-        const QPixmap pixmap = source->pixmap(Qt::LogicalCoordinates, &offset);
+        const QPixmap pixmap = sourcePixmap(Qt::LogicalCoordinates, &offset);
         ...
         painter->drawPixmap(offset, pixmap);
     } else {
         // Draw pixmap in device coordinates to avoid pixmap scaling;
-        const QPixmap pixmap = source->pixmap(Qt::DeviceCoordinates, &offset);
+        const QPixmap pixmap = sourcePixmap(Qt::DeviceCoordinates, &offset);
         painter->setWorldTransform(QTransform());
         ...
         painter->drawPixmap(offset, pixmap);