1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \example network/googlesuggest

    44     \title Google Suggest Example

    45 

    46     The Google Suggest example demonstrates how to use the QNetworkAccessManager

    47     class to obtain a list of suggestions from the Google search engine as the 

    48     user types into a QLineEdit.

    49 

    50     \image googlesuggest-example.png

    51 

    52     The application makes use of the \c get function in

    53     QNetworkAccessManager to post a request and obtain the result of the search

    54     query sent to the Google search engine. The results returned are listed as

    55     clickable links appearing below the search box as a drop-down menu.

    56 

    57     The widget is built up by a QLineEdit as the search box, and a QTreeView

    58     used as a popup menu below the search box.

    59 

    60     \section1 GSuggestCompletion Class Declaration

    61 

    62     This class implements an event filter and a number of functions to display

    63     the search results and to determent when and how to perform the search.

    64 

    65     \snippet examples/network/googlesuggest/googlesuggest.h 1

    66 

    67     The class connects to a QLineEdit and uses a QTreeWidget to display the

    68     results. A QTimer controls the start of the network requests that are

    69     executed using a QNetworkAccessManager.

    70 

    71     \section1 GSuggestCompletion Class Implementation

    72 

    73     We start by defining a constant containing the URL to be used in the Google

    74     queries. This is the basis for the query. The letters typed into the search

    75     box will be added to the query to perform the search itself.

    76 

    77     \snippet examples/network/googlesuggest/googlesuggest.cpp 1

    78 

    79     In the constructor, we set the parent of this GSuggestCompletion instance

    80     to be the QLineEdit passed in. For simplicity, the QLineEdit is also stored

    81     in the explicit \c editor member variable.

    82 

    83     We then create a QTreeWidget as a toplevel widget and configure the various

    84     properties to give it the look of a popup widget.

    85 

    86     The popup will be populated by the results returned from Google. We set

    87     the number of columns to be two, since we want to display both the

    88     suggested search term and the number of hits it will trigger in the search

    89     engine.

    90 

    91     Furthermore, we install the GSuggestCompletion instance as an event filter

    92     on the QTreeWidget, and connect the \c itemClicked() signal with the \c

    93     doneCompletion() slot.

    94 

    95     A single-shot QTimer is used to start the request when the user has stopped

    96     typing for 500 ms.

    97 

    98     Finally, we connect the networkManagers \c finished() signal with the \c

    99     handleNetworkData() slot to handle the incoming data.

   100 

   101     \snippet examples/network/googlesuggest/googlesuggest.cpp 2

   102 

   103     Since the QTreeWidget popup has been instantiated as a toplevel widget, the

   104     destructor has to delete it explicitly from memory to avoid a memory leak.

   105 

   106     \snippet examples/network/googlesuggest/googlesuggest.cpp 3

   107 

   108     The event filter handles mouse press and key press events that are

   109     delivered to the popup. For mouse press events we just hide the popup and

   110     return focus to the editor widget, and then return true to prevent further

   111     event processing.

   112 

   113     Key event handling is implemented so that Enter and Return execute the

   114     selected link, while the Escape key hides the popup. Since we want to be

   115     able to navigate the list of suggestions using the different navigation

   116     keys on the keyboard we let Qt continue regular event processing for those

   117     by returning false from the eventFilter reimplementation.

   118 

   119     For all other keys, the event will be passed on to the editor widget and the

   120     popup is hidden. This way the user's typing will not be interrupted by the

   121     popping up of the completion list.

   122 

   123     \snippet examples/network/googlesuggest/googlesuggest.cpp 4

   124 

   125     The \c showCompletion() function populates the QTreeWidget with the results

   126     returned from the query. It takes two QStringLists, one with the suggested

   127     search terms and the other with the corresponding number of hits.

   128 

   129     \snippet examples/network/googlesuggest/googlesuggest.cpp 5

   130 

   131     A QTreeWidgetItem is created for each index in the list and inserted into

   132     the QTreeWidget. Finally, we adjust position and size of the popup to make

   133     sure that it pops up in the correct position below the editor, and show it.

   134 

   135     The \c doneCompletion() function, which is called by the event filter when

   136     either Enter or Return keys are pressed, stops the timer to prevent further

   137     requests and passes the text of the selected item to the editor. We then

   138     make the \c editor QLineEdit emit the returnPressed() signal, to which the

   139     application can connect to open the respective web page.

   140 

   141     \snippet examples/network/googlesuggest/googlesuggest.cpp 6

   142 

   143     The \c autoSuggest() slot is called when the timer times out, and uses the

   144     text in the editor to build the complete search query. The query is then

   145     passed to the QNetworkAccessManager's \c get() function to start the

   146     request.

   147 

   148     \snippet examples/network/googlesuggest/googlesuggest.cpp 7

   149 

   150     The function \c preventSuggest() stops the timer to prevent further

   151     requests from being started.

   152 

   153     \snippet examples/network/googlesuggest/googlesuggest.cpp 8

   154 

   155     When the network request is finished, the QNetworkAccessManager delivers the

   156     data received from the server through the networkReply object.

   157 

   158     \snippet examples/network/googlesuggest/googlesuggest.cpp 9

   159 

   160     To extract the data from the reply we use the \c readAll() function, which

   161     is inherited from QIODevice and returns a QByteArray. Since this data is

   162     encoded in XML we can use a QXmlStreamReader to traverse the data and

   163     extract the search result as QStrings, which we can stream into two

   164     QStringLists used to populate the popup.

   165 

   166     Finally, we schedule the QNetworkReply object for deletion using the \c

   167     deleteLater function.

   168 

   169     \section1 SearchBox Class Declaration

   170 

   171     The SearchBox class inherits QLineEdit and adds the protected slot \c

   172     doSearch().

   173 

   174     A \c GSuggestCompletion member provides the SearchBox with the request

   175     functionality and the suggestions returned from the Google search engine.

   176 

   177     \snippet examples/network/googlesuggest/searchbox.h 1

   178 

   179     \section1 SearchBox Class Implementation

   180 

   181     The search box constructor instantiates the GSuggestCompletion object and

   182     connects the returnPressed() signal to the doSearch() slot.

   183 

   184     \snippet examples/network/googlesuggest/searchbox.cpp 1

   185 

   186     The function \c doSearch() stops the completer from sending any further

   187     queries to the search engine.

   188 

   189     Further, the function extracts the selected search phrase and opens it

   190     in the default web browser using QDesktopServices.

   191 

   192     \snippet examples/network/googlesuggest/searchbox.cpp 2

   193 

   194 */