From d6357e11474284ddfdb2e860d9661bdf0290ec9b Mon Sep 17 00:00:00 2001 From: Nico Vertriest Date: Fri, 19 Dec 2014 10:44:57 +0100 Subject: Doc: corrected links text object example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Task-number: QTBUG-43462 Change-Id: I9c5092d68b767cafe2c98838e32b205311105452 Reviewed-by: Topi Reiniö --- .../textobject/doc/images/textobject-example.png | Bin 0 -> 16591 bytes .../richtext/textobject/doc/src/textobject.qdoc | 156 +++++++++++++++++++++ 2 files changed, 156 insertions(+) create mode 100644 examples/svg/richtext/textobject/doc/images/textobject-example.png create mode 100644 examples/svg/richtext/textobject/doc/src/textobject.qdoc (limited to 'examples/svg') diff --git a/examples/svg/richtext/textobject/doc/images/textobject-example.png b/examples/svg/richtext/textobject/doc/images/textobject-example.png new file mode 100644 index 0000000..626c102 Binary files /dev/null and b/examples/svg/richtext/textobject/doc/images/textobject-example.png differ diff --git a/examples/svg/richtext/textobject/doc/src/textobject.qdoc b/examples/svg/richtext/textobject/doc/src/textobject.qdoc new file mode 100644 index 0000000..79c90e1 --- /dev/null +++ b/examples/svg/richtext/textobject/doc/src/textobject.qdoc @@ -0,0 +1,156 @@ +/**************************************************************************** +** +** Copyright (C) 2013 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: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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example richtext/textobject + \title Text Object Example + + The Text Object example shows how to insert an SVG file into a + QTextDocument. + + \image textobject-example.png + + A QTextDocument consists of a hierarchy of elements, such as text blocks and + frames. A text object describes the structure or format of one or more of these + elements. For instance, images imported from HTML are implemented using text + objects. Text objects are used by the document's + \l{QAbstractTextDocumentLayout}{layout} to lay out and render (paint) the + document. Each object knows how to paint the elements they govern, and + calculates their size. + + To be able to insert an SVG image into a text document, we create + a text object, and implement painting for that object. This object + can then be \l{QTextCharFormat::setObjectType()}{set} on a + QTextCharFormat. We also register the text object with the layout + of the document, enabling it to draw \l{QTextCharFormat}s governed + by our text object. We can summarize the procedure with the + following steps: + + \list + \li Implement the text object. + \li Register the text object with the layout of the text + document. + \li Set the text object on a QTextCharFormat. + \li Insert a QChar::ObjectReplacementCharacter with that + text char format into the document. + \endlist + + The example consists of the following classes: + + \list + \li \c{SvgTextObject} implements the text object. + \li \c{Window} shows a QTextEdit into which SVG images can be + inserted. + \endlist + + \section1 SvgTextObject Class Definition + + Let's take a look at the header file of \c {SvgTextObject}: + + \snippet richtext/textobject/svgtextobject.h 0 + + A text object is a QObject that implements QTextObjectInterface. + Note that the first class inherited must be QObject, and that + you must use Q_INTERFACES to let Qt know that your class + implements QTextObjectInterface. + + The document layout keeps a collection of text objects stored as + \l{QObject}s, each of which has an associated object type. The + layout casts the QObject for the associated object type into the + QTextObjectInterface. + + The \l{QTextObjectInterface::}{intrinsicSize()} and + \l{QTextObjectInterface::}{drawObject()} functions are then used + to calculate the size of the text object and draw it. + + \section1 SvgTextObject Class Implementation + + We start of by taking a look at the + \l{QTextObjectInterface::}{intrinsicSize()} function: + + \snippet richtext/textobject/svgtextobject.cpp 0 + + \c intrinsicSize() is called by the layout to calculate the size + of the text object. Notice that we have drawn the SVG image on a + QImage. This is because SVG rendering is quite expensive. The + example would lag seriously for large images if we drew them + with a QSvgRenderer each time. + + \snippet richtext/textobject/svgtextobject.cpp 1 + + In \c drawObject(), we paint the SVG image using the QPainter + provided by the layout. + + \section1 Window Class Definition + + The \c Window class is a self-contained window that has a + QTextEdit in which SVG images can be inserted. + + \snippet richtext/textobject/window.h 0 + + The \c insertTextObject() slot inserts an SVG image at the current + cursor position, while \c setupTextObject() creates and registers + the SvgTextObject with the layout of the text edit's document. + + The constructor simply calls \c setupTextObject() and \c + setupGui(), which creates and lays out the widgets of the \c + Window. + + \section1 Window Class Implementation + + We will now take a closer look at the functions that are relevant + to our text object, starting with the \c setupTextObject() + function. + + \snippet richtext/textobject/window.cpp 3 + + \c {SvgTextFormat}'s value is the number of our object type. It is + used to identify object types by the document layout. + + Note that we only create one SvgTextObject instance; it will be + used for all QTextCharFormat's with the \c SvgTextFormat object + type. + + Let's move on to the \c insertTextObject() function: + + \snippet richtext/textobject/window.cpp 1 + + First, the \c .svg file is opened and its contents are read + into the \c svgData array. + + \snippet richtext/textobject/window.cpp 2 + + To speed things up, we buffer the SVG image in a QImage. We use + \l{QTextFormat::}{setProperty()} to store the QImage in the in the + QTextCharFormat. We can retrieve it later with + \l{QTextCharFormat::}{property()}. + + We insert the char format in the standard way - using a + QTextCursor. Notice that we use the special QChar + \l{QChar::}{ObjectReplacementCharacter}. +*/ + -- cgit v1.2.1