diff options
author | Leena Miettinen <riitta-leena.miettinen@qt.io> | 2022-01-21 18:30:37 +0100 |
---|---|---|
committer | Leena Miettinen <riitta-leena.miettinen@qt.io> | 2022-01-31 14:24:11 +0100 |
commit | ec57418ecfc1bf7cfbc0dd7b33c899ce24b4a49d (patch) | |
tree | 08c616511b9755eddff06d140353f76a560afab6 /examples | |
parent | a3503c8eae08a393233f5f5c187a51c9c0d98b5e (diff) | |
download | qtbase-ec57418ecfc1bf7cfbc0dd7b33c899ce24b4a49d.tar.gz |
Doc: Update Notepad tutorial
Update to use Qt Creator 7.0 and CMake as the build system.
Fixes: QTBUG-100075
Pick-to: 6.3
Change-Id: I71e1d1446a2c79c98423ca5d4427b4b4eb00021b
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
Diffstat (limited to 'examples')
-rw-r--r-- | examples/widgets/doc/images/notepad1.png | bin | 12418 -> 11747 bytes | |||
-rw-r--r-- | examples/widgets/doc/images/notepad2.png | bin | 22700 -> 26246 bytes | |||
-rw-r--r-- | examples/widgets/doc/images/notepad3.png | bin | 40584 -> 21002 bytes | |||
-rw-r--r-- | examples/widgets/tutorials/gettingstartedqt.qdoc | 196 | ||||
-rw-r--r-- | examples/widgets/tutorials/notepad/main.cpp | 12 | ||||
-rw-r--r-- | examples/widgets/tutorials/notepad/notepad.h | 23 |
6 files changed, 92 insertions, 139 deletions
diff --git a/examples/widgets/doc/images/notepad1.png b/examples/widgets/doc/images/notepad1.png Binary files differindex 40d13269b9..91863de5c3 100644 --- a/examples/widgets/doc/images/notepad1.png +++ b/examples/widgets/doc/images/notepad1.png diff --git a/examples/widgets/doc/images/notepad2.png b/examples/widgets/doc/images/notepad2.png Binary files differindex 9cec1f9a58..599a5c68f4 100644 --- a/examples/widgets/doc/images/notepad2.png +++ b/examples/widgets/doc/images/notepad2.png diff --git a/examples/widgets/doc/images/notepad3.png b/examples/widgets/doc/images/notepad3.png Binary files differindex 426861ab06..d4f55ba2a0 100644 --- a/examples/widgets/doc/images/notepad3.png +++ b/examples/widgets/doc/images/notepad3.png diff --git a/examples/widgets/tutorials/gettingstartedqt.qdoc b/examples/widgets/tutorials/gettingstartedqt.qdoc index 2edc1f07f1..99c039b24b 100644 --- a/examples/widgets/tutorials/gettingstartedqt.qdoc +++ b/examples/widgets/tutorials/gettingstartedqt.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. +** Copyright (C) 2022 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the documentation of the Qt Toolkit. @@ -28,7 +28,7 @@ /*! \example tutorials/notepad \title Getting Started Programming with Qt Widgets - \brief A tutorial for Qt Widgets based on a notepad application. + \brief A tutorial for Qt Widgets based notepad application. In this topic, we teach basic Qt knowledge by implementing a simple Notepad application using C++ and the \l{Qt Widgets} module. The @@ -38,11 +38,7 @@ \image notepad1.png "Notepad application" - You can find the final Notepad source files in the qtdoc repository - in the tutorials/notepad directory. You can either fetch - the Qt 5 sources from Qt Project or install them as part of Qt 5. - The application is also available in the example list of Qt Creator's - Welcome mode. + \include examples-run.qdocinc \section1 Creating the Notepad Project @@ -51,23 +47,26 @@ wizard prompts you to enter the settings needed for that particular type of project and creates the project for you. - \image notepad2.png "Qt Creator New File or Project dialog" + \note The UI text in Qt Creator and the contents of the generated files + depend on the Qt Creator version that you use. - To create the Notepad project, select \b File > \b{New File or - Project} > \b Applications > \b {Qt Widgets Application} > \b Choose, - and follow the instructions of the wizard. In the - \b{Class Information} - dialog, type \b Notepad as the class name and select \b QMainWindow + \image notepad2.png "Qt Creator New Project dialog" + + To create the Notepad project, select \uicontrol File > + \uicontrol {New Project} > \uicontrol {Application (Qt)} > + \uicontrol {Qt Widgets Application} > \uicontrol Choose, and follow the + instructions of the wizard. In the \uicontrol{Class Information} dialog, + type \e Notepad as the class name and select \uicontrol QMainWindow as the base class. \image notepad3.png "Class Information Dialog" - The \b {Qt Widgets Application} wizard creates a project that contains + The \uicontrol {Qt Widgets Application} wizard creates a project that contains a main source file and a set of files that specify a user interface (Notepad widget): \list - \li notepad.pro - the project file. + \li CMakeLists.txt - the project file. \li main.cpp - the main source file for the application. \li notepad.cpp - the source file of the notepad class of the Notepad widget. @@ -76,11 +75,9 @@ \li notepad.ui - the UI form for the Notepad widget. \endlist - The .cpp, .h, and .ui files come with the necessary boiler plate code - for you to be able to build and run the project. The .pro file is - complete. - We will take a closer look at the file contents in the following - sections. + The files come with the necessary boiler plate code for you to be able to + build and run the project. We will take a closer look at the file contents + in the following sections. \b{Learn More} @@ -103,7 +100,6 @@ \quotefromfile tutorials/notepad/main.cpp \skipto "notepad.h" - \printuntil EditorApp.exec() \printuntil } We will go through the code line by line. The following lines include @@ -143,14 +139,14 @@ are not visible by default; the function \l{QWidget::}{show()} makes the widget visible. - \printline Editor.show + \printline w.show The following line makes the QApplication enter its event loop. When a Qt application is running, events are generated and sent to the widgets of the application. Examples of events are mouse presses and key strokes. - \printline EditorApp.exec + \printline a.exec \b{Learn More} @@ -186,14 +182,14 @@ To add widgets in Qt Designer: \list 1 - \li In the Qt Creator \b Editor mode, double-click the notepad.ui - file in the \b Projects view to launch the file in the integrated + \li In the Qt Creator \uicontrol Edit mode, double-click the notepad.ui + file in the \uicontrol Projects view to launch the file in the integrated Qt Designer. \li Drag and drop widgets Text Edit (QTextEdit) to the form. - \li Press \b {Ctrl+A} (or \b {Cmd+A}) to select the widgets and click - \b {Lay out Vertically} (or press \b {Ctrl+L}) to apply a vertical + \li Press \key {Ctrl+A} (or \key {Cmd+A}) to select the widgets and click + \uicontrol {Lay out Vertically} (or press \key {Ctrl+L}) to apply a vertical layout (QVBoxLayout). - \li Press \b {Ctrl+S} (or \b {Cmd+S}) to save your changes. + \li Press \key {Ctrl+S} (or \key {Cmd+S}) to save your changes. \endlist The UI now looks as follows in Qt Designer: @@ -231,18 +227,25 @@ necessary #includes, a constructor, a destructor, and the Ui object. The file looks as follows: - \snippet tutorials/notepad/notepad.h all + \quotefromfile tutorials/notepad/notepad.h + \skipto #include + \printuntil ~Notepad(); + \skipto private: + \printuntil }; The following line includes QMainWindow that provides a main application window: - \snippet tutorials/notepad/notepad.h 1 + \quotefromfile tutorials/notepad/notepad.h + \skipto #include + \printuntil > The following lines declare the Notepad class in the Ui namespace, which is the standard namespace for the UI classes generated from .ui files by the \c uic tool: - \snippet tutorials/notepad/notepad.h 2 + \skipto Ui { + \printuntil } The class declaration contains the \c Q_OBJECT macro. It must come first in the class definition, and declares our class as a QObject. @@ -251,14 +254,15 @@ names can be queried at runtime. It is also possible to query a slot's parameter types and invoke it. - \snippet tutorials/notepad/notepad.h 3 + \skipto class Notepad + \printuntil Q_OBJECT The following lines declare a constructor that has a default argument called \c parent. The value 0 indicates that the widget has no parent (it is a top-level widget). - \snippet tutorials/notepad/notepad.h 4 + \printuntil explicit The following line declares a virtual destructor to free the resources that were acquired by the object during its life-cycle. According to @@ -268,13 +272,14 @@ classes are invoked properly when an object is deleted through a pointer-to-base-class. - \snippet tutorials/notepad/notepad.h 5 + \printuntil ~Notepad(); The following lines declare a member variable which is a pointer to the Notepad UI class. A member variable is associated with a specific class, and accessible for all its methods. - \snippet tutorials/notepad/notepad.h 6 + \skipto private: + \printuntil }; \section2 Notepad Source File @@ -282,8 +287,9 @@ as follows: \quotefromfile tutorials/notepad/notepad.cpp - \skipto notepad.h - \printuntil ui->textEdit->setFont(font) + \skipto #include "notepad.h" + \printuntil ui->setupUi(this); + \skipto } \printuntil } The following lines include the Notepad class header file that was @@ -291,18 +297,17 @@ by the \c uic tool: \quotefromfile tutorials/notepad/notepad.cpp - \skipto notepad.h - \printuntil ui_notepad + \skipto #include "notepad.h" + \printuntil #include "ui_notepad.h" The following line defines the \c {Notepad} constructor: - \skipto Notepad::Notepad - \printline Notepad::Notepad + \printuntil Notepad::Notepad The following line calls the QMainWindow constructor, which is the base class for the Notepad class: - \printline QMainWindow + \printuntil QMainWindow The following line creates the UI class instance and assigns it to the \c ui member: @@ -311,9 +316,7 @@ The following line sets up the UI: - \quotefromfile tutorials/notepad/notepad.cpp - \skipto ui->setupUi - \printline ui->setupUi(this) + \printuntil ui->setupUi(this) In the destructor, we delete the \c ui: @@ -322,19 +325,13 @@ \section2 Project File - The wizard generates the following project file, \c {notepad.pro}, for + The wizard generates the following project file, \c CMakeLists.txt, for us: - \quotefile tutorials/notepad/notepad.pro - - The project file specifies the application name and the \c qmake - template to use for generating the project, as well as the source, - header, and UI files included in the project. + \quotefile tutorials/notepad/CMakeLists.txt - You could also use \c qmake's \c -project option to generate the \.pro - file. Although, in that case, you have to remember to add the line - \c{QT += widgets} to the generated file in order to link against the - Qt Widgets Module. + The project file specifies the source, header, and UI files included in + the project. \b{Learn More} @@ -375,7 +372,8 @@ Click on "Type Here", and add the options New, Open, Save, Save as, Print and Exit. This creates 5 lines in the Action Editor below. To connect the actions to slots, right-click an action and select - Go to slot > triggered(), and complete the code for that given slot. + \uicontrol {Go to slot} > \uicontrol triggered(), and complete the + code for that given slot. If we also want to add the actions to a toolbar, we can assign an icon to each QAction, and then drag the QAction to the toolbar. You @@ -389,20 +387,18 @@ \skipto newDocument() \printuntil } - \c current_file is a global variable containing the file presently - being edited. - It is defined in the private part of notepad.h: + The \c currentFile variable is a global variable containing the file + presently being edited, and \c clear() clears the text buffer. + The \c currentFile variable is defined in the private part of notepad.h: \quotefromfile tutorials/notepad/notepad.h \skipto private: \printuntil currentFile; - \c clear() clears the text buffer. - \section2 Opening a file - In \c notepad.ui, right click on \c actionOpen and select \c {Go to - slot} + In \c notepad.ui, right click on \c actionOpen and select + \uicontrol {Go to Slot}. Complete method \c open(). @@ -413,21 +409,21 @@ \c QFileDialog::getOpenFileName opens a dialog enabling you to select - a file. QFile object \c myfile has the selected \c file_name as - parameter. We store the selected file also into the global variable - \c current_file for later purposes. We open the file with \c file.open + a file. QFile object \c myfile has the selected \c file_name as + parameter. We store the selected file also into the global variable + \c currentFile for later purposes. We open the file with \c file.open as a readonly text file. If it cannot be opened, a warning is issued, and the program stops. We define a QTextStream \c instream for parameter \c myfile. - The contents of file \c myfile is copied into QString \a text. - \c setText(text) fille the buffer of our editor with \c text. + The contents of file \c myfile is copied into QString \c text. + \c setText(text) fills the buffer of our editor with \c text. - \c section2 Saving a file + \section2 Saving a file We create the method for saving a file in the same way as for \l {Opening a file}, by right clicking on \c actionSave, and - selecting \c {Go to Slot}. + selecting \uicontrol {Go to Slot}. \skipto Notepad::save \printuntil file.close @@ -436,41 +432,45 @@ QFile object \c myfile is linked to global variable \c current_file, the variable that contains the file we were working with. If we cannot open \c myfile, an error message is issued and the - method stops. We create a QTextStream \c outstream. The contents + method stops. We create a QTextStream \c outstream. The contents of the editor buffer is converted to plain text, and then written to \c outstream. - \section2 Saving a file with \c {Save as} + \section2 Saving a file under another name \skipto Notepad::saveAs \printuntil file.close \printuntil } - This is the same procedure as for \c {Saving a file}, the only + This is the same procedure as for \l {Saving a file}, the only difference being that here you need to enter a new file name for the file to be created. - \section2 Print a File + \section2 Printing a File If you want to use print functionalities, you need to add - \c printsupport to the project file: + \c PrintSupport to the project file: - \badcode - QT += printsupport - \endcode + \quotefromfile tutorials/notepad/CMakeLists.txt + \skipto find_package(Qt6 + \printuntil ) + + In \c notepad.cpp, we declare a QPrinter object called \c printDev: + + \quotefromfile tutorials/notepad/notepad.cpp + \skipto void Notepad::print() + \printuntil } - We declare a QPrinter object called \c printer. We launch a printer dialog box and store the selected printer in - object \c printer. If we clicked on \c Cancel and did not select - a printer, the methods returns. The actual printer command is given - with \a ui->textEdit->print with our QPrinter object as parameter. + object \c printDev. If we clicked on \c Cancel and did not select + a printer, the methods returns. The actual printer command is given + with \c ui->textEdit->print with our QPrinter object as parameter. \section2 Select a Font \skipto Notepad::selectFont - \printuntil ui->textEdit->setFont - \printline } + \printuntil } We declare a boolean indicating if we did select a font with QFontDialog. If so, we set the font with \c ui->textEdit->setFont(myfont). @@ -478,7 +478,7 @@ \section2 Copy, Cut, Paste, Undo, and Redo If you select some text, and want to copy it to the clipboard, - you call the appropriate method of ui->textEdit. The same counts + you call the appropriate method of \c ui->textEdit. The same counts for cut, paste, undo, and redo. This table shows the method name to use. @@ -524,29 +524,5 @@ \l{Internationalization with Qt} \endtable - \section1 Building and Running Notepad - - Now that you have all the necessary files, select \b Build > - \b {Build Project Notepad} to build and run the application. Qt - Creator uses \c qmake and \c make to create an executable in the - directory specified in the build settings of the project and runs - it. - - \section2 Building and Running from the Command Line - - To build the application from the command line, switch to the - directory in which you have the \c .cpp file of the application - and add the project file (suffixed .pro) described earlier. The - following shell commands then build the application: - - \badcode - qmake - make (or nmake on Windows) - \endcode - - The commands create an executable in the project directory. The - \c qmake tool reads the project file and produces a \c Makefile - with instructions on how to build the application. - The \c make tool (or the \c nmake tool) then reads the \c Makefile - and produces the executable binary. + \include cli-build-cmake.qdocinc cli-build-cmake */ diff --git a/examples/widgets/tutorials/notepad/main.cpp b/examples/widgets/tutorials/notepad/main.cpp index 20bcdaa7df..af5b09eedc 100644 --- a/examples/widgets/tutorials/notepad/main.cpp +++ b/examples/widgets/tutorials/notepad/main.cpp @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. +** Copyright (C) 2022 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the documentation of the Qt Toolkit. @@ -49,13 +49,13 @@ ****************************************************************************/ #include "notepad.h" + #include <QApplication> int main(int argc, char *argv[]) { - QApplication EditorApp(argc, argv); - Notepad Editor; - Editor.show(); - - return EditorApp.exec(); + QApplication a(argc, argv); + Notepad w; + w.show(); + return a.exec(); } diff --git a/examples/widgets/tutorials/notepad/notepad.h b/examples/widgets/tutorials/notepad/notepad.h index d4209daf6d..03daa82a91 100644 --- a/examples/widgets/tutorials/notepad/notepad.h +++ b/examples/widgets/tutorials/notepad/notepad.h @@ -51,60 +51,37 @@ #ifndef NOTEPAD_H #define NOTEPAD_H -//! [all] -//! [1] #include <QMainWindow> -//! [1] -//! [2] QT_BEGIN_NAMESPACE namespace Ui { class Notepad; } QT_END_NAMESPACE -//! [2] -//! [3] class Notepad : public QMainWindow { Q_OBJECT -//! [3] -//! [4] public: explicit Notepad(QWidget *parent = nullptr); -//! [4] -//! [5] ~Notepad(); -//! [5] private slots: void newDocument(); - void open(); - void save(); - void saveAs(); - void print(); - void selectFont(); - void setFontBold(bool bold); - void setFontUnderline(bool underline); - void setFontItalic(bool italic); - void about(); -//! [6] private: Ui::Notepad *ui; QString currentFile; -//! [6] }; -//! [all] #endif // NOTEPAD_H |