7aad542629
Their correctness is not checked at compile time and even object renames can break code. Change-Id: I99273a28743a79a76c00e6db0ed4cd6d7eba8bf2 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
560 lines
19 KiB
Plaintext
560 lines
19 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** Copyright (C) 2017 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$
|
|
**
|
|
****************************************************************************/
|
|
|
|
/*!
|
|
\example tutorials/notepad
|
|
\title Getting Started Programming with Qt Widgets
|
|
\brief A tutorial for Qt Widgets based on a 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
|
|
application is a small text editor which allows you to create a text
|
|
file, save it, print it,
|
|
or reopen and edit it again. You can also set the font to be used.
|
|
|
|
\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.
|
|
|
|
\section1 Creating the Notepad Project
|
|
|
|
Setting up a new project in Qt Creator is aided by a wizard that
|
|
guides you step-by-step through the project creation process. The
|
|
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"
|
|
|
|
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
|
|
as the base class.
|
|
|
|
\image notepad3.png "Class Information Dialog"
|
|
|
|
The \b {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 main.cpp - the main source file for the application.
|
|
\li notepad.cpp - the source file of the notepad class of the
|
|
Notepad widget.
|
|
\li notepad.h - the header file of the notepad class for the
|
|
Notepad widget.
|
|
\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.
|
|
|
|
\b{Learn More}
|
|
|
|
\table
|
|
\header
|
|
\li About
|
|
\li Here
|
|
\row
|
|
\li Using Qt Creator
|
|
\li \l{Qt Creator Manual}{Qt Creator}
|
|
\row
|
|
\li Creating other kind of applications with Qt Creator
|
|
\li \l{Qt Creator: Tutorials}{Qt Creator Tutorials}
|
|
\endtable
|
|
|
|
|
|
\section1 Main Source File
|
|
|
|
The wizard generates the following code in the main.cpp file:
|
|
|
|
\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
|
|
the header files for the Notepad widget and QApplication. All Qt classes
|
|
have a header file named after them.
|
|
|
|
\quotefromfile tutorials/notepad/main.cpp
|
|
\skipto notepad.h
|
|
\printuntil QApplication
|
|
|
|
The following line defines the main function that is the entry point
|
|
for all C and C++ based applications:
|
|
|
|
\printline main
|
|
|
|
The following line creates a QApplication object. This object manages
|
|
application-wide resources and is necessary to run any Qt program
|
|
that uses Qt Widgets. It constructs an application object with \c argc
|
|
command line arguments run in \c argv. (For GUI applications that
|
|
do not use Qt Widgets, you can use QGuiApplication instead.)
|
|
|
|
\skipuntil {
|
|
\printuntil QApplication
|
|
|
|
The following line creates the Notepad object. This is the object for
|
|
which the wizard created the class and the UI file. The user interface
|
|
contains visual elements that are called \c widgets in Qt. Examples
|
|
of widgets are text edits, scroll bars, labels, and radio buttons. A
|
|
widget can also be a container for other widgets; a dialog or a main
|
|
application window, for example.
|
|
|
|
\printline Notepad
|
|
|
|
The following line shows the Notepad widget on the screen in its own
|
|
window. Widgets can also function as containers. An example of this
|
|
is QMainWindow which often contains several types of widgets. Widgets
|
|
are not visible by default; the function \l{QWidget::}{show()} makes
|
|
the widget visible.
|
|
|
|
\printline Editor.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
|
|
|
|
\b{Learn More}
|
|
|
|
\table
|
|
\header
|
|
\li About
|
|
\li Here
|
|
\row
|
|
\li Widgets and Window Geometry
|
|
\li \l{Window and Dialog Widgets}
|
|
\row
|
|
\li Events and event handling
|
|
\li \l{The Event System}
|
|
\endtable
|
|
|
|
\section1 Designing a UI
|
|
|
|
The wizard generates a user interface definition in XML format: notepad.ui.
|
|
When you open the notepad.ui file in Qt Creator, it automatically
|
|
opens in the integrated Qt Designer.
|
|
|
|
When you build the application, Qt Creator launches the Qt
|
|
\l{User Interface Compiler (uic)} that reads the .ui file and creates
|
|
a corresponding C++ header file, ui_notepad.h.
|
|
|
|
\section2 Using Qt Designer
|
|
|
|
The wizard creates an application that uses a QMainWindow. It has
|
|
its own layout to which you can add a menu bar, dock widgets, toolbars,
|
|
and a status bar. The center area can be occupied by any kind of widget.
|
|
The wizard places the Notepad widget there.
|
|
|
|
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
|
|
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
|
|
layout (QVBoxLayout).
|
|
\li Press \b {Ctrl+S} (or \b {Cmd+S}) to save your changes.
|
|
\endlist
|
|
|
|
The UI now looks as follows in Qt Designer:
|
|
|
|
\image notepad4.png
|
|
|
|
You can view the generated XML file in the code editor:
|
|
|
|
\quotefromfile tutorials/notepad/notepad.ui
|
|
|
|
\printuntil QMenuBar
|
|
\dots
|
|
|
|
The following line contains the XML declaration, which specifies the
|
|
XML version and character encoding used in the document:
|
|
|
|
\code
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
\endcode
|
|
|
|
The rest of the file specifies an \c ui element that defines a
|
|
Notepad widget:
|
|
|
|
\code
|
|
<ui version="4.0">
|
|
\endcode
|
|
|
|
The UI file is used together with the header and source file of the
|
|
Notepad class. We will look at the rest of the UI file in the later
|
|
sections.
|
|
|
|
\section2 Notepad Header File
|
|
|
|
The wizard generated a header file for the Notepad class that has the
|
|
necessary #includes, a constructor, a destructor, and the Ui object.
|
|
The file looks as follows:
|
|
|
|
\snippet tutorials/notepad/notepad.h all
|
|
|
|
The following line includes QMainWindow that provides a main application
|
|
window:
|
|
|
|
\snippet tutorials/notepad/notepad.h 1
|
|
|
|
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
|
|
|
|
The class declaration contains the \c Q_OBJECT macro. It must come
|
|
first in the class definition, and declares our class as a QObject.
|
|
Naturally, it must also inherit from QObject. A QObject adds several
|
|
abilities to a normal C++ class. Notably, the class name and slot
|
|
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
|
|
|
|
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
|
|
|
|
The following line declares a virtual destructor to free the resources
|
|
that were acquired by the object during its life-cycle. According to
|
|
the C++ naming convention, destructors have the same name as the class
|
|
they are associated with, prefixed with a tilde (~). In QObject,
|
|
destructors are virtual to ensure that the destructors of derived
|
|
classes are invoked properly when an object is deleted through a
|
|
pointer-to-base-class.
|
|
|
|
\snippet tutorials/notepad/notepad.h 5
|
|
|
|
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
|
|
|
|
\section2 Notepad Source File
|
|
|
|
The source file that the wizard generated for the Notepad class looks
|
|
as follows:
|
|
|
|
\quotefromfile tutorials/notepad/notepad.cpp
|
|
\skipto notepad.h
|
|
\printuntil ui->textEdit->setFont(font)
|
|
\printuntil }
|
|
|
|
The following lines include the Notepad class header file that was
|
|
generated by the wizard and the UI header file that was generated
|
|
by the \c uic tool:
|
|
|
|
\quotefromfile tutorials/notepad/notepad.cpp
|
|
\skipto notepad.h
|
|
\printuntil ui_notepad
|
|
|
|
The following line defines the \c {Notepad} constructor:
|
|
|
|
\skipto Notepad::Notepad
|
|
\printline Notepad::Notepad
|
|
|
|
The following line calls the QMainWindow constructor, which is
|
|
the base class for the Notepad class:
|
|
|
|
\printline QMainWindow
|
|
|
|
The following line creates the UI class instance and assigns it to
|
|
the \c ui member:
|
|
|
|
\printline ui(new
|
|
|
|
The following line sets up the UI:
|
|
|
|
\quotefromfile tutorials/notepad/notepad.cpp
|
|
\skipto ui->setupUi
|
|
\printline ui->setupUi(this)
|
|
|
|
In the destructor, we delete the \c ui:
|
|
|
|
\skipto Notepad::~Notepad
|
|
\printuntil }
|
|
|
|
In order to have the text edit field occupy the whole screen, we add
|
|
\c setCentralWidget to the main window.
|
|
|
|
\quotefromfile tutorials/notepad/notepad.cpp
|
|
\skipto Notepad::Notepad(QWidget *parent)
|
|
\printuntil }
|
|
|
|
\section2 Project File
|
|
|
|
The wizard generates the following project file, \c {notepad.pro}, 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.
|
|
|
|
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.
|
|
|
|
\b{Learn More}
|
|
|
|
\table
|
|
\header
|
|
\li About
|
|
\li Here
|
|
\row
|
|
\li Using Qt Designer
|
|
\li \l{Qt Designer Manual}
|
|
\row
|
|
\li Layouts
|
|
\li \l{Layout Management},
|
|
\l{Widgets and Layouts},
|
|
\l{Layout Examples}
|
|
\row
|
|
\li The widgets that come with Qt
|
|
\li \l{Qt Widget Gallery}
|
|
\row
|
|
\li Main windows and main window classes
|
|
\li \l{Application Main Window},
|
|
\l{Main Window Examples}
|
|
\row
|
|
\li QObjects and the Qt Object model (This is essential to
|
|
understand Qt)
|
|
\li \l{Object Model}
|
|
\row
|
|
\li qmake and the Qt build system
|
|
\li \l{qmake Manual}
|
|
\endtable
|
|
|
|
\section1 Adding User Interaction
|
|
|
|
|
|
To add functionality to the editor, we start by adding menu items
|
|
and buttons on a toolbar.
|
|
|
|
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.
|
|
|
|
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
|
|
assign an icon by entering an icon name in the Icon property of the
|
|
action concerned. When the QAction has been dragged to the toolbar,
|
|
clicking the icon will launch the associated slot.
|
|
|
|
Complete the method \c newDocument():
|
|
|
|
\quotefromfile tutorials/notepad/notepad.cpp
|
|
\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:
|
|
|
|
\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}
|
|
|
|
Complete method \c open().
|
|
|
|
\quotefromfile tutorials/notepad/notepad.cpp
|
|
\skipto open()
|
|
\printuntil file.close
|
|
\printuntil }
|
|
|
|
|
|
\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
|
|
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.
|
|
|
|
\c 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}.
|
|
|
|
\skipto Notepad::save
|
|
\printuntil file.close
|
|
\printuntil }
|
|
|
|
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
|
|
of the editor buffer is converted to plain text, and then written
|
|
to \c outstream.
|
|
|
|
\section2 Saving a file with \c {Save as}
|
|
|
|
\skipto Notepad::saveAs
|
|
\printuntil file.close
|
|
\printuntil }
|
|
|
|
This is the same procedure as for \c {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
|
|
|
|
If you want to use print functionalities, you need to add
|
|
\c printsupport to the project file:
|
|
|
|
\badcode
|
|
QT += printsupport
|
|
\endcode
|
|
|
|
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.
|
|
|
|
\section2 Select a Font
|
|
|
|
\skipto Notepad::selectFont
|
|
\printuntil ui->textEdit->setFont
|
|
\printline }
|
|
|
|
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).
|
|
|
|
\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
|
|
for cut, paste, undo, and redo.
|
|
|
|
This table shows the method name to use.
|
|
|
|
\table
|
|
\header
|
|
\li Task
|
|
\li Method called
|
|
\row
|
|
\li Copy
|
|
\li ui->textEdit->copy()
|
|
\row
|
|
\li Cut
|
|
\li ui->textEdit->cut()
|
|
\row
|
|
\li Paste
|
|
\li ui->textEdit->paste()
|
|
\row
|
|
\li Undo
|
|
\li ui->textEdit->undo()
|
|
\row
|
|
\li Redo
|
|
\li ui->textEdit->redo()
|
|
\endtable
|
|
|
|
\b{Learn More}
|
|
|
|
\table
|
|
\header
|
|
\li About
|
|
\li Here
|
|
\row
|
|
\li MDI applications
|
|
\li QMdiArea,
|
|
\l{MDI Example}
|
|
\row
|
|
\li Files and I/O devices
|
|
\li QFile, QIODevice
|
|
\row
|
|
\li tr() and internationalization
|
|
\li \l{Qt Linguist Manual},
|
|
\l{Writing Source Code for Translation},
|
|
\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.
|
|
*/
|