diff options
Diffstat (limited to 'doc/src/examples/googlesuggest.qdoc')
| -rw-r--r-- | doc/src/examples/googlesuggest.qdoc | 148 |
1 files changed, 145 insertions, 3 deletions
diff --git a/doc/src/examples/googlesuggest.qdoc b/doc/src/examples/googlesuggest.qdoc index bec242d..ab8ab57 100644 --- a/doc/src/examples/googlesuggest.qdoc +++ b/doc/src/examples/googlesuggest.qdoc @@ -43,10 +43,152 @@ \example network/googlesuggest \title Google Suggest Example - The Google Suggest example shows how to use the network access manager - to get the list of suggested search terms from Google. + The Google Suggest example demonstrates how to use the QNetworkAccessManager + class to obtain a list of suggestions from the Google search engine as the + user types into a QLineEdit. \image googlesuggest-example.png - \note The Google Suggest suggestion service is a registered trademark of Google Inc. + The application makes use of the \c get function in + QNetworkAccessManager to post a request and obtain the result of the search + query sent to the Google search engine. The results returned are listed as + clickable links appearing below the search box as a drop-down menu. + + The widget is built up by a QLineEdit as the search box, and a QTreeView + used as a popup menu below the search box. + + \section1 GSuggestCompletion Class Declaration + + This class implements an event filter and a number of functions to display + the search results and to determent when and how to perform the search. + + \snippet examples/network/googlesuggest/googlesuggest.h 1 + + The class connects to a QLineEdit and uses a QTreeWidget to display the + results. A QTimer controls the start of the network requests that are + executed using a QNetworkAccessManager. + + \section1 GSuggestCompletion Class Implementation + + We start by defining a constant containing the URL to be used in the Google + queries. This is the basis for the query. The letters typed into the search + box will be added to the query to perform the search itself. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 1 + + In the constructor, we set the parent of this GSuggestCompletion instance + to be the QLineEdit passed in. For simplicity, the QLineEdit is also stored + in the explicit \c editor member variable. + + We then create a QTreeWidget as a toplevel widget and configure the various + properties to give it the look of a popup widget. + + The popup will be populated by the results returned from Google. We set + the number of columns to be two, since we want to display both the + suggested search term and the number of hits it will trigger in the search + engine. + + Furthermore, we install the GSuggestCompletion instance as an event filter + on the QTreeWidget, and connect the \c itemClicked() signal with the \c + doneCompletion() slot. + + A single-shot QTimer is used to start the request when the user has stopped + typing for 500 ms. + + Finally, we connect the networkManagers \c finished() signal with the \c + handleNetworkData() slot to handle the incoming data. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 2 + + Since the QTreeWidget popup has been instantiated as a toplevel widget, the + destructor has to delete it explicitly from memory to avoid a memory leak. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 3 + + The event filter handles mouse press and key press events that are + delivered to the popup. For mouse press events we just hide the popup and + return focus to the editor widget, and then return true to prevent further + event processing. + + Key event handling is implemented so that Enter and Return execute the + selected link, while the Escape key hides the popup. Sine we want to be + able to navigate the list of suggestions using the different navigation + keys on the keyboard we let Qt continue regular event processing for those + by returning false from the eventFilter reimplementation. + + For all other keys, the event will be passed on to the editor widget and the + popup is hidden. This way the user's typing will not be interrupted by the + popping up of the completion list. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 4 + + The \c showCompletion() function populates the QTreeWidget with the results + returned from the query. It takes two QStringLists, one with the suggested + search terms and the other with the corresponding number of hits. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 5 + + A QTreeWidgetItem is created for each index in the list and inserted into + the QTreeWidget. Finally, we adjust position and size of the popup to make + sure that it pops up in the correct position below the editor, and show it. + + The \c doneCompletion() function, which is called by the event filter when + either Enter or Return keys are pressed, stops the timer to prevent further + requests and passes the text of the selected item to the editor. We then + make the \c editor QLineEdit emit the returnPressed() signal, to which the + application can connect to open the respective web page. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 6 + + The \c autoSuggest() slot is called when the timer times out, and uses the + text in the editor to build the complete search query. The query is then + passed to the QNetworkAccessManager's \c get() function to start the + request. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 7 + + The function \c preventSuggest() stops the timer to prevent further + requests from being started. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 8 + + When the network request is finished, the QNetworkAccessManager delivers the + data received from the server through the networkReply object. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 9 + + To extract the data from the reply we use the \c readAll() function, which + is inherited from QIODevice and returns a QByteArray. Since this data is + encoded in XML we can use a QXmlStreamReader to traverse the data and + extract the search result as QStrings, which we can stream into two + QStringLists used to populate the popup. + + Finally, we schedule the QNetworkReply object for deletion using the \c + deleteLater function. + + \section1 SearchBox Class Declaration + + The SearchBox class inherits QLineEdit and adds the protected slot \c + doSearch(). + + A \c GSuggestCompletion member provides the SearchBox with the request + functionality and the suggestions returned from the Google search engine. + + \snippet examples/network/googlesuggest/searchbox.h 1 + + \section1 SearchBox Class Implementation + + The search box constructor instantiates the GSuggestCompletion object and + connects the returnPressed() signal to the doSearch() slot. + + \snippet examples/network/googlesuggest/searchbox.cpp 1 + + The function \c doSearch() stops the completer from sending any further + queries to the search engine. + + Further, the function extracts the selected search phrase and opens it + in the default web browser using QDesktopServices. + + \snippet examples/network/googlesuggest/searchbox.cpp 2 + */ |