diff options
Diffstat (limited to 'doc/src/examples')
| -rw-r--r-- | doc/src/examples/collidingmice-example.qdoc | 39 | ||||
| -rw-r--r-- | doc/src/examples/customtype.qdoc | 157 | ||||
| -rw-r--r-- | doc/src/examples/customtypesending.qdoc | 128 | ||||
| -rw-r--r-- | doc/src/examples/extension.qdoc | 11 | ||||
| -rw-r--r-- | doc/src/examples/queuedcustomtype.qdoc | 177 | ||||
| -rw-r--r-- | doc/src/examples/qxmlstreambookmarks.qdoc | 5 | ||||
| -rw-r--r-- | doc/src/examples/svggenerator.qdoc | 136 |
7 files changed, 627 insertions, 26 deletions
diff --git a/doc/src/examples/collidingmice-example.qdoc b/doc/src/examples/collidingmice-example.qdoc index 7ea2ca2..657a204 100644 --- a/doc/src/examples/collidingmice-example.qdoc +++ b/doc/src/examples/collidingmice-example.qdoc @@ -66,7 +66,7 @@ \section1 Mouse Class Definition - The \c mouse class inherits both QObject and QGraphicsItem. The + The \c mouse class inherits from QGraphicsItem. The QGraphicsItem class is the base class for all graphical items in the Graphics View framework, and provides a light-weight foundation for writing your own custom items. @@ -78,14 +78,11 @@ {QGraphicsItem::}{boundingRect()}, which returns an estimate of the area painted by the item, and \l {QGraphicsItem::}{paint()}, which implements the actual painting. In addition, we reimplement - the \l {QGraphicsItem::}{shape()} function to return an accurate + the \l {QGraphicsItem::}{shape()} and \l {QGraphicsItem::}{advance()}. + We reimplement \l {QGraphicsItem::}{shape()} to return an accurate shape of our mouse item; the default implementation simply returns - the item's bounding rectangle. - - The rationale for deriving from QObject in addition to - QGraphicsItem is to be able to animate our items by reimplementing - QObject's \l {QObject::}{timerEvent()} function and use - QObject::startTimer() to generate timer events. + the item's bounding rectangle. We reimplement \l {QGraphicsItem::}{advance()} + to handle the animation so it all happens on one update. \section1 Mouse Class Definition @@ -105,19 +102,18 @@ calling the item's \l {QGraphicsItem::rotate()}{rotate()} function we alter the direction in which the mouse will start moving. - In the end we call QObject's \l {QObject::}{startTimer()} - function, emitting a timer event every 1000/33 millisecond. This - enables us to animate our mouse item using our reimplementation of - the \l {QObject::}{timerEvent()} function; whenever a mouse - receives a timer event it will trigger \l - {QObject::}{timerEvent()}: - + When the QGraphicsScene decides to advance the scene a frame it will call + QGraphicsItem::advance() on each of the items. This enables us to animate + our mouse using our reimplementation of the advance() function. + \snippet examples/graphicsview/collidingmice/mouse.cpp 4 \snippet examples/graphicsview/collidingmice/mouse.cpp 5 \snippet examples/graphicsview/collidingmice/mouse.cpp 6 - First we ensure that the mice stays within a circle with a radius - of 150 pixels. + First, we don't bother doing any advance if the step is 0 since we want to our advance in + the actual advance (advance() is called twice, once with step == 0 indicating that items + are about to advance and with step == 1 for the actual advance). We also ensure that the + mice stays within a circle with a radius of 150 pixels. Note the \l {QGraphicsItem::mapFromScene()}{mapFromScene()} function provided by QGraphicsItem. This function maps a position @@ -275,5 +271,12 @@ In the end, we set the application window's title and size before we enter the main event loop using the QApplication::exec() function. -*/ + Finally, we create a QTimer and connect its timeout() signal to the advance() + slot of the scene. Every time the timer fires, the scene will advance one frame. + We then tell the timer to fire every 1000/33 millisecond. This will + give us a frame rate of 30 frames a second, which is fast enough for most animations. + Doing the animation with a single timer connect to advance the scene ensures that all the + mice are moved at one point and, more importantly, only one update is sent to the screen + after all the mice have moved. +*/
\ No newline at end of file diff --git a/doc/src/examples/customtype.qdoc b/doc/src/examples/customtype.qdoc new file mode 100644 index 0000000..ffeccc3 --- /dev/null +++ b/doc/src/examples/customtype.qdoc @@ -0,0 +1,157 @@ +/**************************************************************************** +** +** 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 tools/customtype + \title Custom Type Example + + The Custom Type example shows how to integrate a custom type into Qt's + meta-object system. + + Contents: + + \tableofcontents + + \section1 Overview + + Qt provides a range of standard value types that are used to provide + rich and meaningful APIs. These types are integrated with the meta-object + system, enabling them to be stored in QVariant objects, written out in + debugging information and sent between components in signal-slot + communication. + + Custom types can also be integrated with the meta-object system as long as + they are written to conform to some simple guidelines. In this example, we + introduce a simple \c Message class, we describe how we make it work with + QVariant, and we show how it can be extended to generate a printable + representation of itself for use in debugging output. + + \section1 The Message Class Definition + + The \c Message class is a simple value class that contains two pieces + of information (a QString and a QStringList), each of which can be read + using trivial getter functions: + + \snippet examples/tools/customtype/message.h custom type definition + + The default constructor, copy constructor and destructor are + all required, and must be public, if the type is to be integrated into the + meta-object system. Other than this, we are free to implement whatever we + need to make the type do what we want, so we also include a constructor + that lets us set the type's data members. + + To enable the type to be used with QVariant, we declare it using the + Q_DECLARE_METATYPE() macro: + + \snippet examples/tools/customtype/message.h custom type meta-type declaration + + We do not need to write any additional code to accompany this macro. + + To allow us to see a readable description of each \c Message object when it + is sent to the debug output stream, we define a streaming operator: + + \snippet examples/tools/customtype/message.h custom type streaming operator + + This facility is useful if you need to insert tracing statements in your + code for debugging purposes. + + \section1 The Message Class Implementation + + The implementation of the default constructor, copy constructor and destructor + are straightforward for the \c Message class: + + \snippet examples/tools/customtype/message.cpp Message class implementation + + The streaming operator is implemented in the following way: + + \snippet examples/tools/customtype/message.cpp custom type streaming operator + + Here, we want to represent each value depending on how many lines are stored + in the message body. We stream text to the QDebug object passed to the + operator and return the QDebug object obtained from its maybeSpace() member + function; this is described in more detail in the + \l{Creating Custom Qt Types#Making the Type Printable}{Creating Custom Qt Types} + document. + + We include the code for the getter functions for completeness: + + \snippet examples/tools/customtype/message.cpp getter functions + + With the type fully defined, implemented, and integrated with the + meta-object system, we can now use it. + + \section1 Using the Message + + In the example's \c{main()} function, we show how a \c Message object can + be printed to the console by sending it to the debug stream: + + \snippet examples/tools/customtype/main.cpp printing a custom type + + You can use the type with QVariant in exactly the same way as you would + use standard Qt value types. Here's how to store a value using the + QVariant::setValue() function: + + \snippet examples/tools/customtype/main.cpp storing a custom value + + Alternatively, the qVariantFromValue() and qVariantSetValue() functions + can be used if you are using a compiler without support for member template + functions. + + The value can be retrieved using the QVariant::value() member template + function: + + \snippet examples/tools/customtype/main.cpp retrieving a custom value + + Alternatively, the qVariantValue() template function can be used if + you are using a compiler without support for member template functions. + + \section1 Further Reading + + The custom \c Message type can also be used with direct signal-slot + connections; see the \l{Custom Type Sending Example} for a demonstration + of this. + To register a custom type for use with queued signals and slots, such as + those used in cross-thread communication, see the + \l{Queued Custom Type Example}. + + More information on using custom types with Qt can be found in the + \l{Creating Custom Qt Types} document. +*/ diff --git a/doc/src/examples/customtypesending.qdoc b/doc/src/examples/customtypesending.qdoc new file mode 100644 index 0000000..d335c28 --- /dev/null +++ b/doc/src/examples/customtypesending.qdoc @@ -0,0 +1,128 @@ +/**************************************************************************** +** +** 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 tools/customtypesending + \title Custom Type Sending Example + + The Custom Type Sending example shows how to use a custom type with signals + and slots. + + \image customtypesending-example.png + + Contents: + + \tableofcontents + + \section1 Overview + + In the \l{Custom Type Example}, we showed how to integrate custom types + with the meta-object system, enabling them to be stored in QVariant + objects, written out in debugging information and used in signal-slot + communication. + + In this example, we demonstrate that the preparations made to the + \c Message class and its declaration with Q_DECLARE_METATYPE() enable it + to be used with direct signal-slot connections. We do this by creating + a \c Window class containing signals and slots whose signatures include + \c Message arguments. + + \section1 The Window Class Definition + + We define a simple \c Window class with a signal and public slot that + allow a \c Message object to be sent via a signal-slot connection: + + \snippet examples/tools/customtypesending/window.h Window class definition + + The window will contain a text editor to show the contents of a message + and a push button that the user can click to send a message. To facilitate + this, we also define the \c sendMessage() slot. We also keep a \c Message + instance in the \c thisMessage private variable which holds the actual + message to be sent. + + \section1 The Window Class Implementation + + The \c Window constructor sets up a user interface containing a text + editor and a push button. + + \snippet examples/tools/customtypesending/window.cpp Window constructor + + The button's \l{QPushButton::}{clicked()} signal is connected to the + window's \c{sendMessage()} slot, which emits the \c{messageSent(Message)} + signal with the \c Message held by the \c thisMessage variable: + + \snippet examples/tools/customtypesending/window.cpp sending a message + + We implement a slot to allow the message to be received, and this also + lets us set the message in the window programatically: + + \snippet examples/tools/customtypesending/window.cpp receiving a message + + In this function, we simply assign the new message to \c thisMessage + and update the text in the editor. + + \section1 Making the Connection + + In the example's \c{main()} function, we perform the connection between + two instances of the \c Window class: + + \snippet examples/tools/customtypesending/main.cpp main function + + We set the message for the first window and connect the + \c{messageSent(Message)} signal from each window to the other's + \c{setMessage(Message)} slot. Since the signals and slots mechanism is only + concerned with the type, we can simplify the signatures of both the + signal and slot when we make the connection. + + When the user clicks on the \gui{Send message} button in either window, + the message shown will be emitted in a signal that the other window will + receive and display. + + \section1 Further Reading + + Although the custom \c Message type can be used with direct signals and + slots, an additional registration step needs to be performed if you want + to use it with queued signal-slot connections. See the + \l{Queued Custom Type Example} for details. + + More information on using custom types with Qt can be found in the + \l{Creating Custom Qt Types} document. +*/ diff --git a/doc/src/examples/extension.qdoc b/doc/src/examples/extension.qdoc index 8a0ca3a..02e0698 100644 --- a/doc/src/examples/extension.qdoc +++ b/doc/src/examples/extension.qdoc @@ -80,9 +80,9 @@ user type a word to search for, we need several \l {QCheckBox}{QCheckBox}es to facilitate the search options, and we need three \l {QPushButton}{QPushButton}s: the \gui Find button to - start a search, the \gui More button to enable an advanced search, - and the \gui Close button to exit the application. Finally, we - need a QWidget representing the application's extension part. + start a search and the \gui More button to enable an advanced search. + Finally, we need a QWidget representing the application's extension + part. \section1 FindDialog Class Implementation @@ -128,8 +128,7 @@ the connection makes sure that the extension widget is shown depending on the state of \gui More button. - We also connect the \gui Close button to the QWidget::close() - slot, and we put the checkboxes associated with the advanced + We also put the check boxes associated with the advanced search options into a layout we install on the extension widget. \snippet examples/dialogs/extension/finddialog.cpp 4 @@ -137,7 +136,7 @@ Before we create the main layout, we create several child layouts for the widgets: First we allign the QLabel ans its buddy, the QLineEdit, using a QHBoxLayout. Then we vertically allign the - QLabel and QLineEdit with the checkboxes associated with the + QLabel and QLineEdit with the check boxes associated with the simple search, using a QVBoxLayout. We also create a QVBoxLayout for the buttons. In the end we lay out the two latter layouts and the extension widget using a QGridLayout. diff --git a/doc/src/examples/queuedcustomtype.qdoc b/doc/src/examples/queuedcustomtype.qdoc new file mode 100644 index 0000000..bbd1427 --- /dev/null +++ b/doc/src/examples/queuedcustomtype.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 threads/queuedcustomtype + \title Queued Custom Type Example + + The Queued Custom Type example shows how to send custom types between + threads with queued signals and slots. + + \image queuedcustomtype-example.png + + Contents: + + \tableofcontents + + \section1 Overview + + In the \l{Custom Type Sending Example}, we showed how to use a custom type + with signal-slot communication within the same thread. + + In this example, we create a new value class, \c Block, and register it + with the meta-object system to enable us to send instances of it between + threads using queued signals and slots. + + \section1 The Block Class + + The \c Block class is similar to the \c Message class described in the + \l{Custom Type Example}. It provides the default constructor, copy + constructor and destructor in the public section of the class that the + meta-object system requires. It describes a colored rectangle. + + \snippet examples/threads/queuedcustomtype/block.h custom type definition and meta-type declaration + + We will still need to register it with the meta-object system at + run-time by calling the qRegisterMetaType() template function before + we make any signal-slot connections that use this type. + Even though we do not intend to use the type with QVariant in this example, + it is good practice to also declare the new type with Q_DECLARE_METATYPE(). + + The implementation of the \c Block class is trivial, so we avoid quoting + it here. + + \section1 The Window Class + + We define a simple \c Window class with a public slot that accepts a + \c Block object. The rest of the class is concerned with managing the + user interface and handling images. + + \snippet examples/threads/queuedcustomtype/window.h Window class definition + + The \c Window class also contains a worker thread, provided by a + \c RenderThread object. This will emit signals to send \c Block objects + to the window's \c addBlock(Block) slot. + + The parts of the \c Window class that are most relevant are the constructor + and the \c addBlock(Block) slot. + + The constructor creates a thread for rendering images, sets up a user + interface containing a label and two push buttons that are connected to + slots in the same class. + + \snippet examples/threads/queuedcustomtype/window.cpp Window constructor start + \snippet examples/threads/queuedcustomtype/window.cpp set up widgets and connections + \snippet examples/threads/queuedcustomtype/window.cpp connecting signal with custom type + + In the last of these connections, we connect a signal in the + \c RenderThread object to the \c addBlock(Block) slot in the window. + + \dots + \snippet examples/threads/queuedcustomtype/window.cpp Window constructor finish + + The rest of the constructor simply sets up the layout of the window. + + The \c addBlock(Block) slot receives blocks from the rendering thread via + the signal-slot connection set up in the constructor: + + \snippet examples/threads/queuedcustomtype/window.cpp Adding blocks to the display + + We simply paint these onto the label as they arrive. + + \section1 The RenderThread Class + + The \c RenderThread class processes an image, creating \c Block objects + and using the \c sendBlock(Block) signal to send them to other components + in the example. + + \snippet examples/threads/queuedcustomtype/renderthread.h RenderThread class definition + + The constructor and destructor are not quoted here. These take care of + setting up the thread's internal state and cleaning up when it is destroyed. + + Processing is started with the \c processImage() function, which calls the + \c RenderThread class's reimplementation of the QThread::run() function: + + \snippet examples/threads/queuedcustomtype/renderthread.cpp processing the image (start) + + Ignoring the details of the way the image is processed, we see that the + signal containing a block is emitted in the usual way: + + \dots + \snippet examples/threads/queuedcustomtype/renderthread.cpp processing the image (finish) + + Each signal that is emitted will be queued and delivered later to the + window's \c addBlock(Block) slot. + + \section1 Registering the Type + + In the example's \c{main()} function, we perform the registration of the + \c Block class as a custom type with the meta-object system by calling the + qRegisterMetaType() template function: + + \snippet examples/threads/queuedcustomtype/main.cpp main function + + This call is placed here to ensure that the type is registered before any + signal-slot connections are made that use it. + + The rest of the \c{main()} function is concerned with setting a seed for + the pseudo-random number generator, creating and showing the window, and + setting a default image. See the source code for the implementation of the + \c createImage() function. + + \section1 Further Reading + + This example showed how a custom type can be registered with the + meta-object system so that it can be used with signal-slot connections + between threads. For ordinary communication involving direct signals and + slots, it is enough to simply declare the type in the way described in the + \l{Custom Type Sending Example}. + + In practice, both the Q_DECLARE_METATYPE() macro and the qRegisterMetaType() + template function can be used to register custom types, but + qRegisterMetaType() is only required if you need to perform signal-slot + communication or need to create and destroy objects of the custom type + at run-time. + + More information on using custom types with Qt can be found in the + \l{Creating Custom Qt Types} document. +*/ diff --git a/doc/src/examples/qxmlstreambookmarks.qdoc b/doc/src/examples/qxmlstreambookmarks.qdoc index 7059043..fb3a1c1 100644 --- a/doc/src/examples/qxmlstreambookmarks.qdoc +++ b/doc/src/examples/qxmlstreambookmarks.qdoc @@ -103,8 +103,9 @@ The \c read() function accepts a QIODevice and sets it using \l{QXmlStreamReader::setDevice()}{setDevice()}. The actual process - of reading only takes place in event the file is a valid XBEL 1.0 - file. Otherwise, the \l{QXmlStreamReader::raiseError()} + of reading only takes place if the file is a valid XBEL 1.0 file. + Note that the XML input needs to be well-formed to be accepted by + QXmlStreamReader. Otherwise, the \l{QXmlStreamReader::raiseError()} {raiseError()} function is used to display an error message. \snippet examples/xml/streambookmarks/xbelreader.cpp 1 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. +*/ |