diff options
Diffstat (limited to 'examples/widgets/tutorials/gettingstartedqt.qdoc')
-rw-r--r-- | examples/widgets/tutorials/gettingstartedqt.qdoc | 552 |
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. -*/ |