Qt GUI: Adding Rich Text Processing documentation from qtdoc

-included the snippets
-editing for technical accuracy still to be done.
-ported missing files from Qt 4

Change-Id: I0b2d27630b762c6518c08973a40b476d7852001d
Reviewed-by: Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@digia.com>

6 files changed, 466 insertions, 0 deletions

diff --git a/src/gui/doc/snippets/textdocument-frames/main.cpp b/src/gui/doc/snippets/textdocument-frames/main.cpp
new file mode 100644
index 0000000000..3c065cd138
--- /dev/null
+++ b/src/gui/doc/snippets/textdocument-frames/main.cpp
@@ -0,0 +1,53 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QtGui>
+
+#include "mainwindow.h"
+
+int main(int argc, char *argv[])
+{
+    QApplication app(argc, argv);
+    MainWindow *window = new MainWindow;
+    window->resize(480, 480);
+    window->show();
+    return app.exec();
+}
+
diff --git a/src/gui/doc/snippets/textdocument-frames/mainwindow.cpp b/src/gui/doc/snippets/textdocument-frames/mainwindow.cpp
new file mode 100644
index 0000000000..4fca7d02cd
--- /dev/null
+++ b/src/gui/doc/snippets/textdocument-frames/mainwindow.cpp
@@ -0,0 +1,161 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QtGui>
+
+#include "mainwindow.h"
+#include "xmlwriter.h"
+
+MainWindow::MainWindow()
+{
+    QMenu *fileMenu = new QMenu(tr("&File"));
+
+    QAction *saveAction = fileMenu->addAction(tr("&Save..."));
+    saveAction->setShortcut(tr("Ctrl+S"));
+
+    QAction *quitAction = fileMenu->addAction(tr("E&xit"));
+    quitAction->setShortcut(tr("Ctrl+Q"));
+
+    menuBar()->addMenu(fileMenu);
+    editor = new QTextEdit();
+
+    QTextCursor cursor(editor->textCursor());
+    cursor.movePosition(QTextCursor::Start);
+
+    QTextFrame *mainFrame = cursor.currentFrame();
+
+    QTextCharFormat plainCharFormat;
+    QTextCharFormat boldCharFormat;
+    boldCharFormat.setFontWeight(QFont::Bold);
+/*  main frame
+//! [0]
+    QTextFrame *mainFrame = cursor.currentFrame();
+    cursor.insertText(...);
+//! [0]
+*/
+    cursor.insertText("Text documents are represented by the "
+                      "QTextDocument class, rather than by QString objects. "
+                      "Each QTextDocument object contains information about "
+                      "the document's internal representation, its structure, "
+                      "and keeps track of modifications to provide undo/redo "
+                      "facilities. This approach allows features such as the "
+                      "layout management to be delegated to specialized "
+                      "classes, but also provides a focus for the framework.",
+                      plainCharFormat);
+
+//! [1]
+    QTextFrameFormat frameFormat;
+    frameFormat.setMargin(32);
+    frameFormat.setPadding(8);
+    frameFormat.setBorder(4);
+//! [1]
+    cursor.insertFrame(frameFormat);
+
+/*  insert frame
+//! [2]
+    cursor.insertFrame(frameFormat);
+    cursor.insertText(...);
+//! [2]
+*/
+    cursor.insertText("Documents are either converted from external sources "
+                      "or created from scratch using Qt. The creation process "
+                      "can done by an editor widget, such as QTextEdit, or by "
+                      "explicit calls to the Scribe API.", boldCharFormat);
+
+    cursor = mainFrame->lastCursorPosition();
+/*  last cursor
+//! [3]
+    cursor = mainFrame->lastCursorPosition();
+    cursor.insertText(...);
+//! [3]
+*/
+    cursor.insertText("There are two complementary ways to visualize the "
+                      "contents of a document: as a linear buffer that is "
+                      "used by editors to modify the contents, and as an "
+                      "object hierarchy containing structural information "
+                      "that is useful to layout engines. In the hierarchical "
+                      "model, the objects generally correspond to visual "
+                      "elements such as frames, tables, and lists. At a lower "
+                      "level, these elements describe properties such as the "
+                      "style of text used and its alignment. The linear "
+                      "representation of the document is used for editing and "
+                      "manipulation of the document's contents.",
+                      plainCharFormat);
+
+
+    connect(saveAction, SIGNAL(triggered()), this, SLOT(saveFile()));
+    connect(quitAction, SIGNAL(triggered()), this, SLOT(close()));
+
+    setCentralWidget(editor);
+    setWindowTitle(tr("Text Document Frames"));
+}
+
+void MainWindow::saveFile()
+{
+    QString fileName = QFileDialog::getSaveFileName(this,
+        tr("Save document as:"), "", tr("XML (*.xml)"));
+
+    if (!fileName.isEmpty()) {
+        if (writeXml(fileName))
+            setWindowTitle(fileName);
+        else
+            QMessageBox::warning(this, tr("Warning"),
+                tr("Failed to save the document."), QMessageBox::Cancel,
+                QMessageBox::NoButton);
+    }
+}
+bool MainWindow::writeXml(const QString &fileName)
+{
+    XmlWriter documentWriter(editor->document());
+
+    QDomDocument *domDocument = documentWriter.toXml();
+    QFile file(fileName);
+
+    if (file.open(QFile::WriteOnly)) {
+        QTextStream textStream(&file);
+        textStream.setCodec(QTextCodec::codecForName("UTF-8"));
+
+        textStream << domDocument->toString(1).toUtf8();
+        file.close();
+        return true;
+    }
+    else
+        return false;
+}
diff --git a/src/gui/doc/snippets/textdocument-frames/mainwindow.h b/src/gui/doc/snippets/textdocument-frames/mainwindow.h
new file mode 100644
index 0000000000..4f25902fb2
--- /dev/null
+++ b/src/gui/doc/snippets/textdocument-frames/mainwindow.h
@@ -0,0 +1,64 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef WINDOW_H
+#define WINDOW_H
+
+#include <QMainWindow>
+
+class QTextEdit;
+
+class MainWindow : public QMainWindow
+{
+    Q_OBJECT
+
+public:
+    MainWindow();
+
+public slots:
+    void saveFile();
+
+private:
+    bool writeXml(const QString &fileName);
+
+    QTextEdit *editor;
+};
+
+#endif
diff --git a/src/gui/doc/snippets/textdocument-frames/textdocument-frames.pro b/src/gui/doc/snippets/textdocument-frames/textdocument-frames.pro
new file mode 100644
index 0000000000..91ae50f491
--- /dev/null
+++ b/src/gui/doc/snippets/textdocument-frames/textdocument-frames.pro
@@ -0,0 +1,6 @@
+SOURCES     = main.cpp \
+              mainwindow.cpp \
+              xmlwriter.cpp
+HEADERS     = mainwindow.h \
+              xmlwriter.h
+QT          += xml
diff --git a/src/gui/doc/snippets/textdocument-frames/xmlwriter.cpp b/src/gui/doc/snippets/textdocument-frames/xmlwriter.cpp
new file mode 100644
index 0000000000..d4d8d83bda
--- /dev/null
+++ b/src/gui/doc/snippets/textdocument-frames/xmlwriter.cpp
@@ -0,0 +1,118 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QtGui>
+
+#include "xmlwriter.h"
+
+QDomDocument *XmlWriter::toXml()
+{
+    QDomImplementation implementation;
+    QDomDocumentType docType = implementation.createDocumentType(
+        "scribe-document", "scribe", "qt.nokia.com/scribe");
+
+    document = new QDomDocument(docType);
+
+    // ### This processing instruction is required to ensure that any kind
+    // of encoding is given when the document is written.
+    QDomProcessingInstruction process = document->createProcessingInstruction(
+        "xml", "version=\"1.0\" encoding=\"utf-8\"");
+    document->appendChild(process);
+
+    QDomElement documentElement = document->createElement("document");
+    document->appendChild(documentElement);
+
+//! [0]
+    QTextFrame *root = textDocument->rootFrame();
+//! [0]
+
+    if (root)
+        processFrame(documentElement, root);
+
+    return document;
+}
+
+void XmlWriter::processBlock(QDomElement &parent, const QTextBlock &block)
+{
+    QDomElement blockElement = document->createElement("block");
+    blockElement.setAttribute("position", block.position());
+    blockElement.setAttribute("length", block.length());
+    parent.appendChild(blockElement);
+
+    QTextBlock::iterator it;
+    for (it = block.begin(); !(it.atEnd()); ++it) {
+        QTextFragment fragment = it.fragment();
+
+        if (fragment.isValid()) {
+            QDomElement fragmentElement = document->createElement("fragment");
+            blockElement.appendChild(fragmentElement);
+
+            fragmentElement.setAttribute("length", fragment.length());
+            QDomText fragmentText = document->createTextNode(fragment.text());
+
+            fragmentElement.appendChild(fragmentText);
+        }
+    }
+}
+
+void XmlWriter::processFrame(QDomElement &parent, QTextFrame *frame)
+{
+    QDomElement frameElement = document->createElement("frame");
+    frameElement.setAttribute("begin", frame->firstPosition());
+    frameElement.setAttribute("end", frame->lastPosition());
+    parent.appendChild(frameElement);
+
+//! [1]
+    QDomElement frameElement = ...
+
+    QTextFrame::iterator it;
+    for (it = frame->begin(); !(it.atEnd()); ++it) {
+
+        QTextFrame *childFrame = it.currentFrame();
+        QTextBlock childBlock = it.currentBlock();
+
+        if (childFrame)
+//! [1] //! [2]
+            processFrame(frameElement, childFrame);
+        else if (childBlock.isValid())
+            processBlock(frameElement, childBlock);
+    }
+//! [2]
+}
diff --git a/src/gui/doc/snippets/textdocument-frames/xmlwriter.h b/src/gui/doc/snippets/textdocument-frames/xmlwriter.h
new file mode 100644
index 0000000000..5953d9346a
--- /dev/null
+++ b/src/gui/doc/snippets/textdocument-frames/xmlwriter.h
@@ -0,0 +1,64 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef XMLWRITER_H
+#define XMLWRITER_H
+
+#include <QDomDocument>
+
+class QTextDocument;
+
+class XmlWriter
+{
+public:
+    XmlWriter(QTextDocument *document) : textDocument(document) {}
+    QDomDocument *toXml();
+
+private:
+    void processBlock(QDomElement &parent, const QTextBlock &block);
+    void processFrame(QDomElement &parent, QTextFrame *frame);
+
+    QDomDocument *document;
+//! [0]
+    QTextDocument *textDocument;
+//! [0]
+};
+
+#endif