From c457aebbba18c5431915a664a02264fae96cc848 Mon Sep 17 00:00:00 2001 From: Morten Engvoldsen Date: Mon, 9 Nov 2009 13:34:44 +0100 Subject: Doc: updated documentation for Google Suggest Example Documented the Google Suggest Example. Adding descriptions and screenshot. and correcting indent Task-number: QT-700 Rev-by: Volker Hilsheimer --- doc/src/examples/googlesuggest.qdoc | 192 ++++++++++++++++++------------------ 1 file changed, 96 insertions(+), 96 deletions(-) diff --git a/doc/src/examples/googlesuggest.qdoc b/doc/src/examples/googlesuggest.qdoc index f3693e9..ab8ab57 100644 --- a/doc/src/examples/googlesuggest.qdoc +++ b/doc/src/examples/googlesuggest.qdoc @@ -50,145 +50,145 @@ \image googlesuggest-example.png 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. + 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. + 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 + \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. + 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 + \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. + 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 + \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. + 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 + \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. + 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. + 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. + 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. + 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. + 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. + 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 + \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. + 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 + \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. + 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. + 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. + 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 + \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. + 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 + \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. + 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. + 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 + \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. + 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 + \snippet examples/network/googlesuggest/googlesuggest.cpp 7 -The function \c preventSuggest() stops the timer to prevent further -requests from being started. + The function \c preventSuggest() stops the timer to prevent further + requests from being started. -\snippet examples/network/googlesuggest/googlesuggest.cpp 8 + \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. + 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 + \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. + 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. + Finally, we schedule the QNetworkReply object for deletion using the \c + deleteLater function. -\section1 SearchBox Class Declaration + \section1 SearchBox Class Declaration -The SearchBox class inherits QLineEdit and adds the protected slot \c -doSearch(). + 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. + 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 + \snippet examples/network/googlesuggest/searchbox.h 1 -\section1 SearchBox Class Implementation + \section1 SearchBox Class Implementation -The search box constructor instantiates the GSuggestCompletion object and -connects the returnPressed() signal to the doSearch() slot. + The search box constructor instantiates the GSuggestCompletion object and + connects the returnPressed() signal to the doSearch() slot. -\snippet examples/network/googlesuggest/searchbox.cpp 1 + \snippet examples/network/googlesuggest/searchbox.cpp 1 -The function \c doSearch() stops the completer from sending any further -queries to the search engine. + 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. + 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 + \snippet examples/network/googlesuggest/searchbox.cpp 2 */ -- cgit v0.12