source: trunk/doc/src/examples/googlesuggest.qdoc@ 624

Last change on this file since 624 was 561, checked in by Dmitry A. Kuminov, 16 years ago

trunk: Merged in qt 4.6.1 sources.
  • Property svn:eol-style set to native
File size: 8.5 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 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** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and Nokia.
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** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you have questions regarding the use of this file, please contact
37** Nokia at qt-info@nokia.com.
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. Sine 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*/
Note: See TracBrowser for help on using the repository browser.