- Qt Creator Documentation
- Tutorial: Qt Widgets application
- Qt Creator 18.0.2

Tutorial: Qt Widgets and Python ◦ Tutorial: Use internal libraries with qmake

# Tutorial: Qt Widgets application

This tutorial describes how to use Qt Creator to create a small Qt application, Text Finder. It is a simplified version of the Qt UI Tools Text Finder example. You'll use Qt Widgets Designer to construct the application user interface from Qt widgets and the code editor to write the application logic in C++.

## Create the Text Finder project

1. Go to File > New Project > Application (Qt) > Qt Widgets Application.

2. Select Choose to open the Project Location dialog.

3. In Name, type TextFinder.
4. In Create in, enter the path for the project files. For example, `C:\Qt\examples`.
5. Select Next (on Windows and Linux) or Continue (on macOS) to open the Define Build System dialog.

6. In Build system, select CMake as the build system to use for building the project.
7. Select Next or Continue to open the Class Information dialog.

8. In Class name, type TextFinder as the class name.
9. In Base class, select QWidget as the base class type.

   Note: Header file, Source file and Form file s are automatically updated to match the name of the class.

10. Select Next or Continue to open the Translation File dialog.

11. In Language, you can select a language that you plan to translate the application to. This sets up localization support for the application. You can add other languages later by editing the project file.
12. Select Next or Continue to open the Kit Selection dialog.

13. Select build and run kits for your project.
14. Select Next or Continue to open the Project Management dialog.

15. Review the project settings, and select Finish (on Windows and Linux) or Done (on macOS) to create the project.

Note: The project opens in the Edit mode, which hides these instructions. To return to these instructions, open the Help mode.

The TextFinder project now has the following files:

- `main.cpp`
- `textfinder.h`
- `textfinder.cpp`
- `textfinder.ui`
- `CMakeLists.txt`

The `.h` and `.cpp` files come with the necessary boiler plate code.

If you selected CMake as the build system, Qt Creator created a `CMakeLists.txt` project file for you.

## Fill 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.

### Design the user interface

1. In the Edit mode, double-click the `textfinder.ui` file in the Projects view to launch the integrated Qt Widgets Designer.
2. Drag the following widgets to the form:
   - Label (QLabel)
   - Line Edit (QLineEdit)
   - Push Button (QPushButton)

   Note: To easily locate the widgets, use the search box at the top of the Widget Box. For example, to find the Label widget, start typing the word label.

3. Double-click the Label widget and enter the text Keyword.
4. Double-click the Push Button widget and enter the text Find.
5. In the Property Editor view, change the objectName to findButton.

6. Select Ctrl+A (or Cmd+A) to select the widgets and select Lay out Horizontally (or select Ctrl+H on Linux or Windows or Ctrl+Shift+H on macOS) to apply a horizontal layout (QHBoxLayout).

7. Drag a Text Edit widget (QTextEdit) to the form.
8. Select the screen area, and then select Lay out Vertically (or select Ctrl+L) to apply a vertical layout (QVBoxLayout).

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

9. To call a find function when users select the 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 Qt Widgets Designer. To add a slot for the find function:
   - Right-click the Find button to open a context-menu.
   - Select Go to Slot > clicked(), and then select OK.

     This adds a private slot, `on_findButton_clicked()`, to the header file, `textfinder.h` and a private function, `TextFinder::on_findButton_clicked()`, to the source file, `textfinder.cpp`.

10. Select Ctrl+S (or Cmd+S) to save your changes.

For more information about designing forms with Qt Widgets Designer, see the Qt Widgets Designer Manual.

### Complete the header file

The `textfinder.h` file already has the necessary #includes, a constructor, a destructor, and the `Ui` object. You need to add a private function, `loadTextFile()`, to read and display the contents of the input text file in the QTextEdit.

1. In the Projects view in the Edit mode, double-click the `textfinder.h` file to open it for editing.
2. Add a private function to the `private` section, after the `Ui::TextFinder` pointer:

        private slots:
            void on_findButton_clicked();

        private:
            Ui::TextFinder *ui;
            void loadTextFile();

### Complete the source file

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

1. In the Projects view in the Edit mode, double-click the `textfinder.cpp` file to open it for editing.
2. Add code to load a text file using QFile, read it with QTextStream, and then display it on `textEdit` with QTextEdit::setPlainText():

        void TextFinder::loadTextFile()
        {
            QFile inputFile(":/input.txt");
            inputFile.open(QIODevice::ReadOnly);

            QTextStream in(&inputFile);
            QString line = in.readAll();
            inputFile.close();

            ui->textEdit->setPlainText(line);
            QTextCursor cursor = ui->textEdit->textCursor();
            cursor.movePosition(QTextCursor::Start, QTextCursor::MoveAnchor, 1);
        }

3. To use QFile and QTextStream, add the following #includes to `textfinder.cpp`:

        #include "./ui_textfinder.h"
        #include <QFile>
        #include <QTextStream>

4. For the `on_findButton_clicked()` slot, add code to extract the search string and use the QTextEdit::find() function to look for the search string within the text file:

        void TextFinder::on_findButton_clicked()
        {
            QString searchString = ui->lineEdit->text();
            ui->textEdit->find(searchString, QTextDocument::FindWholeWords);
        }

5. Add a line to call `loadTextFile()` in the constructor:

        TextFinder::TextFinder(QWidget *parent)
            : QWidget(parent)
            , ui(new Ui::TextFinder)
        {
            ui->setupUi(this);
            loadTextFile();
        }

The following line of code automatically calls the `on_findButton_clicked()` slot in the uic generated `ui_textfinder.h` file:

     QMetaObject::connectSlotsByName(TextFinder);

### Create 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:

1. Go to File > New File > Qt > Qt Resource File > Choose.

   The Choose the Location dialog opens.

2. In Name, enter textfinder.
3. In Path, enter the path to the project, and select Next or Continue.

   The Project Management dialog opens.

4. In Add to project, select TextFinder and select Finish or Done to open the file in the code editor.
5. Select Add Prefix.
6. In Prefix, replace the default prefix with a slash (/).
7. Select Add Files, to locate and add `input.txt`.

## Add resources to the project file

For the text file to appear when you run the application, you must specify the resource file as a source file in the `CMakeLists.txt` file that the wizard created for you:

     set(PROJECT_SOURCES
             main.cpp
             textfinder.cpp
             textfinder.h
             textfinder.ui
             ${TS_FILES}
             textfinder.qrc
     )

## Build and run your application

Now that you have all the necessary files, select (Run) to build and run your application.