From 30356a121cc6dff76c20409fd5648b5abb8ceb4e Mon Sep 17 00:00:00 2001 From: David Boddie Date: Thu, 26 Mar 2009 17:46:24 +0100 Subject: Squashed commit of the following: commit 23e30464792f7e403e0815775eb7acbaad975238 Author: David Boddie Date: Thu Mar 26 17:41:20 2009 +0100 Doc: Added some basic documentation for the QSvgGenerator class. Task-number: 244944 Reviewed-by: TrustMe commit f84c1806d2ba40a61499584562d754f65d43f854 Merge: 8a42be7... 213d922... Author: David Boddie Date: Thu Mar 26 16:59:14 2009 +0100 Merge branch '4.5' of ../qt-45 into qt/4.5 commit 8a42be789077de45f8fd9f13afd177798df7495e Author: David Boddie Date: Thu Mar 26 16:58:33 2009 +0100 Doc: Added missing pieces for the SVG Generator example. Reviewed-by: David Boddie --- demos/qtdemo/xml/examples.xml | 1 + doc/src/examples/svggenerator.qdoc | 136 +++++++++++++++++++++++++++++++++++++ examples/painting/painting.pro | 2 +- src/svg/qsvggenerator.cpp | 29 +++++++- 4 files changed, 166 insertions(+), 2 deletions(-) create mode 100644 doc/src/examples/svggenerator.qdoc diff --git a/demos/qtdemo/xml/examples.xml b/demos/qtdemo/xml/examples.xml index df2d93b..03b59f3 100644 --- a/demos/qtdemo/xml/examples.xml +++ b/demos/qtdemo/xml/examples.xml @@ -137,6 +137,7 @@ + diff --git a/doc/src/examples/svggenerator.qdoc b/doc/src/examples/svggenerator.qdoc new file mode 100644 index 0000000..32bb89a --- /dev/null +++ b/doc/src/examples/svggenerator.qdoc @@ -0,0 +1,136 @@ +/**************************************************************************** +** +** 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 painting/svggenerator + \title SVG Generator Example + + The SVG Generator example shows how to add SVG file export to applications. + + \image svggenerator-example.png + + Scalable Vector Graphics (SVG) is an XML-based language for describing + two-dimensional vector graphics. Qt provides classes for rendering and + generating SVG drawings. This example allows the user to create a simple + picture and save it to an SVG file. + + The example consists of two classes: \c Window and \c DisplayWidget. + + The \c Window class contains the application logic and constructs the user + interface from a Qt Designer \c{.ui} file as described in the + \l{Using a Designer .ui File in Your Application#The Multiple Inheritance Approach}{Qt Designer manual}. + It also contains the code to write an SVG file. + + The \c DisplayWidget class performs all the work of painting a picture on + screen. Since we want the SVG to resemble this picture as closely as + possible, we make this code available to the \c Window class so that it can + be used to generate SVG files. + + \section1 The DisplayWidget Class + + The \c DisplayWidget class displays a drawing consisting of a selection of + elements chosen by the user. These are defined using \c Shape and + \c Background enums that are included within the class definition: + + \snippet examples/painting/svggenerator/displaywidget.h DisplayWidget class definition + + Much of this class is used to configure the appearance of the drawing. The + \c paintEvent() and \c paint() functions are most relevant to the purpose + of this example, so we will describe these here and leave the reader to + look at the source code for the example to see how shapes and colors are + handled. + + We reimplement the QWidget::paintEvent() function to display the drawing + on screen: + + \snippet examples/painting/svggenerator/displaywidget.cpp paint event + + Here, we only construct a QPainter object, begin painting on the device + and set a render hint for improved output quality before calling the + \c paint() function to perform the painting itself. When this returns, + we close the painter and return. + + The \c paint() function is designed to be used for different painting + tasks. In this example, we use it to draw on a \c DisplayWidget instance + and on a QSvgGenerator object. We show how the painting is performed to + demonstrate that there is nothing device-specific about the process: + + \snippet examples/painting/svggenerator/displaywidget.cpp paint function + + \section1 The Window Class + + The \c Window class represents the example's window, containing the user + interface, which has been created using Qt Designer: + + \snippet examples/painting/svggenerator/window.h Window class definition + + As with the \c DisplayWidget class, we concentrate on the parts of the code + which are concerned with painting and SVG generation. In the \c Window + class, the \c saveSvg() function is called whenever the \gui{Save As...} + button is clicked; this connection was defined in the \c{window.ui} file + using Qt Designer. + + The start of the \c saveSvg() function performs the task of showing a file + dialog so that the user can specify a SVG file to save the drawing to. + + \snippet examples/painting/svggenerator/window.cpp save SVG + + In the rest of the function, we set up the generator and configure it to + generate output with the appropriate dimensions and write to the + user-specified file. We paint on the QSvgGenerator object in the same way + that we paint on a widget, calling the \c DisplayWidget::paint() function + so that we use exactly the same code that we used to display the drawing. + + The generation process itself begins with the call to the painter's + \l{QPainter::}{begin()} function and ends with call to its + \l{QPainter::}{end()} function. The QSvgGenerator paint device relies on + the explicit use of these functions to ensure that output is written to + the file. + + \section1 Further Reading + + The \l{SVG Viewer Example} shows how to display SVG drawings in an + application, and can be used to show the contents of SVG files created + by this example. + + See the QtSvg module documentation for more information about SVG and Qt's + SVG classes. +*/ diff --git a/examples/painting/painting.pro b/examples/painting/painting.pro index b6fad5a..6d00720 100644 --- a/examples/painting/painting.pro +++ b/examples/painting/painting.pro @@ -7,7 +7,7 @@ SUBDIRS = basicdrawing \ !wince*: SUBDIRS += fontsampler -contains(QT_CONFIG, svg): SUBDIRS += svgviewer +contains(QT_CONFIG, svg): SUBDIRS += svggenerator svgviewer # install target.path = $$[QT_INSTALL_EXAMPLES]/painting diff --git a/src/svg/qsvggenerator.cpp b/src/svg/qsvggenerator.cpp index f7b2ae8..e822da5 100644 --- a/src/svg/qsvggenerator.cpp +++ b/src/svg/qsvggenerator.cpp @@ -516,7 +516,34 @@ public: \brief The QSvgGenerator class provides a paint device that is used to create SVG drawings. \reentrant - \sa QSvgRenderer, QSvgWidget + This paint device represents a Scalable Vector Graphics (SVG) drawing. Like QPrinter, it is + designed as a write-only device that generates output in a specific format. + + To write an SVG file, you first need to configure the output by setting the \l fileName + or \l outputDevice properties. It is usually necessary to specify the size of the drawing + by setting the \l size property, and in some cases where the drawing will be included in + another, the \l viewBox property also needs to be set. + + \snippet examples/painting/svggenerator/window.cpp configure SVG generator + + Other meta-data can be specified by setting the \a title, \a description and \a resolution + properties. + + As with other QPaintDevice subclasses, a QPainter object is used to paint onto an instance + of this class: + + \snippet examples/painting/svggenerator/window.cpp begin painting + \dots + \snippet examples/painting/svggenerator/window.cpp end painting + + Painting is performed in the same way as for any other paint device. However, + it is necessary to use the QPainter::begin() and \l{QPainter::}{end()} to + explicitly begin and end painting on the device. + + The \l{SVG Generator Example} shows how the same painting commands can be used + for painting a widget and writing an SVG file. + + \sa QSvgRenderer, QSvgWidget, {About SVG} */ /*! -- cgit v0.12