diff options
Diffstat (limited to 'doc/src/getting-started/gettingstartedqt.qdoc')
| -rw-r--r-- | doc/src/getting-started/gettingstartedqt.qdoc | 316 |
1 files changed, 112 insertions, 204 deletions
diff --git a/doc/src/getting-started/gettingstartedqt.qdoc b/doc/src/getting-started/gettingstartedqt.qdoc index 73e3a2a20..7c448c28c 100644 --- a/doc/src/getting-started/gettingstartedqt.qdoc +++ b/doc/src/getting-started/gettingstartedqt.qdoc @@ -31,22 +31,11 @@ \title Getting Started Programming with Qt Widgets In this topic, we teach basic Qt knowledge by implementing a simple Notepad - application using C++ and the \l{Qt Widgets} module. We use the - Qt Creator IDE and Qt Designer to generate some code, but you could also write all the - code yourself. + 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. - After reading this topic, you are ready to refer to our overviews and API - documentation, to find the information you need for the application you are - developing. - - In this topic, we first use Qt Creator to create a project with the - necessary files. Then we use Qt Designer to modify the user interface files - to show a text edit and a push button in a window on the desktop. - This represents a simple Qt application that has a GUI. Finally, we add - user interaction to the application by creating actions for opening and - saving files. - - \image gs1.png "Notepad application" + \image notepad1.png "Notepad application" You can find the final Notepad source files in the qtdoc repository in the snippets/widgets-tutorial/notepad directory. You can either fetch @@ -59,14 +48,14 @@ to enter the settings needed for that particular type of project and creates the project for you. - \image gs-project1.png "Qt Creator New File or Project dialog" + \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 gs-project2.png "Class Information Dialog" + \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 @@ -107,7 +96,7 @@ \snippet snippets/widgets-tutorial/notepad/main.cpp all - Let us go through the code line by line. The following lines include + 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. @@ -120,9 +109,9 @@ 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.) + 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.) \snippet snippets/widgets-tutorial/notepad/main.cpp 3 @@ -137,12 +126,10 @@ \snippet snippets/widgets-tutorial/notepad/main.cpp 4 The following line shows the Notepad widget on the screen in its own - window. - Since widgets also function as containers (for instance a - QMainWindow, which has toolbars, menus, a status bar, and a few - other widgets), it is possible to show a single widget in its own - window. Widgets are not visible by default; the function - \l{QWidget::}{show()} makes the widget visible. + 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. \snippet snippets/widgets-tutorial/notepad/main.cpp 5 @@ -169,7 +156,7 @@ \section1 Designing a UI - The wizard generates a user interface definition in XML format, notepad.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. @@ -180,29 +167,17 @@ \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, tool bars, and a + 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. - Let us use Qt Designer to add a QTextEdit object and a QPushButton object to - the main window. When you type text in the text edit widget, it receives key - pressed events and responds by drawing the text typed. The button will exit - the Notepad application when pushed (that is, clicked with the mouse). - 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 the following widgets to the form: - \list - \li Text Edit (QTextEdit) - \li Push Button (QPushButton) - \endlist - \li Double-click the \b {Push Button} widget and enter the text \b Quit. - \li In the \b Properties pane, change the value of \b objectName to - \b quitButton. + \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). @@ -211,7 +186,7 @@ The UI now looks as follows in Qt Designer: - \image gs2.png + \image notepad4.png You can view the generated XML file in the code editor: @@ -234,28 +209,6 @@ <ui version="4.0"> \endcode - The following snippet creates a QVBoxLayout widget that contains a QTextEdit - and QPushButton widget. As mentioned, widgets can contain - other widgets. It is possible to set the bounds (the location and - size) of child widgets directly, but it is usually easier to use a - layout. A layout manages the bounds of a widget's children. - QVBoxLayout, for instance, places the children in a vertical row. - - \code - <layout class="QVBoxLayout" name="verticalLayout"> - <item> - <widget class="QTextEdit" name="textEdit"/> - </item> - <item> - <widget class="QPushButton" name="quitButton"> - <property name="text"> - <string>Quit</string> - </property> - </widget> - </item> - </layout> - \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. @@ -282,7 +235,7 @@ 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 run-time. It is also possible to query a slot's + queried at runtime. It is also possible to query a slot's parameter types and invoke it. \snippet snippets/gs/notepad1.h 3 @@ -343,6 +296,11 @@ \snippet snippets/gs/notepad1.cpp 5 + In order to have the text edit field occupy the whole screen, we add + \c setCentralWidget to the main window. + + \snippet snippets/widgets-tutorial/notepad/notepad.cpp 1 + \section2 Project File The wizard generates the following project file, \c {notepad.pro}, for us: @@ -389,179 +347,129 @@ \section1 Adding User Interaction - We now have a user interface, but it does not really do anything useful, as - it only contains a text edit and a push button, as well as some standard - functions for quitting, minimizing and maximizing the application. To make - the application useful, we will add user interaction to it. First, we will - add functionality to the push button. Second, we will add functions for - loading a file to the text edit and for saving the contents of the text edit - as a file. - - \section2 Adding Push Buttons - - Most desktop operating systems have standard ways of enabling users to quit - applications. However, in this example we use this basic function to - illustrate how you can add user interaction to applications. To do this, we - add a slot that we connect to the \b {Quit button}. - - To exit the application when the \b Quit button is pushed, you use the Qt - signals and slots mechanism. A signal is emitted when a particular event - occurs and a slot is a function that is called in response to a particular - signal. Qt widgets have predefined signals and slots that you can use - directly from Qt Designer. - - To use Qt Designer to add a slot for the quit function, right-click the - \b Quit button to open a context-menu and then select \b {Go to slot} > - \b {clicked()}. - - A private slot, \c{on_quitButton_clicked()}, is added to the Notepad widget - class header file, notepad.h and a private function, - \c{Notepad::on_quitButton_clicked()}, is added to the Notepad widget class - source file, notepad.cpp. We just need to write the code to execute the quit - function in the source file. - - Let us look at the modified code in the header file, notepad.h: - - \snippet snippets/gs/notepad2.h all - - The following code uses Qt's signals and slots mechanism to make the - application exit when the \b {Quit button} is pushed. Qt Designer uses - QMetaObject \l{designer-using-a-ui-file.html#automatic-connections} - {auto-connection facilities} to connect the button's clicked() signal to a - slot in the Notepad class. The \c uic tool automatically generates code in - the dialog's \c{setupUi()} function to do this, so Qt Designer only needs to - declare and implement a slot with a name that follows a standard convention. - - \snippet snippets/gs/notepad2.h 1 - The corresponding code in the source file, notepad.cpp, looks as follows: + To add functionality to the editor, we start by adding menu items and buttons on a toolbar. - \snippet snippets/gs/notepad2.cpp all + 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. - The code defines the private function that is executed when QPushButton - emits the \l{QPushButton::}{clicked()} signal. + 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. - We now complement the code to have the \l{QCoreApplication::}{quit()} slot of - QApplication exit Notepad: + Complete the method \c on_actionNew_triggered() : - \snippet snippets/widgets-tutorial/notepad/notepad.cpp 1 - - \b{Learn More} - - \table - \header - \li About - \li Here - \row - \li Signals and slots - \li \l{Signals & Slots} - \endtable + \snippet snippets/widgets-tutorial/notepad/notepad.cpp 2 - \section2 Adding Menu Items + \c current_file is a global variable containing the file presently being edited. + It is defined in the private part of notepad.h: - Often, in a main window, the same slot should be invoked by - several widgets. Examples are menu items and buttons on a tool - bar. To make this easier, Qt provides QAction, which can be given - to several widgets, and be connected to a slot. For instance, both - QMenu and QToolBar can create menu items and tool buttons from the - same \l{QAction}. + \snippet snippets/widgets-tutorial/notepad/notepad.h 6 - To learn how to use actions with signals and slots, we add menu items to - open and save a document and connect them to slots. + \c setText("") clears the text buffer. - As before, we use Qt Designer to add the widgets to the user interface. - The wizard creates an application with a QMenu widget, with the text - \b {Type Here} as a placeholder for menu and menu item names. Double-click - the text to enter names for the \b File menu and \b Open and \b Save menu - items. Qt Designer automatically generates the appropriate actions. + \section2 Opening a file - \image gs3.png + In \c notepad.ui, right click on \c actionOpen and select \c {Go to slot} - To connect the actions to slots, right-click an action and select - \b {Go to slot} > \b triggered(). + Complete method \c on_actionOpen_triggered(). - \l{QAction} instances are created with the text that should appear on the - widgets that we add them to (in our case, menu items). If we also - wanted to add the actions to a tool bar, we could have specified - \l{QIcon}{icons} for them. + \snippet snippets/widgets-tutorial/notepad/notepad.cpp 3 - The modified code in notepad.ui now looks as follows: + \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. - \quotefromfile snippets/widgets-tutorial/notepad/notepad.ui + 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. - \skipto QMenuBar - \printto layoutdefault + \c section2 Saving a file - Qt Designer adds the private slots \c{on_actionOpen_triggered()} and - \c{on_actionSave_triggered()} to notepad.h and the private functions - \c{Notepad::on_actionOpen_triggered()} and - \c{Notepad::on_actionSave_triggered()} to notepad.cpp. + 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}. - In the following sections, we complement the code to load and save files. - When a menu item is clicked, the item triggers the action, and the - respective slot is invoked. + \snippet snippets/widgets-tutorial/notepad/notepad.cpp 4 - \section2 Opening Files + 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. - In this section, we implement the functionality of the - \c{on_actionOpen_triggered()} slot. The first step is asking the user for - the name of the file to open. Qt comes with QFileDialog, which is a dialog - from which the user can select a file. The appearance of the dialog depends - on the desktop platform that you run the application on. The following - image shows the dialog on \macos: + \c section2 Saving a file with \c {Save as} - \image gs4.png + \snippet snippets/widgets-tutorial/notepad/notepad.cpp 5 - We complement the code generated by Qt Designer in notepad.cpp, as follows: + 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. - \snippet snippets/widgets-tutorial/notepad/notepad.cpp 2 - The static \l{QFileDialog::}{getOpenFileName()} function - displays a modal file dialog. It returns the file path of the file - selected, or an empty string if the user canceled the dialog. + \section2 Print a file - If we have a file name, we try to open the file with - \l{QIODevice::}{open()}, which returns true if the file could be - opened. We will not go into error handling here, but you can follow - the links from the learn more section. If the file could not be - opened, we use QMessageBox to display a dialog with an error - message (see the QMessageBox class description for further - details). + If you want to use print functionalities, you need to add \c printsupport to + the project file: - Actually reading in the data is trivial using the QTextStream - class, which wraps the QFile object. The - \l{QTextStream::}{readAll()} function returns the contents of the - file as a QString. The contents can then be displayed in the text - edit. We then \l{QIODevice::}{close()} the file to return the file - descriptor back to the operating system. + QT += core gui printsupport - We now use the function \l{QObject::}{tr()} around our user - visible strings. This function is necessary when you want to - provide your application in more than one language (for example, English - and Chinese). We will not go into details here, but you can follow - the \c {Qt Linguist} link from the learn more table. + 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. - To use QFileDialog, QFile, QMessageBox, and QTextStream, add the following - includes to notepad.cpp: + \section2 Select a font - \snippet snippets/widgets-tutorial/notepad/notepad.cpp 0 + \snippet snippets/widgets-tutorial/notepad/notepad.cpp 7 - \section2 Saving Files + 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). - Now, let us move on to the \c{on_actionSave_triggered()} slot, which - also uses QFileDialog to create a dialog in which the user can save a - file with the specified name in the specified location. + \section2 Copy, cut, paste, undo, redo - \image gs5.png + 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. - We complement the code generated by Qt Designer in notepad.cpp, as follows: + This table shows the method name to use. - \snippet snippets/widgets-tutorial/notepad/notepad.cpp 3 + \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 - When we write the contents of the text edit to the file, we use - the QTextStream class again. QTextStream can also write - \l{QString}s to the file with the << operator. + This project contains the following files: + \list + \li {main.cpp} + \li {notepad.cpp} + \li {notepad.h} + \li {notepad.pro} + \li {notepad.ui} + \endlist \b{Learn More} \table |