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