1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc: Update Notepad tutorial

Browse Source 
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>
This commit is contained in:
Leena Miettinen 2022-01-21 18:30:37 +01:00
parent a3503c8eae
commit ec57418ecf
8 changed files with 160 additions and 141 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
doc/global/includes/cli-build-cmake.qdocinc Normal file
View File

@ -0,0 +1,66 @@
/****************************************************************************
**
** Copyright (C) 2022 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** 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. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
//! [cli-build-cmake]
\section1 Building and Running from the Command Line
To build an example application from the command line, create a build
directory for it. Switch to the build directory and run \c qt-cmake to
configure your project for building. If the project is configured
successfully, the generated files enable you to build the project.
\badcode
md <build_directory>
cd <build_directory>
<qt_installation_directory>\bin\qt-cmake -GNinja <source_directory>
<generator>
\endcode
The commands create an executable in the build directory. The \c CMake
tool reads the project file and produces instructions for how to build
the application. The generator then uses the instructions to produce
the executable binary.
For example, to build the Notepad example on Windows, when using Ninja
as the generator, enter the following commands:
\badcode
md notepad-build
cd notepad-build
C:\Qt\6.2.1\msvc2019_64\bin\qt-cmake -GNinja C:\Examples\notepad
ninja
\endcode
If you do not use Ninja as the generator, use the generator-independent
CMake command to build the application instead of \c ninja:
\badcode
cmake --build
\endcode
//! [cli-build-cmake]

4
doc/global/includes/examples-run.qdocinc
View File

@ -1,5 +1,5 @@
\section1 Running the Example
To run the example from \l{Qt Creator Manual}{Qt Creator}, open the \gui Welcome
mode and select the example from \gui Examples. For more information, visit
To run the example from \l{Qt Creator Manual}{Qt Creator}, open the \uicontrol Welcome
mode and select the example from \uicontrol Examples. For more information, visit
\l{Qt Creator: Building and Running an Example}{Building and Running an Example}.

BIN
examples/widgets/doc/images/notepad1.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB

BIN
examples/widgets/doc/images/notepad2.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 22 KiB

After

Width:  |  Height:  |  Size: 26 KiB

BIN
examples/widgets/doc/images/notepad3.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 40 KiB

After

Width:  |  Height:  |  Size: 20 KiB

196
examples/widgets/tutorials/gettingstartedqt.qdoc
View File

@ -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
\quotefile tutorials/notepad/CMakeLists.txt
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.
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
*/

12
examples/widgets/tutorials/notepad/main.cpp
View File

@ -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();
}

23
examples/widgets/tutorials/notepad/notepad.h
View File

@ -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