| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 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 mainwindows/application |
| \title Application Example |
| \ingroup examples-mainwindow |
| |
| \brief The Application example shows how to implement a standard GUI |
| application with menus, toolbars, and a status bar. The example |
| itself is a simple text editor program built around QPlainTextEdit. |
| |
| \image application.png Screenshot of the Application example |
| |
| Nearly all of the code for the Application example is in the \c |
| MainWindow class, which inherits QMainWindow. QMainWindow |
| provides the framework for windows that have menus, toolbars, |
| dock windows, and a status bar. The application provides |
| \uicontrol{File}, \uicontrol{Edit}, and \uicontrol{Help} entries in the menu |
| bar, with the following popup menus: |
| |
| \image application-menus.png The Application example's menu system |
| |
| The status bar at the bottom of the main window shows a |
| description of the menu item or toolbar button under the cursor. |
| |
| To keep the example simple, recently opened files aren't shown in |
| the \uicontrol{File} menu, even though this feature is desired in 90% |
| of applications. Furthermore, this example can only load one file at a |
| time. The \l{mainwindows/sdi}{SDI} and \l{mainwindows/mdi}{MDI} examples |
| show how to lift these restrictions and how to implement recently opened files |
| handling. |
| |
| \section1 MainWindow Class Definition |
| |
| Here's the class definition: |
| |
| \snippet mainwindows/application/mainwindow.h 0 |
| |
| The public API is restricted to the constructor. In the \c |
| protected section, we reimplement QWidget::closeEvent() to detect |
| when the user attempts to close the window, and warn the user |
| about unsaved changes. In the \c{private slots} section, we |
| declare slots that correspond to menu entries, as well as a |
| mysterious \c documentWasModified() slot. Finally, in the \c |
| private section of the class, we have various members that will |
| be explained in due time. |
| |
| \section1 MainWindow Class Implementation |
| |
| \snippet mainwindows/application/mainwindow.cpp 0 |
| |
| We start by including \c <QtWidgets>, a header file that contains the |
| definition of all classes in the Qt Core, Qt GUI and Qt Widgets |
| modules. This saves us from the trouble of having to include |
| every class individually. We also include \c mainwindow.h. |
| |
| You might wonder why we don't include \c <QtWidgets> in \c |
| mainwindow.h and be done with it. The reason is that including |
| such a large header from another header file can rapidly degrade |
| performances. Here, it wouldn't do any harm, but it's still |
| generally a good idea to include only the header files that are |
| strictly necessary from another header file. |
| |
| \snippet mainwindows/application/mainwindow.cpp 1 |
| \snippet mainwindows/application/mainwindow.cpp 2 |
| |
| In the constructor, we start by creating a QPlainTextEdit widget as a |
| child of the main window (the \c this object). Then we call |
| QMainWindow::setCentralWidget() to tell that this is going to be |
| the widget that occupies the central area of the main window, |
| between the toolbars and the status bar. |
| |
| Then we call \c createActions() and \c createStatusBar(), two private |
| functions that set up the user interface. After that, we call \c |
| readSettings() to restore the user's preferences. |
| |
| We establish a signal-slot connection between the QPlainTextEdit's |
| document object and our \c documentWasModified() slot. Whenever |
| the user modifies the text in the QPlainTextEdit, we want to update |
| the title bar to show that the file was modified. |
| |
| At the end, we set the window title using the private |
| \c setCurrentFile() function. We'll come back to this later. |
| |
| \target close event handler |
| \snippet mainwindows/application/mainwindow.cpp 3 |
| \snippet mainwindows/application/mainwindow.cpp 4 |
| |
| When the user attempts to close the window, we call the private |
| function \c maybeSave() to give the user the possibility to save |
| pending changes. The function returns true if the user wants the |
| application to close; otherwise, it returns false. In the first |
| case, we save the user's preferences to disk and accept the close |
| event; in the second case, we ignore the close event, meaning |
| that the application will stay up and running as if nothing |
| happened. |
| |
| \snippet mainwindows/application/mainwindow.cpp 5 |
| \snippet mainwindows/application/mainwindow.cpp 6 |
| |
| The \c newFile() slot is invoked when the user selects |
| \uicontrol{File|New} from the menu. We call \c maybeSave() to save any |
| pending changes and if the user accepts to go on, we clear the |
| QPlainTextEdit and call the private function \c setCurrentFile() to |
| update the window title and clear the |
| \l{QWidget::windowModified}{windowModified} flag. |
| |
| \snippet mainwindows/application/mainwindow.cpp 7 |
| \snippet mainwindows/application/mainwindow.cpp 8 |
| |
| The \c open() slot is invoked when the user clicks |
| \uicontrol{File|Open}. We pop up a QFileDialog asking the user to |
| choose a file. If the user chooses a file (i.e., \c fileName is |
| not an empty string), we call the private function \c loadFile() |
| to actually load the file. |
| |
| \snippet mainwindows/application/mainwindow.cpp 9 |
| \snippet mainwindows/application/mainwindow.cpp 10 |
| |
| The \c save() slot is invoked when the user clicks |
| \uicontrol{File|Save}. If the user hasn't provided a name for the file |
| yet, we call \c saveAs(); otherwise, we call the private function |
| \c saveFile() to actually save the file. |
| |
| \snippet mainwindows/application/mainwindow.cpp 11 |
| \snippet mainwindows/application/mainwindow.cpp 12 |
| |
| In \c saveAs(), we start by popping up a QFileDialog asking the |
| user to provide a name. If the user clicks \uicontrol{Cancel}, the |
| returned file name is empty, and we do nothing. |
| |
| \snippet mainwindows/application/mainwindow.cpp 13 |
| \snippet mainwindows/application/mainwindow.cpp 14 |
| |
| The application's About box is done using one statement, using |
| the QMessageBox::about() static function and relying on its |
| support for an HTML subset. |
| |
| The \l{QObject::tr()}{tr()} call around the literal string marks |
| the string for translation. It is a good habit to call |
| \l{QObject::tr()}{tr()} on all user-visible strings, in case you |
| later decide to translate your application to other languages. |
| The \l{Internationalization with Qt} overview covers |
| \l{QObject::tr()}{tr()} in more detail. |
| |
| \snippet mainwindows/application/mainwindow.cpp 15 |
| \snippet mainwindows/application/mainwindow.cpp 16 |
| |
| The \c documentWasModified() slot is invoked each time the text |
| in the QPlainTextEdit changes because of user edits. We call |
| QWidget::setWindowModified() to make the title bar show that the |
| file was modified. How this is done varies on each platform. |
| |
| \snippet mainwindows/application/mainwindow.cpp 17 |
| \snippet mainwindows/application/mainwindow.cpp 18 |
| \dots |
| \snippet mainwindows/application/mainwindow.cpp 22 |
| |
| The \c createActions() private function, which is called from the |
| \c MainWindow constructor, creates \l{QAction}s and populates |
| the menus and two toolbars. The code is very |
| repetitive, so we show only the actions corresponding to |
| \uicontrol{File|New}, \uicontrol{File|Open}, and \uicontrol{Help|About Qt}. |
| |
| A QAction is an object that represents one user action, such as |
| saving a file or invoking a dialog. An action can be put in a |
| QMenu or a QToolBar, or both, or in any other widget that |
| reimplements QWidget::actionEvent(). |
| |
| An action has a text that is shown in the menu, an icon, a |
| shortcut key, a tooltip, a status tip (shown in the status bar), |
| a "What's This?" text, and more. It emits a |
| \l{QAction::triggered()}{triggered()} signal whenever the user |
| invokes the action (e.g., by clicking the associated menu item or |
| toolbar button). |
| |
| Instances of QAction can be created by passing a parent QObject or |
| by using one of the convenience functions of QMenu, QMenuBar or QToolBar. |
| We create the actions that are in a menu as well as in a toolbar |
| parented on the window to prevent ownership issues. For actions |
| that are only in the menu, we use the convenience function |
| QMenu::addAction(), which allows us to pass text, icon and the |
| target object and its slot member function. |
| |
| Creating toolbars is very similar to creating menus. The same |
| actions that we put in the menus can be reused in the toolbars. |
| After creating the action, we add it to the toolbar using |
| QToolBar::addAction(). |
| |
| The code above contains one more idiom that must be explained. |
| For some of the actions, we specify an icon as a QIcon to the |
| QAction constructor. We use QIcon::fromTheme() to obtain |
| the correct standard icon from the underlying window system. |
| If that fails due to the platform not supporting it, we |
| pass a file name as fallback. Here, the file name starts |
| with \c{:}. Such file names aren't ordinary file names, but |
| rather path in the executable's stored resources. We'll come back |
| to this when we review the \c application.qrc file that's part of |
| the project. |
| |
| \snippet mainwindows/application/mainwindow.cpp 23 |
| \snippet mainwindows/application/mainwindow.cpp 24 |
| |
| The \uicontrol{Edit|Cut} and \uicontrol{Edit|Copy} actions must be available |
| only when the QPlainTextEdit contains selected text. We disable them |
| by default and connect the QPlainTextEdit::copyAvailable() signal to |
| the QAction::setEnabled() slot, ensuring that the actions are |
| disabled when the text editor has no selection. |
| |
| Just before we create the \uicontrol{Help} menu, we call |
| QMenuBar::addSeparator(). This has no effect for most widget |
| styles (e.g., Windows and \macos styles), but for some |
| styles this makes sure that \uicontrol{Help} is pushed to the right |
| side of the menu bar. |
| |
| \snippet mainwindows/application/mainwindow.cpp 32 |
| \snippet mainwindows/application/mainwindow.cpp 33 |
| |
| QMainWindow::statusBar() returns a pointer to the main window's |
| QStatusBar widget. Like with \l{QMainWindow::menuBar()}, the |
| widget is automatically created the first time the function is |
| called. |
| |
| \snippet mainwindows/application/mainwindow.cpp 34 |
| \snippet mainwindows/application/mainwindow.cpp 36 |
| |
| The \c readSettings() function is called from the constructor to |
| load the user's preferences and other application settings. The |
| QSettings class provides a high-level interface for storing |
| settings permanently on disk. On Windows, it uses the (in)famous |
| Windows registry; on \macos, it uses the native XML-based |
| CFPreferences API; on Unix/X11, it uses text files. |
| |
| The QSettings constructor takes arguments that identify your |
| company and the name of the product. This ensures that the |
| settings for different applications are kept separately. |
| |
| We use QSettings::value() to extract the value of the geometry setting. |
| The second argument to QSettings::value() is |
| optional and specifies a default value for the setting if there |
| exists none. This value is used the first time the application is |
| run. |
| |
| We use QWidget::saveGeometry() and Widget::restoreGeometry() to |
| save the position. They use an opaque QByteArray to store |
| screen number, geometry and window state. |
| |
| \snippet mainwindows/application/mainwindow.cpp 37 |
| \snippet mainwindows/application/mainwindow.cpp 39 |
| |
| The \c writeSettings() function is called from \c closeEvent(). |
| Writing settings is similar to reading them, except simpler. The |
| arguments to the QSettings constructor must be the same as in \c |
| readSettings(). |
| |
| \snippet mainwindows/application/mainwindow.cpp 40 |
| \snippet mainwindows/application/mainwindow.cpp 41 |
| |
| The \c maybeSave() function is called to save pending changes. If |
| there are pending changes, it pops up a QMessageBox giving the |
| user to save the document. The options are QMessageBox::Yes, |
| QMessageBox::No, and QMessageBox::Cancel. The \uicontrol{Yes} button is |
| made the default button (the button that is invoked when the user |
| presses \uicontrol{Return}) using the QMessageBox::Default flag; the |
| \uicontrol{Cancel} button is made the escape button (the button that is |
| invoked when the user presses \uicontrol{Esc}) using the |
| QMessageBox::Escape flag. |
| |
| The \c maybeSave() function returns \c true in all cases, except |
| when the user clicks \uicontrol{Cancel} or saving the file fails. |
| The caller must check the return value and stop whatever it was |
| doing if the return value is \c false. |
| |
| \snippet mainwindows/application/mainwindow.cpp 42 |
| \snippet mainwindows/application/mainwindow.cpp 43 |
| |
| In \c loadFile(), we use QFile and QTextStream to read in the |
| data. The QFile object provides access to the bytes stored in a |
| file. |
| |
| We start by opening the file in read-only mode. The QFile::Text |
| flag indicates that the file is a text file, not a binary file. |
| On Unix and \macos, this makes no difference, but on Windows, |
| it ensures that the "\\r\\n" end-of-line sequence is converted to |
| "\\n" when reading. |
| |
| If we successfully opened the file, we use a QTextStream object |
| to read in the data. QTextStream automatically converts the 8-bit |
| data into a Unicode QString and supports various encodings. If no |
| encoding is specified, QTextStream assumes the file is written |
| using the system's default 8-bit encoding (for example, Latin-1; |
| see QTextCodec::codecForLocale() for details). |
| |
| Since the call to QTextStream::readAll() might take some time, we |
| set the cursor to be Qt::WaitCursor for the entire application |
| while it goes on. |
| |
| At the end, we call the private \c setCurrentFile() function, |
| which we'll cover in a moment, and we display the string "File |
| loaded" in the status bar for 2 seconds (2000 milliseconds). |
| |
| \snippet mainwindows/application/mainwindow.cpp 44 |
| \snippet mainwindows/application/mainwindow.cpp 45 |
| |
| Saving a file is similar to loading one. We use QSaveFile to ensure |
| all data are safely written and existing files are not damaged |
| should writing fail. |
| We use the QFile::Text flag to make sure that on Windows, "\\n" |
| is converted into "\\r\\n" to conform to the Windows convention. |
| |
| |
| \snippet mainwindows/application/mainwindow.cpp 46 |
| \snippet mainwindows/application/mainwindow.cpp 47 |
| |
| The \c setCurrentFile() function is called to reset the state of |
| a few variables when a file is loaded or saved, or when the user |
| starts editing a new file (in which case \c fileName is empty). |
| We update the \c curFile variable, clear the |
| QTextDocument::modified flag and the associated \c |
| QWidget:windowModified flag, and update the window title to |
| contain the new file name (or \c untitled.txt). |
| |
| The \c strippedName() function call around \c curFile in the |
| QWidget::setWindowTitle() call shortens the file name to exclude |
| the path. Here's the function: |
| |
| \snippet mainwindows/application/mainwindow.cpp 48 |
| \snippet mainwindows/application/mainwindow.cpp 49 |
| |
| \section1 The main() Function |
| |
| The \c main() function for this application is typical of |
| applications that contain one main window: |
| |
| \snippet mainwindows/application/main.cpp 0 |
| |
| The main function uses QCommandLineParser to check whether some file |
| argument was passed to the application and loads it via |
| MainWindow::loadFile(). |
| |
| \section1 The Resource File |
| |
| As you will probably recall, for some of the actions, we |
| specified icons with file names starting with \c{:} and mentioned |
| that such file names aren't ordinary file names, but path in the |
| executable's stored resources. These resources are compiled |
| |
| The resources associated with an application are specified in a |
| \c .qrc file, an XML-based file format that lists files on the |
| disk. Here's the \c application.qrc file that's used by the |
| Application example: |
| |
| \quotefile mainwindows/application/application.qrc |
| |
| The \c .png files listed in the \c application.qrc file are files |
| that are part of the Application example's source tree. Paths are |
| relative to the directory where the \c application.qrc file is |
| located (the \c mainwindows/application directory). |
| |
| The resource file must be mentioned in the \c application.pro |
| file so that \c qmake knows about it: |
| |
| \snippet mainwindows/application/application.pro 0 |
| |
| \c qmake will produce make rules to generate a file called \c |
| qrc_application.cpp that is linked into the application. This |
| file contains all the data for the images and other resources as |
| static C++ arrays of compressed binary data. See |
| \l{resources.html}{The Qt Resource System} for more information |
| about resources. |
| */ |
