/**************************************************************************** ** ** Copyright (c) 2012 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of Qt Creator ** ** ** GNU Free Documentation License ** ** Alternatively, this file may be used under the terms of the GNU Free ** Documentation License version 1.3 as published by the Free Software ** Foundation and appearing in the file included in the packaging of this ** file. ** ** ****************************************************************************/ // ********************************************************************** // NOTE: the sections are not ordered by their logical order to avoid // reshuffling the file each time the index order changes (i.e., often). // Run the fixnavi.pl script to adjust the links to the index order. // ********************************************************************** /*! \contentspage index.html \previouspage creator-qml-application.html \page creator-writing-program.html \nextpage creator-project-managing.html \title Creating a Qt Widget Based Application This tutorial describes how to use \QC to create a small Qt application, Text Finder. It is a simplified version of the QtUiTools \l{http://qt-project.org/doc/qt-4.8/uitools-textfinder.html}{Text Finder} example. The application user interface is constructed from Qt widgets by using \QD. The application logic is written in C++ by using the code editor. \image qtcreator-textfinder-screenshot.png \section1 Creating the Text Finder Project \list 1 \o Select \gui{File > New File or Project > Applications > Qt Gui Application > Choose}. \image qtcreator-new-qt-gui-application.png "New File or Project dialog" The \gui{Introduction and Project Location} dialog opens. \image qtcreator-intro-and-location-qt-gui.png "Introduction and Project Location dialog" \o In the \gui{Name} field, type \bold {TextFinder}. \o In the \gui {Create in} field, enter the path for the project files. For example, \c {C:\Qt\examples}, and then click \gui{Next} (on Windows and Linux) or \gui Continue (on Mac OS). The \gui {Kit Selection} dialog opens. \image qtcreator-new-project-qt-versions-qt-gui.png "Kit Selection dialog" \o Select build and run \l{glossary-buildandrun-kit}{kits} for your project, and click \gui Next or \gui Continue. \note If only one kit is specified in \gui Tools > \gui Options > \gui {Build & Run} > \gui Kits, this dialog is skipped. The \gui{Class Information} dialog opens. \image qtcreator-class-info-qt-gui.png "Class Information dialog" \o In the \gui{Class name} field, type \bold {TextFinder} as the class name. \o In the \gui{Base class} list, select \bold {QWidget} as the base class type. \note The \gui{Header file}, \gui{Source file} and \gui{Form file} fields are automatically updated to match the name of the class. \o Click \gui Next or \gui Continue. The \gui{Project Management} dialog opens. \image qtcreator-new-project-summary-qt-gui.png "Project Management dialog" \o Review the project settings, and click \gui{Finish} (on Windows and Linux) or \gui Done (on Mac OS) to create the project. \endlist \note The project opens in the \gui Edit mode, and these instructions are hidden. To return to these instructions, open the \gui Help mode. The TextFinder project now contains the following files: \list \o textfinder.h \o textfinder.cpp \o main.cpp \o textfinder.ui \o textfinder.pro \endlist \image qtcreator-textfinder-contents.png "TextFinder project contents" The .h and .cpp files come with the necessary boiler plate code. The .pro file is complete. \section1 Filling in the Missing Pieces Begin by designing the user interface and then move on to filling in the missing code. Finally, add the find functionality. \section2 Designing the User Interface \image qtcreator-textfinder-ui.png "Text Finder UI" \list 1 \o In the \gui{Editor} mode, double-click the textfinder.ui file in the \gui{Projects} view to launch the integrated \QD. \o Drag and drop the following widgets to the form: \list \o \gui{Label} (QLabel) \o \gui{Line Edit} (QLineEdit) \o \gui{Push Button} (QPushButton) \endlist \image qtcreator-textfinder-ui-widgets.png "Adding widgets to Text Finder UI" \note To easily locate the widgets, use the search box at the top of the \gui Sidebar. For example, to find the \gui Label widget, start typing the word \bold label. \image qtcreator-texfinder-filter.png "Filter field" \o Double-click the \gui{Label} widget and enter the text \bold{Keyword}. \o Double-click the \gui{Push Button} widget and enter the text \bold{Find}. \o In the \gui Properties pane, change the \gui objectName to \bold findButton. \image qtcreator-textfinder-objectname.png "Changing object names" \o Press \key {Ctrl+A} (or \key {Cmd+A}) to select the widgets and click \gui{Lay out Horizontally} (or press \gui{Ctrl+H} on Linux or Windows or \key {Ctrl+Shift+H} on Mac OS) to apply a horizontal layout (QHBoxLayout). \image qtcreator-texfinder-ui-horizontal-layout.png "Applying horizontal layout" \o Drag and drop a \gui{Text Edit} widget (QTextEdit) to the form. \o Select the screen area and click \gui{Lay out Vertically} (or press \gui{Ctrl+L}) to apply a vertical layout (QVBoxLayout). \image qtcreator-textfinder-ui.png "Text Finder UI" Applying the horizontal and vertical layouts ensures that the application UI scales to different screen sizes. \o To call a find function when users press the \gui Find button, you use the Qt signals and slots mechanism. A signal is emitted when a particular event occurs and a slot is a function that is called in response to a particular signal. Qt widgets have predefined signals and slots that you can use directly from \QD. To add a slot for the find function: \list \o Right-click the \gui Find button to open a context-menu. \o Select \gui {Go to Slot > clicked()}, and then select \gui OK. A private slot, \c{on_findButton_clicked()}, is added to the header file, textfinder.h and a private function, \c{TextFinder::on_findButton_clicked()}, is added to the source file, textfinder.cpp. \endlist \o Press \gui{Ctrl+S} (or \key {Cmd+S}) to save your changes. \endlist For more information about designing forms with \QD, see the \l{http://qt-project.org/doc/qt-4.8/designer-manual.html}{Qt Designer Manual}. \section2 Completing the Header File The textfinder.h file already has the necessary #includes, a constructor, a destructor, and the \c{Ui} object. You need to add a private function, \c{loadTextFile()}, to read and display the contents of the input text file in the QTextEdit. \list 1 \o In the \gui{Projects} pane in the \gui {Edit view}, double-click the \c{textfinder.h} file to open it for editing. \o Add a private function to the \c{private} section, after the \c{Ui::TextFinder} pointer, as illustrated by the following code snippet: \snippet textfinder/textfinder.h 0 \endlist \section2 Completing the Source File Now that the header file is complete, move on to the source file, textfinder.cpp. \list 1 \o In the \gui{Projects} pane in the \gui Edit view, double-click the textfinder.cpp file to open it for editing. \o Add code to load a text file using QFile, read it with QTextStream, and then display it on \c{textEdit} with \l{http://qt-project.org/doc/qt-4.8/qtextedit.html#plainText-prop} {setPlainText()}. This is illustrated by the following code snippet: \snippet textfinder/textfinder.cpp 0 \o To use QFile and QTextStream, add the following #includes to textfinder.cpp: \snippet textfinder/textfinder.cpp 1 \o For the \c{on_findButton_clicked()} slot, add code to extract the search string and use the \l{http://qt-project.org/doc/qt-4.8/qtextedit.html#find}{find()} function to look for the search string within the text file. This is illustrated by the following code snippet: \snippet textfinder/textfinder.cpp 2 \o Once both of these functions are complete, add a line to call \c{loadTextFile()} in the constructor, as illustrated by the following code snippet: \snippet textfinder/textfinder.cpp 3 \endlist The \c{on_findButton_clicked()} slot is called automatically in the uic generated ui_textfinder.h file by this line of code: \code QMetaObject::connectSlotsByName(TextFinder); \endcode \section2 Creating a Resource File You need a resource file (.qrc) within which you embed the input text file. The input file can be any .txt file with a paragraph of text. Create a text file called input.txt and store it in the textfinder folder. To add a resource file: \list 1 \o Select \gui{File > New File or Project > Qt > Qt Resource File > Choose}. \image qtcreator-add-resource-wizard.png "New File or Project dialog" The \gui {Choose the Location} dialog opens. \image qtcreator-add-resource-wizard2.png "Choose the Location dialog" \o In the \gui{Name} field, enter \bold{textfinder}. \o In the \gui{Path} field, enter \c{C:\Qt\examples\TextFinder}, and click \gui Next or \gui Continue. The \gui{Project Management} dialog opens. \image qtcreator-add-resource-wizard3.png "Project Management dialog" \o In the \gui{Add to project} field, select \bold{TextFinder.pro} and click \gui{Finish} or \gui Done to open the file in the code editor. \o Select \gui{Add > Add Prefix}. \o In the \gui{Prefix} field, replace the default prefix with a slash (/). \o Select \gui{Add > Add Files}, to locate and add input.txt. \image qtcreator-add-resource.png "Editing resource files" \endlist \section1 Compiling and Running Your Program Now that you have all the necessary files, click the \inlineimage qtcreator-run.png button to compile and run your program. */