summaryrefslogtreecommitdiffstats
path: root/examples/widgets/tutorials/gettingstartedqt.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'examples/widgets/tutorials/gettingstartedqt.qdoc')
-rw-r--r--examples/widgets/tutorials/gettingstartedqt.qdoc552
1 files changed, 0 insertions, 552 deletions
diff --git a/examples/widgets/tutorials/gettingstartedqt.qdoc b/examples/widgets/tutorials/gettingstartedqt.qdoc
deleted file mode 100644
index 2edc1f07f1..0000000000
--- a/examples/widgets/tutorials/gettingstartedqt.qdoc
+++ /dev/null
@@ -1,552 +0,0 @@
-/****************************************************************************
-**
-** 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 }
-
- \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.
-*/