|
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 */ |