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

Last change on this file since 1168 was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.

  • Property svn:eol-style set to native
File size: 7.6 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:FDL$
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 a
14** written agreement between you and Nokia.
15**
16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at [email protected].
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \example network/googlesuggest
30 \title Google Suggest Example
31
32 The Google Suggest example demonstrates how to use the QNetworkAccessManager
33 class to obtain a list of suggestions from the Google search engine as the
34 user types into a QLineEdit.
35
36 \image googlesuggest-example.png
37
38 The application makes use of the \c get function in
39 QNetworkAccessManager to post a request and obtain the result of the search
40 query sent to the Google search engine. The results returned are listed as
41 clickable links appearing below the search box as a drop-down menu.
42
43 The widget is built up by a QLineEdit as the search box, and a QTreeView
44 used as a popup menu below the search box.
45
46 \section1 GSuggestCompletion Class Declaration
47
48 This class implements an event filter and a number of functions to display
49 the search results and to determent when and how to perform the search.
50
51 \snippet examples/network/googlesuggest/googlesuggest.h 1
52
53 The class connects to a QLineEdit and uses a QTreeWidget to display the
54 results. A QTimer controls the start of the network requests that are
55 executed using a QNetworkAccessManager.
56
57 \section1 GSuggestCompletion Class Implementation
58
59 We start by defining a constant containing the URL to be used in the Google
60 queries. This is the basis for the query. The letters typed into the search
61 box will be added to the query to perform the search itself.
62
63 \snippet examples/network/googlesuggest/googlesuggest.cpp 1
64
65 In the constructor, we set the parent of this GSuggestCompletion instance
66 to be the QLineEdit passed in. For simplicity, the QLineEdit is also stored
67 in the explicit \c editor member variable.
68
69 We then create a QTreeWidget as a toplevel widget and configure the various
70 properties to give it the look of a popup widget.
71
72 The popup will be populated by the results returned from Google. We set
73 the number of columns to be two, since we want to display both the
74 suggested search term and the number of hits it will trigger in the search
75 engine.
76
77 Furthermore, we install the GSuggestCompletion instance as an event filter
78 on the QTreeWidget, and connect the \c itemClicked() signal with the \c
79 doneCompletion() slot.
80
81 A single-shot QTimer is used to start the request when the user has stopped
82 typing for 500 ms.
83
84 Finally, we connect the networkManagers \c finished() signal with the \c
85 handleNetworkData() slot to handle the incoming data.
86
87 \snippet examples/network/googlesuggest/googlesuggest.cpp 2
88
89 Since the QTreeWidget popup has been instantiated as a toplevel widget, the
90 destructor has to delete it explicitly from memory to avoid a memory leak.
91
92 \snippet examples/network/googlesuggest/googlesuggest.cpp 3
93
94 The event filter handles mouse press and key press events that are
95 delivered to the popup. For mouse press events we just hide the popup and
96 return focus to the editor widget, and then return true to prevent further
97 event processing.
98
99 Key event handling is implemented so that Enter and Return execute the
100 selected link, while the Escape key hides the popup. Since we want to be
101 able to navigate the list of suggestions using the different navigation
102 keys on the keyboard we let Qt continue regular event processing for those
103 by returning false from the eventFilter reimplementation.
104
105 For all other keys, the event will be passed on to the editor widget and the
106 popup is hidden. This way the user's typing will not be interrupted by the
107 popping up of the completion list.
108
109 \snippet examples/network/googlesuggest/googlesuggest.cpp 4
110
111 The \c showCompletion() function populates the QTreeWidget with the results
112 returned from the query. It takes two QStringLists, one with the suggested
113 search terms and the other with the corresponding number of hits.
114
115 \snippet examples/network/googlesuggest/googlesuggest.cpp 5
116
117 A QTreeWidgetItem is created for each index in the list and inserted into
118 the QTreeWidget. Finally, we adjust position and size of the popup to make
119 sure that it pops up in the correct position below the editor, and show it.
120
121 The \c doneCompletion() function, which is called by the event filter when
122 either Enter or Return keys are pressed, stops the timer to prevent further
123 requests and passes the text of the selected item to the editor. We then
124 make the \c editor QLineEdit emit the returnPressed() signal, to which the
125 application can connect to open the respective web page.
126
127 \snippet examples/network/googlesuggest/googlesuggest.cpp 6
128
129 The \c autoSuggest() slot is called when the timer times out, and uses the
130 text in the editor to build the complete search query. The query is then
131 passed to the QNetworkAccessManager's \c get() function to start the
132 request.
133
134 \snippet examples/network/googlesuggest/googlesuggest.cpp 7
135
136 The function \c preventSuggest() stops the timer to prevent further
137 requests from being started.
138
139 \snippet examples/network/googlesuggest/googlesuggest.cpp 8
140
141 When the network request is finished, the QNetworkAccessManager delivers the
142 data received from the server through the networkReply object.
143
144 \snippet examples/network/googlesuggest/googlesuggest.cpp 9
145
146 To extract the data from the reply we use the \c readAll() function, which
147 is inherited from QIODevice and returns a QByteArray. Since this data is
148 encoded in XML we can use a QXmlStreamReader to traverse the data and
149 extract the search result as QStrings, which we can stream into two
150 QStringLists used to populate the popup.
151
152 Finally, we schedule the QNetworkReply object for deletion using the \c
153 deleteLater function.
154
155 \section1 SearchBox Class Declaration
156
157 The SearchBox class inherits QLineEdit and adds the protected slot \c
158 doSearch().
159
160 A \c GSuggestCompletion member provides the SearchBox with the request
161 functionality and the suggestions returned from the Google search engine.
162
163 \snippet examples/network/googlesuggest/searchbox.h 1
164
165 \section1 SearchBox Class Implementation
166
167 The search box constructor instantiates the GSuggestCompletion object and
168 connects the returnPressed() signal to the doSearch() slot.
169
170 \snippet examples/network/googlesuggest/searchbox.cpp 1
171
172 The function \c doSearch() stops the completer from sending any further
173 queries to the search engine.
174
175 Further, the function extracts the selected search phrase and opens it
176 in the default web browser using QDesktopServices.
177
178 \snippet examples/network/googlesuggest/searchbox.cpp 2
179
180*/
Note: See TracBrowser for help on using the repository browser.