--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/textfinder.qdoc Thu Apr 08 14:19:33 2010 +0300
@@ -0,0 +1,173 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \example uitools/textfinder
+ \title Text Finder Example
+
+ The Text Finder example demonstrates how to dynamically process forms
+ using the QtUiTools module. Dynamic form processing enables a form to
+ be processed at run-time only by changing the UI file for the project.
+ The program allows the user to look up a particular word within the
+ contents of a text file. This text file is included in the project's
+ resource and is loaded into the display at startup.
+
+ \table
+ \row \o \inlineimage textfinder-example-find.png
+ \o \inlineimage textfinder-example-find2.png
+ \endtable
+
+ \section1 Setting Up The Resource File
+
+ The resources required for Text Finder are:
+ \list
+ \o \e{textfinder.ui} - the user interface file created in QtDesigner
+ \o \e{input.txt} - a text file containing some text to be displayed
+ in the QTextEdit
+ \endlist
+
+ \e{textfinder.ui} contains all the necessary QWidget objects for the
+ Text Finder. A QLineEdit is used for the user input, a QTextEdit is
+ used to display the contents of \e{input.txt}, a QLabel is used to
+ display the text "Keyword", and a QPushButton is used for the "Find"
+ button. The screenshot below shows the preview obtained in QtDesigner.
+
+ \image textfinder-example-userinterface.png
+
+ A \e{textfinder.qrc} file is used to store both the \e{textfinder.ui}
+ and \e{input.txt} in the application's executable. The file contains
+ the following code:
+
+ \quotefile examples/uitools/textfinder/textfinder.qrc
+
+ For more information on resource files, see \l{The Qt Resource System}.
+
+ To generate a form at run-time, the example is linked against the
+ QtUiTools module library. This is done in the \c{textfinder.pro} file
+ that contains the following lines:
+
+ \snippet doc/src/snippets/code/doc_src_examples_textfinder.qdoc 0
+
+ \section1 TextFinder Class Definition
+
+ The \c TextFinder class is a subclass of QWidget and it hosts the
+ \l{QWidget}s we need to access in the user interface. The QLabel in the
+ user interface is not declared here as we do not need to access it.
+
+ \snippet examples/uitools/textfinder/textfinder.h 0
+
+ The slot \c{on_find_Button_clicked()} is a slot named according to the
+ \l{Using a Designer UI File in Your Application#Automatic Connections}
+ {Automatic Connection} naming convention required
+ by \c uic.
+
+ \section1 TextFinder Class Implementation
+
+ The \c TextFinder class's constructor calls the \c loadUiFile() function
+ and then uses \c qFindChild() to access the user interface's
+ \l{QWidget}s.
+
+ \snippet examples/uitools/textfinder/textfinder.cpp 0
+
+ We then use QMetaObject's system to enable signal and slot connections.
+
+ \snippet examples/uitools/textfinder/textfinder.cpp 2
+
+ The loadTextFile() function is called to load \c{input.txt} into
+ QTextEdit to displays its contents.
+
+ \snippet examples/uitools/textfinder/textfinder.cpp 3a
+
+ The \c{TextFinder}'s layout is set with \l{QWidget::}{setLayout()}.
+
+ \snippet examples/uitools/textfinder/textfinder.cpp 3b
+
+ Finally, the window title is set to \e {Text Finder} and \c isFirstTime is
+ set to true.
+
+ \c isFirstTime is used as a flag to indicate whether the search operation
+ has been performed more than once. This is further explained with the
+ \c{on_findButton_clicked()} function.
+
+ The \c{loadUiFile()} function is used to load the user interface file
+ previously created in QtDesigner. The QUiLoader class is instantiated
+ and its \c load() function is used to load the form into \c{formWidget}
+ that acts as a place holder for the user interface. The function then
+ returns \c{formWidget} to its caller.
+
+ \snippet examples/uitools/textfinder/textfinder.cpp 4
+
+ As mentioned earlier, the loadTextFile() function loads \e{input.txt}
+ into QTextEdit to display its contents. Data is read using QTextStream
+ into a QString object, \c line with the QTextStream::readAll() function.
+ The contents of \c line are then appended to \c{ui_textEdit}.
+
+ \snippet examples/uitools/textfinder/textfinder.cpp 5
+
+ The \c{on_findButton_clicked()} function is a slot that is connected to
+ \c{ui_findButton}'s \c clicked() signal. The \c searchString is extracted
+ from the \c ui_lineEdit and the \c document is extracted from \c textEdit.
+ In event there is an empty \c searchString, a QMessageBox is used,
+ requesting the user to enter a word. Otherwise, we traverse through the
+ words in \c ui_textEdit, and highlight all ocurrences of the
+ \c searchString . Two QTextCursor objects are used: One to traverse through
+ the words in \c line and another to keep track of the edit blocks.
+
+ \snippet examples/uitools/textfinder/textfinder.cpp 7
+
+ The \c isFirstTime flag is set to false the moment \c findButton is
+ clicked. This is necessary to undo the previous text highlight before
+ highlighting the user's next search string. Also, the \c found flag
+ is used to indicate if the \c searchString was found within the contents
+ of \c ui_textEdit. If it was not found, a QMessageBox is used
+ to inform the user.
+
+ \snippet examples/uitools/textfinder/textfinder.cpp 9
+
+ \section1 \c main() Function
+
+ \snippet examples/uitools/textfinder/main.cpp 0
+
+ The \c main() function initialises the \e{textfinder.qrc} resource file
+ and instantiates as well as displays \c TextFinder.
+
+ \sa{Calculator Builder Example}, {World Time Clock Builder Example}
+ */