qtdesigner-app-tutorial.qdoc 11.4 KB
Newer Older
1 2
/****************************************************************************
**
Eike Ziller's avatar
Eike Ziller committed
3 4
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing
5
**
hjk's avatar
hjk committed
6
** This file is part of Qt Creator
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
**
**
** 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.
// **********************************************************************

/*!
26
    \contentspage {Qt Creator Manual}
27
    \previouspage {Creating a Qt Quick Application}
28
    \page creator-writing-program.html
29
    \nextpage {Creating a Mobile Application}
30 31 32 33

    \title Creating a Qt Widget Based Application

    This tutorial describes how to use \QC to create a small Qt application,
34
    Text Finder. It is a simplified version of the Qt UI Tools \l{Text Finder
35
    Example}. The application user interface is constructed from Qt widgets by
36 37 38 39 40 41 42 43
    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

44
        \li Select \uicontrol{File > New File or Project > Application > Qt Widgets
45 46 47 48
            Application > Choose}.

            \image qtcreator-new-qt-gui-application.png "New File or Project dialog"

49
            The \uicontrol{Introduction and Project Location} dialog opens.
50 51 52

            \image qtcreator-intro-and-location-qt-gui.png "Introduction and Project Location dialog"

53
        \li In the \uicontrol{Name} field, type \b {TextFinder}.
54

55 56 57
        \li In the \uicontrol {Create in} field, enter the path for the project files.
            For example, \c {C:\Qt\examples}, and then click \uicontrol{Next} (on
            Windows and Linux) or \uicontrol Continue (on OS X).
58

59
            The \uicontrol {Kit Selection} dialog opens.
60

61
            \image qtcreator-new-project-qt-versions-qt-gui.png "Kit Selection dialog"
62

63
        \li Select build and run \l{glossary-buildandrun-kit}{kits} for your project,
64
            and click \uicontrol Next or \uicontrol Continue.
65

66 67 68
            \note If only one kit is specified in \uicontrol Tools > \uicontrol Options >
            \uicontrol {Build & Run} > \uicontrol Kits (on Windows and Linux) or in
            \uicontrol {Qt Creator} > \uicontrol Preferences \uicontrol {Build & Run} > \uicontrol Kits
69
            (on OS X), this dialog is skipped.
70

71
            The \uicontrol{Class Information} dialog opens.
72 73 74

            \image qtcreator-class-info-qt-gui.png "Class Information dialog"

75
        \li In the \uicontrol{Class name} field, type \b {TextFinder} as the class
76 77
            name.

78
        \li In the \uicontrol{Base class} list, select \b {QWidget} as the base
79 80
            class type.

81
           \note The \uicontrol{Header file}, \uicontrol{Source file} and \uicontrol{Form file}
82 83
            fields are automatically updated to match the name of the class.

84
        \li Click \uicontrol Next or \uicontrol Continue.
85

86
            The \uicontrol{Project Management} dialog opens.
87 88 89

            \image qtcreator-new-project-summary-qt-gui.png "Project Management dialog"

90 91
        \li Review the project settings, and click \uicontrol{Finish} (on Windows and
            Linux) or \uicontrol Done (on OS X) to create the project.
92 93 94

    \endlist

95 96
    \note The project opens in the \uicontrol Edit mode, and these instructions are
    hidden. To return to these instructions, open the \uicontrol Help mode.
97

98 99 100 101
    The TextFinder project now contains the following files:

    \list

102 103 104 105 106
        \li textfinder.h
        \li textfinder.cpp
        \li main.cpp
        \li textfinder.ui
        \li textfinder.pro
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125

    \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

126 127
        \li In the \uicontrol{Editor} mode, double-click the textfinder.ui file in the
            \uicontrol{Projects} view to launch the integrated \QD.
128

129
        \li Drag and drop the following widgets to the form:
130 131 132

        \list

133 134 135
            \li \uicontrol{Label} (QLabel)
            \li \uicontrol{Line Edit} (QLineEdit)
            \li \uicontrol{Push Button} (QPushButton)
136 137 138 139 140 141

        \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
142
        \uicontrol Sidebar. For example, to find the \uicontrol Label widget, start typing
143
        the word \b label.
144 145 146

        \image qtcreator-texfinder-filter.png "Filter field"

147
        \li Double-click the \uicontrol{Label} widget and enter the text
148
            \b{Keyword}.
149

150
        \li Double-click the \uicontrol{Push Button} widget and enter the text
151
            \b{Find}.
152

153
        \li In the \uicontrol Properties pane, change the \uicontrol objectName to
154
            \b findButton.
155 156 157

            \image qtcreator-textfinder-objectname.png "Changing object names"

158
        \li Press \key {Ctrl+A} (or \key {Cmd+A}) to select the widgets and
159
            click \uicontrol{Lay out Horizontally} (or press \uicontrol{Ctrl+H} on Linux or
160
            Windows or \key {Ctrl+Shift+H} on OS X) to apply a horizontal
161
            layout (QHBoxLayout).
162 163 164

            \image qtcreator-texfinder-ui-horizontal-layout.png "Applying horizontal layout"

165
        \li Drag and drop a \uicontrol{Text Edit} widget (QTextEdit) to the form.
166

167 168
        \li Select the screen area and click \uicontrol{Lay out Vertically} (or press
            \uicontrol{Ctrl+L}) to apply a vertical layout (QVBoxLayout).
169 170 171 172 173 174

            \image qtcreator-textfinder-ui.png "Text Finder UI"

            Applying the horizontal and vertical layouts ensures that the
            application UI scales to different screen sizes.

175
        \li To call a find function when users press the \uicontrol Find button, you
176 177 178 179 180 181 182 183
            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

184
                \li Right-click the \uicontrol Find button to open a context-menu.
185

186 187
                \li Select \uicontrol {Go to Slot > clicked()}, and then select
                    \uicontrol OK.
188 189 190 191 192 193 194 195

                    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

196
        \li Press \uicontrol{Ctrl+S} (or \key {Cmd+S}) to save your changes.
197 198 199 200

    \endlist

    For more information about designing forms with \QD, see the
201
    \l{Qt Designer Manual}.
202 203 204 205 206 207 208 209 210 211

    \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

212
        \li In the \uicontrol{Projects} pane in the \uicontrol {Edit view}, double-click the
213 214
            \c{textfinder.h} file to open it for editing.

215
        \li Add a private function to the \c{private} section, after the
216 217 218
            \c{Ui::TextFinder} pointer, as illustrated by the following code
            snippet:

219
            \snippet textfinder/textfinder.h 0
220 221 222 223 224 225 226 227 228 229

    \endlist

    \section2 Completing the Source File

    Now that the header file is complete, move on to the source file,
    textfinder.cpp.

    \list 1

230
        \li In the \uicontrol{Projects} pane in the \uicontrol Edit view, double-click the
231 232
            textfinder.cpp file to open it for editing.

233
        \li Add code to load a text file using QFile, read it with QTextStream,
234
            and then display it on \c{textEdit} with
235
            \l{QTextEdit::setPlainText()}.
236 237
            This is illustrated by the following code snippet:

238
            \snippet textfinder/textfinder.cpp 0
239

240
        \li To use QFile and QTextStream, add the following #includes to
241 242
            textfinder.cpp:

243
            \snippet textfinder/textfinder.cpp 1
244

245
        \li For the \c{on_findButton_clicked()} slot, add code to extract the
246
            search string and use the \l{QTextEdit::find()} function
247 248 249
            to look for the search string within the text file. This is
            illustrated by the following code snippet:

250
            \snippet textfinder/textfinder.cpp 2
251

252
        \li Once both of these functions are complete, add a line to call
253 254 255
            \c{loadTextFile()} in the constructor, as illustrated by the
            following code snippet:

256
            \snippet textfinder/textfinder.cpp 3
257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277

    \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

278
        \li Select \uicontrol{File > New File or Project > Qt > Qt Resource File >
279 280 281 282
            Choose}.

            \image qtcreator-add-resource-wizard.png "New File or Project dialog"

283
            The \uicontrol {Choose the Location} dialog opens.
284 285 286

            \image qtcreator-add-resource-wizard2.png "Choose the Location dialog"

287
        \li In the \uicontrol{Name} field, enter \b{textfinder}.
288

289 290
        \li In the \uicontrol{Path} field, enter \c{C:\Qt\examples\TextFinder},
            and click \uicontrol Next or \uicontrol Continue.
291

292
            The \uicontrol{Project Management} dialog opens.
293 294 295 296

            \image qtcreator-add-resource-wizard3.png "Project Management dialog"


297 298
        \li In the \uicontrol{Add to project} field, select \b{TextFinder.pro}
            and click \uicontrol{Finish} or \uicontrol Done to open the file in the code
299
            editor.
300

301
        \li Select \uicontrol{Add > Add Prefix}.
302

303
        \li In the \uicontrol{Prefix} field, replace the default prefix with a slash
304 305
            (/).

306
        \li Select \uicontrol{Add > Add Files}, to locate and add input.txt.
307 308 309 310 311 312 313 314 315 316 317 318

            \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.

*/