diff options
Diffstat (limited to 'examples/widgets/doc/src/application.qdoc')
| -rw-r--r-- | examples/widgets/doc/src/application.qdoc | 395 |
1 files changed, 0 insertions, 395 deletions
diff --git a/examples/widgets/doc/src/application.qdoc b/examples/widgets/doc/src/application.qdoc deleted file mode 100644 index 334c8cb9f0..0000000000 --- a/examples/widgets/doc/src/application.qdoc +++ /dev/null @@ -1,395 +0,0 @@ -/**************************************************************************** -** -** 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 Qt Widgets - Application Example - \ingroup examples-mainwindow - - \brief The Application example shows how to implement a standard - widget 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 encoded in - UTF-8. - - 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. -*/ |