diff options
Diffstat (limited to 'doc/src/examples/dockwidgets.qdoc')
| -rw-r--r-- | doc/src/examples/dockwidgets.qdoc | 163 |
1 files changed, 163 insertions, 0 deletions
diff --git a/doc/src/examples/dockwidgets.qdoc b/doc/src/examples/dockwidgets.qdoc new file mode 100644 index 0000000000..98c1216b6b --- /dev/null +++ b/doc/src/examples/dockwidgets.qdoc @@ -0,0 +1,163 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example mainwindows/dockwidgets + \title Dock Widgets Example + + 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 examples/mainwindows/dockwidgets/mainwindow.h 0 + + We will now review each function in turn. + + \section1 MainWindow Class Implementation + + \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 0 + + We start by including \c <QtGui>, a header file that contains the + definition of all classes in the \l QtCore and \l QtGui + libraries. 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 examples/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 examples/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 examples/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 examples/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 examples/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 examples/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 examples/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 examples/mainwindows/dockwidgets/mainwindow.cpp 5 + + If the focus is in the QTextEdit, pressing \key 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. +*/ |