Long live Qt 4.5!

1 files changed, 177 insertions, 0 deletions

diff --git a/doc/src/examples/dockwidgets.qdoc b/doc/src/examples/dockwidgets.qdoc
new file mode 100644
index 0000000..bc9f5f1
--- /dev/null
+++ b/doc/src/examples/dockwidgets.qdoc
@@ -0,0 +1,177 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@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.
+*/