| /**************************************************************************** |
| ** |
| ** 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/dockwidgets |
| \title Dock Widgets Example |
| \ingroup examples-mainwindow |
| |
| \brief The Dock Widgets example shows how to add dock windows to an |
| application. It also shows how to use Qt's rich text engine. |
| |
| \image dockwidgets-example.png Screenshot of the Dock Widgets example |
| |
| The application presents a simple business letter template, and has |
| a list of customer names and addresses and a list of standard |
| phrases in two dock windows. The user can click a customer to have |
| their name and address inserted into the template, and click one or |
| more of the standard phrases. Errors can be corrected by clicking |
| the Undo button. Once the letter has been prepared it can be printed |
| or saved as HTML. |
| |
| \section1 MainWindow Class Definition |
| |
| Here's the class definition: |
| |
| \snippet mainwindows/dockwidgets/mainwindow.h 0 |
| |
| We will now review each function in turn. |
| |
| \section1 MainWindow Class Implementation |
| |
| \snippet mainwindows/dockwidgets/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 having to include |
| every class individually and is especially convenient if we add new |
| widgets. We also include \c mainwindow.h. |
| |
| \snippet mainwindows/dockwidgets/mainwindow.cpp 1 |
| |
| In the constructor, we start by creating a QTextEdit widget. Then we call |
| QMainWindow::setCentralWidget(). This function passes ownership of |
| the QTextEdit to the \c MainWindow and tells the \c MainWindow that |
| the QTextEdit will occupy the \c MainWindow's central area. |
| |
| Then we call \c createActions(), \c createMenus(), \c |
| createToolBars(), \c createStatusBar(), and \c createDockWindows() |
| to set up the user interface. Finally we call \c setWindowTitle() to |
| give the application a title, and \c newLetter() to create a new |
| letter template. |
| |
| We won't quote the \c createActions(), \c createMenus(), \c |
| createToolBars(), and \c createStatusBar() functions since they |
| follow the same pattern as all the other Qt examples. |
| |
| \snippet mainwindows/dockwidgets/mainwindow.cpp 9 |
| |
| We create the customers dock window first, and in addition to a |
| window title, we also pass it a \c this pointer so that it becomes a |
| child of \c MainWindow. Normally we don't have to pass a parent |
| because widgets are parented automatically when they are laid out: |
| but dock windows aren't laid out using layouts. |
| |
| We've chosen to restrict the customers dock window to the left and |
| right dock areas. (So the user cannot drag the dock window to the |
| top or bottom dock areas.) The user can drag the dock window out of |
| the dock areas entirely so that it becomes a free floating window. |
| We can change this (and whether the dock window is moveable or |
| closable) using QDockWidget::setFeatures(). |
| |
| Once we've created the dock window we create a list widget with the |
| dock window as parent, then we populate the list and make it the |
| dock window's widget. Finally we add the dock widget to the \c |
| MainWindow using \c addDockWidget(), choosing to put it in the right |
| dock area. |
| |
| We undertake a similar process for the paragraphs dock window, |
| except that we don't restrict which dock areas it can be dragged to. |
| |
| Finally we set up the signal-slot connections. If the user clicks a |
| customer or a paragraph their \c currentTextChanged() signal will be |
| emitted and we connect these to \c insertCustomer() and |
| addParagraph() passing the text that was clicked. |
| |
| We briefly discuss the rest of the implementation, but have now |
| covered everything relating to dock windows. |
| |
| \snippet mainwindows/dockwidgets/mainwindow.cpp 2 |
| |
| In this function we clear the QTextEdit so that it is empty. Next we |
| create a QTextCursor on the QTextEdit. We move the cursor to the |
| start of the document and create and format a frame. We then create |
| some character formats and a table format. We insert a table into |
| the document and insert the company's name and address into a table |
| using the table and character formats we created earlier. Then we |
| insert the skeleton of the letter including two markers \c NAME and |
| \c ADDRESS. We will also use the \c{Yours sincerely,} text as a marker. |
| |
| \snippet mainwindows/dockwidgets/mainwindow.cpp 6 |
| |
| If the user clicks a customer we split the customer details into |
| pieces. We then look for the \c NAME marker using the \c find() |
| function. This function selects the text it finds, so when we call |
| \c insertText() with the customer's name the name replaces the marker. |
| We then look for the \c ADDRESS marker and replace it with each line |
| of the customer's address. Notice that we wrapped all the insertions |
| between a \c beginEditBlock() and \c endEditBlock() pair. This means |
| that the entire name and address insertion is treated as a single |
| operation by the QTextEdit, so a single undo will revert all the |
| insertions. |
| |
| \snippet mainwindows/dockwidgets/mainwindow.cpp 7 |
| |
| This function works in a similar way to \c insertCustomer(). First |
| we look for the marker, in this case, \c {Yours sincerely,}, and then |
| replace it with the standard paragraph that the user clicked. Again |
| we use a \c beginEditBlock() ... \c endEditBlock() pair so that the |
| insertion can be undone as a single operation. |
| |
| \snippet mainwindows/dockwidgets/mainwindow.cpp 3 |
| |
| Qt's QTextDocument class makes printing documents easy. We simply |
| take the QTextEdit's QTextDocument, set up the printer and print the |
| document. |
| |
| \snippet mainwindows/dockwidgets/mainwindow.cpp 4 |
| |
| QTextEdit can output its contents in HTML format, so we prompt the |
| user for the name of an HTML file and if they provide one we simply |
| write the QTextEdit's contents in HTML format to the file. |
| |
| \snippet mainwindows/dockwidgets/mainwindow.cpp 5 |
| |
| If the focus is in the QTextEdit, pressing \uicontrol Ctrl+Z undoes as |
| expected. But for the user's convenience we provide an |
| application-wide undo function that simply calls the QTextEdit's |
| undo: this means that the user can undo regardless of where the |
| focus is in the application. |
| */ |
