summaryrefslogtreecommitdiffstats
path: root/doc/src/gui
diff options
context:
space:
mode:
authorCasper van Donderen <casper.vandonderen@nokia.com>2012-05-07 15:50:31 +0200
committerMarius Storm-Olsen <marius.storm-olsen@nokia.com>2012-05-09 08:36:34 +0200
commitcfdc5628b1fc2cbafa2aebca38995e5718fcb0de (patch)
tree67615dc74faa944bf7745c9db001efa3594a3249 /doc/src/gui
parent3b8e6027c2f79bde70f9415f0757df073ef75702 (diff)
Doc: Modularize QtGui documentation.
This change moves the snippets and images to the modularized directories. Change-Id: I5f86f598fbe7c47d632c613b85d94ced89ba2c29 Reviewed-by: Marius Storm-Olsen <marius.storm-olsen@nokia.com>
Diffstat (limited to 'doc/src/gui')
-rw-r--r--doc/src/gui/coordsys.qdoc461
-rw-r--r--doc/src/gui/paintsystem.qdoc560
-rw-r--r--doc/src/gui/qtgui.qdoc39
3 files changed, 0 insertions, 1060 deletions
diff --git a/doc/src/gui/coordsys.qdoc b/doc/src/gui/coordsys.qdoc
deleted file mode 100644
index 655dbf7cf3..0000000000
--- a/doc/src/gui/coordsys.qdoc
+++ /dev/null
@@ -1,461 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
-** Contact: http://www.qt-project.org/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** GNU Free Documentation License
-** 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.
-**
-** Other Usage
-** Alternatively, this file may be used in accordance with the terms
-** and conditions contained in a signed written agreement between you
-** and Nokia.
-**
-**
-**
-**
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \page coordsys.html
- \title Coordinate System
- \ingroup qt-graphics
- \ingroup best-practices
- \brief Information about the coordinate system used by the paint
- system.
-
- The coordinate system is controlled by the QPainter
- class. Together with the QPaintDevice and QPaintEngine classes,
- QPainter form the basis of Qt's painting system, Arthur. QPainter
- is used to perform drawing operations, QPaintDevice is an
- abstraction of a two-dimensional space that can be painted on
- using a QPainter, and QPaintEngine provides the interface that the
- painter uses to draw onto different types of devices.
-
- The QPaintDevice class is the base class of objects that can be
- painted: Its drawing capabilities are inherited by the QWidget,
- QPixmap, QPicture, QImage, and QPrinter classes. The default
- coordinate system of a paint device has its origin at the top-left
- corner. The \e x values increase to the right and the \e y values
- increase downwards. The default unit is one pixel on pixel-based
- devices and one point (1/72 of an inch) on printers.
-
- The mapping of the logical QPainter coordinates to the physical
- QPaintDevice coordinates are handled by QPainter's transformation
- matrix, viewport and "window". The logical and physical coordinate
- systems coincide by default. QPainter also supports coordinate
- transformations (e.g. rotation and scaling).
-
- \tableofcontents
-
- \section1 Rendering
-
- \section2 Logical Representation
-
- The size (width and height) of a graphics primitive always
- correspond to its mathematical model, ignoring the width of the
- pen it is rendered with:
-
- \table
- \row
- \li \inlineimage coordinatesystem-rect.png
- \li \inlineimage coordinatesystem-line.png
- \row
- \li QRect(1, 2, 6, 4)
- \li QLine(2, 7, 6, 1)
- \endtable
-
- \section2 Aliased Painting
-
- When drawing, the pixel rendering is controlled by the
- QPainter::Antialiasing render hint.
-
- The \l {QPainter::RenderHint}{RenderHint} enum is used to specify
- flags to QPainter that may or may not be respected by any given
- engine. The QPainter::Antialiasing value indicates that the engine
- should antialias edges of primitives if possible, i.e. smoothing
- the edges by using different color intensities.
-
- But by default the painter is \e aliased and other rules apply:
- When rendering with a one pixel wide pen the pixels will be
- rendered to the \e {right and below the mathematically defined
- points}. For example:
-
- \table
- \row
- \li \inlineimage coordinatesystem-rect-raster.png
- \li \inlineimage coordinatesystem-line-raster.png
-
- \row
- \li
- \snippet doc/src/snippets/code/doc_src_coordsys.cpp 0
-
- \li
- \snippet doc/src/snippets/code/doc_src_coordsys.cpp 1
- \endtable
-
- When rendering with a pen with an even number of pixels, the
- pixels will be rendered symetrically around the mathematical
- defined points, while rendering with a pen with an odd number of
- pixels, the spare pixel will be rendered to the right and below
- the mathematical point as in the one pixel case. See the QRectF
- diagrams below for concrete examples.
-
- \table
- \header
- \li {3,1} QRectF
- \row
- \li \inlineimage qrect-diagram-zero.png
- \li \inlineimage qrectf-diagram-one.png
- \row
- \li Logical representation
- \li One pixel wide pen
- \row
- \li \inlineimage qrectf-diagram-two.png
- \li \inlineimage qrectf-diagram-three.png
- \row
- \li Two pixel wide pen
- \li Three pixel wide pen
- \endtable
-
- Note that for historical reasons the return value of the
- QRect::right() and QRect::bottom() functions deviate from the true
- bottom-right corner of the rectangle.
-
- QRect's \l {QRect::right()}{right()} function returns \l
- {QRect::left()}{left()} + \l {QRect::width()}{width()} - 1 and the
- \l {QRect::bottom()}{bottom()} function returns \l
- {QRect::top()}{top()} + \l {QRect::height()}{height()} - 1. The
- bottom-right green point in the diagrams shows the return
- coordinates of these functions.
-
- We recommend that you simply use QRectF instead: The QRectF class
- defines a rectangle in the plane using floating point coordinates
- for accuracy (QRect uses integer coordinates), and the
- QRectF::right() and QRectF::bottom() functions \e do return the
- true bottom-right corner.
-
- Alternatively, using QRect, apply \l {QRect::x()}{x()} + \l
- {QRect::width()}{width()} and \l {QRect::y()}{y()} + \l
- {QRect::height()}{height()} to find the bottom-right corner, and
- avoid the \l {QRect::right()}{right()} and \l
- {QRect::bottom()}{bottom()} functions.
-
- \section2 Anti-aliased Painting
-
- If you set QPainter's \l {QPainter::Antialiasing}{anti-aliasing}
- render hint, the pixels will be rendered symetrically on both
- sides of the mathematically defined points:
-
- \table
- \row
- \li \inlineimage coordinatesystem-rect-antialias.png
- \li \inlineimage coordinatesystem-line-antialias.png
- \row
- \li
-
- \snippet doc/src/snippets/code/doc_src_coordsys.cpp 2
-
- \li
- \snippet doc/src/snippets/code/doc_src_coordsys.cpp 3
- \endtable
-
- \section1 Transformations
-
- By default, the QPainter operates on the associated device's own
- coordinate system, but it also has complete support for affine
- coordinate transformations.
-
- You can scale the coordinate system by a given offset using the
- QPainter::scale() function, you can rotate it clockwise using the
- QPainter::rotate() function and you can translate it (i.e. adding
- a given offset to the points) using the QPainter::translate()
- function.
-
- \table
- \row
- \li \inlineimage qpainter-clock.png
- \li \inlineimage qpainter-rotation.png
- \li \inlineimage qpainter-scale.png
- \li \inlineimage qpainter-translation.png
- \row
- \li nop
- \li \l {QPainter::rotate()}{rotate()}
- \li \l {QPainter::scale()}{scale()}
- \li \l {QPainter::translate()}{translate()}
- \endtable
-
- You can also twist the coordinate system around the origin using
- the QPainter::shear() function. See the \l {painting/affine}{Affine
- Transformations} example for a visualization of a sheared coordinate
- system. All the transformation operations operate on QPainter's
- transformation matrix that you can retrieve using the
- QPainter::worldTransform() function. A matrix transforms a point
- in the plane to another point.
-
- If you need the same transformations over and over, you can also
- use QTransform objects and the QPainter::worldTransform() and
- QPainter::setWorldTransform() functions. You can at any time save the
- QPainter's transformation matrix by calling the QPainter::save()
- function which saves the matrix on an internal stack. The
- QPainter::restore() function pops it back.
-
- One frequent need for the transformation matrix is when reusing
- the same drawing code on a variety of paint devices. Without
- transformations, the results are tightly bound to the resolution
- of the paint device. Printers have high resolution, e.g. 600 dots
- per inch, whereas screens often have between 72 and 100 dots per
- inch.
-
- \table 100%
- \header
- \li {2,1} Analog Clock Example
- \row
- \li \inlineimage coordinatesystem-analogclock.png
- \li
- The Analog Clock example shows how to draw the contents of a
- custom widget using QPainter's transformation matrix.
-
- Qt's example directory provides a complete walk-through of the
- example. Here, we will only review the example's \l
- {QWidget::paintEvent()}{paintEvent()} function to see how we can
- use the transformation matrix (i.e. QPainter's matrix functions)
- to draw the clock's face.
-
- We recommend compiling and running this example before you read
- any further. In particular, try resizing the window to different
- sizes.
-
- \row
- \li {2,1}
-
- \snippet examples/widgets/analogclock/analogclock.cpp 9
-
- First, we set up the painter. We translate the coordinate system
- so that point (0, 0) is in the widget's center, instead of being
- at the top-left corner. We also scale the system by \c side / 100,
- where \c side is either the widget's width or the height,
- whichever is shortest. We want the clock to be square, even if the
- device isn't.
-
- This will give us a 200 x 200 square area, with the origin (0, 0)
- in the center, that we can draw on. What we draw will show up in
- the largest possible square that will fit in the widget.
-
- See also the \l {Window-Viewport Conversion} section.
-
- \snippet examples/widgets/analogclock/analogclock.cpp 18
-
- We draw the clock's hour hand by rotating the coordinate system
- and calling QPainter::drawConvexPolygon(). Thank's to the
- rotation, it's drawn pointed in the right direction.
-
- The polygon is specified as an array of alternating \e x, \e y
- values, stored in the \c hourHand static variable (defined at the
- beginning of the function), which corresponds to the four points
- (2, 0), (0, 2), (-2, 0), and (0, -25).
-
- The calls to QPainter::save() and QPainter::restore() surrounding
- the code guarantees that the code that follows won't be disturbed
- by the transformations we've used.
-
- \snippet examples/widgets/analogclock/analogclock.cpp 24
-
- We do the same for the clock's minute hand, which is defined by
- the four points (1, 0), (0, 1), (-1, 0), and (0, -40). These
- coordinates specify a hand that is thinner and longer than the
- minute hand.
-
- \snippet examples/widgets/analogclock/analogclock.cpp 27
-
- Finally, we draw the clock face, which consists of twelve short
- lines at 30-degree intervals. At the end of that, the painter is
- rotated in a way which isn't very useful, but we're done with
- painting so that doesn't matter.
- \endtable
-
- For a demonstation of Qt's ability to perform affine
- transformations on painting operations, see the \l
- {painting/affine}{Affine Transformations} example which allows the user
- to experiment with the transformation operations. See also the \l
- {painting/transformations}{Transformations} example which shows
- how transformations influence the way that QPainter renders
- graphics primitives. In particular, it shows how the order of
- transformations affects the result.
-
- For more information about the transformation matrix, see the
- QTransform documentation.
-
- \section1 Window-Viewport Conversion
-
- When drawing with QPainter, we specify points using logical
- coordinates which then are converted into the physical coordinates
- of the paint device.
-
- The mapping of the logical coordinates to the physical coordinates
- are handled by QPainter's world transformation \l
- {QPainter::worldTransform()}{worldTransform()} (described in the \l
- Transformations section), and QPainter's \l
- {QPainter::viewport()}{viewport()} and \l
- {QPainter::window()}{window()}. The viewport represents the
- physical coordinates specifying an arbitrary rectangle. The
- "window" describes the same rectangle in logical coordinates. By
- default the logical and physical coordinate systems coincide, and
- are equivalent to the paint device's rectangle.
-
- Using window-viewport conversion you can make the logical
- coordinate system fit your preferences. The mechanism can also be
- used to make the drawing code independent of the paint device. You
- can, for example, make the logical coordinates extend from (-50,
- -50) to (50, 50) with (0, 0) in the center by calling the
- QPainter::setWindow() function:
-
- \snippet doc/src/snippets/code/doc_src_coordsys.cpp 4
-
- Now, the logical coordinates (-50,-50) correspond to the paint
- device's physical coordinates (0, 0). Independent of the paint
- device, your painting code will always operate on the specified
- logical coordinates.
-
- By setting the "window" or viewport rectangle, you perform a
- linear transformation of the coordinates. Note that each corner of
- the "window" maps to the corresponding corner of the viewport, and
- vice versa. For that reason it normally is a good idea to let the
- viewport and "window" maintain the same aspect ratio to prevent
- deformation:
-
- \snippet doc/src/snippets/code/doc_src_coordsys.cpp 5
-
- If we make the logical coordinate system a square, we should also
- make the viewport a square using the QPainter::setViewport()
- function. In the example above we make it equivalent to the
- largest square that fit into the paint device's rectangle. By
- taking the paint device's size into consideration when setting the
- window or viewport, it is possible to keep the drawing code
- independent of the paint device.
-
- Note that the window-viewport conversion is only a linear
- transformation, i.e. it does not perform clipping. This means that
- if you paint outside the currently set "window", your painting is
- still transformed to the viewport using the same linear algebraic
- approach.
-
- \image coordinatesystem-transformations.png
-
- The viewport, "window" and transformation matrix determine how
- logical QPainter coordinates map to the paint device's physical
- coordinates. By default the world transformation matrix is the
- identity matrix, and the "window" and viewport settings are
- equivalent to the paint device's settings, i.e. the world,
- "window" and device coordinate systems are equivalent, but as we
- have seen, the systems can be manipulated using transformation
- operations and window-viewport conversion. The illustration above
- describes the process.
-
- \omit
- \section1 Related Classes
-
- Qt's paint system, Arthur, is primarily based on the QPainter,
- QPaintDevice, and QPaintEngine classes:
-
- \table
- \header \li Class \li Description
- \row
- \li QPainter
- \li
- The QPainter class performs low-level painting on widgets and
- other paint devices. QPainter can operate on any object that
- inherits the QPaintDevice class, using the same code.
- \row
- \li QPaintDevice
- \li
- The QPaintDevice class is the base class of objects that can be
- painted. Qt provides several devices: QWidget, QImage, QPixmap,
- QPrinter and QPicture, and other devices can also be defined by
- subclassing QPaintDevice.
- \row
- \li QPaintEngine
- \li
- The QPaintEngine class provides an abstract definition of how
- QPainter draws to a given device on a given platform. Qt 4
- provides several premade implementations of QPaintEngine for the
- different painter backends we support; it provides one paint
- engine for each supported window system and painting
- frameworkt. You normally don't need to use this class directly.
- \endtable
-
- The 2D transformations of the coordinate system are specified
- using the QTransform class:
-
- \table
- \header \li Class \li Description
- \row
- \li QTransform
- \li
- A 3 x 3 transformation matrix. Use QTransform to rotate, shear,
- scale, or translate the coordinate system.
- \endtable
-
- In addition Qt provides several graphics primitive classes. Some
- of these classes exist in two versions: an \c{int}-based version
- and a \c{qreal}-based version. For these, the \c qreal version's
- name is suffixed with an \c F.
-
- \table
- \header \li Class \li Description
- \row
- \li \l{QPoint}(\l{QPointF}{F})
- \li
- A single 2D point in the coordinate system. Most functions in Qt
- that deal with points can accept either a QPoint, a QPointF, two
- \c{int}s, or two \c{qreal}s.
- \row
- \li \l{QSize}(\l{QSizeF}{F})
- \li
- A single 2D vector. Internally, QPoint and QSize are the same, but
- a point is not the same as a size, so both classes exist. Again,
- most functions accept either QSizeF, a QSize, two \c{int}s, or two
- \c{qreal}s.
- \row
- \li \l{QRect}(\l{QRectF}{F})
- \li
- A 2D rectangle. Most functions accept either a QRectF, a QRect,
- four \c{int}s, or four \c {qreal}s.
- \row
- \li \l{QLine}(\l{QLineF}{F})
- \li
- A 2D finite-length line, characterized by a start point and an end
- point.
- \row
- \li \l{QPolygon}(\l{QPolygonF}{F})
- \li
- A 2D polygon. A polygon is a vector of \c{QPoint(F)}s. If the
- first and last points are the same, the polygon is closed.
- \row
- \li QPainterPath
- \li
- A vectorial specification of a 2D shape. Painter paths are the
- ultimate painting primitive, in the sense that any shape
- (rectange, ellipse, spline) or combination of shapes can be
- expressed as a path. A path specifies both an outline and an area.
- \row
- \li QRegion
- \li
- An area in a paint device, expressed as a list of
- \l{QRect}s. In general, we recommend using the vectorial
- QPainterPath class instead of QRegion for specifying areas,
- because QPainterPath handles painter transformations much better.
- \endtable
- \endomit
-
- \sa {Analog Clock Example}, {Transformations Example}
-*/
diff --git a/doc/src/gui/paintsystem.qdoc b/doc/src/gui/paintsystem.qdoc
deleted file mode 100644
index 4b33e4fed3..0000000000
--- a/doc/src/gui/paintsystem.qdoc
+++ /dev/null
@@ -1,560 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
-** Contact: http://www.qt-project.org/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** GNU Free Documentation License
-** 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.
-**
-** Other Usage
-** Alternatively, this file may be used in accordance with the terms
-** and conditions contained in a signed written agreement between you
-** and Nokia.
-**
-**
-**
-**
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \group painting
- \title Painting Classes
- \ingroup groups
-
- \brief Classes that provide support for painting.
-
- See also this introduction to the \link coordsys.html Qt
- coordinate system. \endlink
-*/
-
-/*!
- \group painting-3D
- \title Rendering in 3D
- \ingroup groups
-
- \brief Classes that provide support for rendering in 3D.
-*/
-
-/*!
- \page paintsystem.html
- \title Paint System
- \brief A system for painting on the screen or on print devices using the same API
- \ingroup qt-graphics
- \ingroup frameworks-technologies
- \ingroup qt-basic-concepts
-
-
- Qt's paint system enables painting on screen and print devices
- using the same API, and is primarily based on the QPainter,
- QPaintDevice, and QPaintEngine classes.
-
- QPainter is used to perform drawing operations, QPaintDevice is an
- abstraction of a two-dimensional space that can be painted on
- using a QPainter, and QPaintEngine provides the interface that the
- painter uses to draw onto different types of devices. The
- QPaintEngine class is used internally by QPainter and
- QPaintDevice, and is hidden from application programmers unless
- they create their own device type.
-
- \image paintsystem-core.png
-
- The main benefit of this approach is that all painting follows the
- same painting pipeline making it easy to add support for new
- features and providing default implementations for unsupported
- ones.
-
- \section1 Topics
- \list
- \li \l{Classes for Painting}
- \li \l{Paint Devices and Backends}
- \li \l{Drawing and Filling}
- \li \l{Coordinate System}
- \li \l{Reading and Writing Image Files}
- \li \l{Styling}
- \li \l{Printing with Qt}
- \endlist
-
- \section1 Classes for Painting
-
- These classes provide support for painting onto a paint device.
-
- \annotatedlist painting
-
- Alternatively, Qt provides the QtOpenGL module, offering classes
- that makes it easy to use OpenGL in Qt applications. Among others,
- the module provides an OpenGL widget class that can be used just
- like any other Qt widget, except that it opens an OpenGL display
- buffer where the OpenGL API can be used to render the contents.
-*/
-
-
-/*!
- \page paintsystem-devices.html
- \title Paint Devices and Backends
-
- \contentspage The Paint System
- \nextpage Drawing and Filling
-
- \section1 Creating a Paint Device
-
- The QPaintDevice class is the base class of objects that can be
- painted, i.e. QPainter can draw on any QPaintDevice
- subclass. QPaintDevice's drawing capabilities are currently
- implemented by the QWidget, QImage, QPixmap, QGLWidget,
- QGLPixelBuffer, QPicture and QPrinter subclasses.
-
- \image paintsystem-devices.png
-
- \table 100%
- \row \li \b Widget
-
- The QWidget class is the base class of all user interface
- objects. The widget is the atom of the user interface: it receives
- mouse, keyboard and other events from the window system, and
- paints a representation of itself on the screen.
-
- \row \li \b Image
-
- The QImage class provides a hardware-independent image
- representation which is designed and optimized for I/O, and for
- direct pixel access and manipulation. QImage supports several
- image formats including monochrome, 8-bit, 32-bit and
- alpha-blended images.
-
- One advantage of using QImage as a paint device is that it is
- possible to guarantee the pixel exactness of any drawing operation
- in a platform-independent way. Another benefit is that the
- painting can be performed in another thread than the current GUI
- thread.
-
- \row \li \b Pixmap
-
- The QPixmap class is an off-screen image representation which is
- designed and optimized for showing images on screen. Unlike
- QImage, the pixel data in a pixmap is internal and is managed by
- the underlying window system, i.e. pixels can only be accessed
- through QPainter functions or by converting the QPixmap to a
- QImage.
-
- To optimize drawing with QPixmap, Qt provides the QPixmapCache
- class which can be used to store temporary pixmaps that are
- expensive to generate without using more storage space than the
- cache limit.
-
- Qt also provides the QBitmap convenience class, inheriting
- QPixmap. QBitmap guarantees monochrome (1-bit depth) pixmaps, and
- is mainly used for creating custom QCursor and QBrush objects,
- constructing QRegion objects, and for setting masks for pixmaps
- and widgets.
-
- \row \li \b {OpenGL Widget}
-
- As mentioned previously, Qt provides the QtOpenGL module offering
- classes that makes it easy to use OpenGL in Qt applications. For
- example, the QGLWidget enables the OpenGL API for
- rendering.
-
- But QGLWidget is also a QWidget subclass, and can be used by
- QPainter as any other paint device. One huge benefit from this is
- that it enables Qt to utilize the high performance of OpenGL for
- most drawing operations, such as transformations and pixmap
- drawing.
-
- \row \li \b {Pixel Buffer}
-
- The QtOpenGL module also provides the QGLPixelBuffer class which
- inherits QPaintDevice directly.
-
- QGLPixelBuffer encapsulates an OpenGL pbuffer. Rendering into a
- pbuffer is normally done using full hardware acceleration which
- can be significantly faster than rendering into a QPixmap.
-
- \row \li \b {Framebuffer Object}
-
- The QtOpenGL module also provides the QGLFramebufferObject class
- which inherits QPaintDevice directly.
-
- QGLFramebufferObject encapsulates an OpenGL framebuffer object.
- Framebuffer objects can also be used for off-screen rendering, and
- offer several advantages over pixel buffers for this purpose.
- These are described in the QGLFramebufferObject class documentation.
-
- \row \li \b {Picture}
-
- The QPicture class is a paint device that records and replays
- QPainter commands. A picture serializes painter commands to an IO
- device in a platform-independent format. QPicture is also
- resolution independent, i.e. a QPicture can be displayed on
- different devices (for example svg, pdf, ps, printer and screen)
- looking the same.
-
- Qt provides the QPicture::load() and QPicture::save() functions
- as well as streaming operators for loading and saving pictures.
-
- \row \li \b {Printer}
-
- The QPrinter class is a paint device that paints on a printer. On
- Windows or Mac OS X, QPrinter uses the built-in printer
- drivers. On X11, QPrinter generates postscript and sends that to
- lpr, lp, or another print program. QPrinter can also print to any
- other QPrintEngine object.
-
- The QPrintEngine class defines an interface for how QPrinter
- interacts with a given printing subsystem. The common case when
- creating your own print engine, is to derive from both
- QPaintEngine and QPrintEngine.
-
- The output format is by default determined by the platform the
- printer is running on, but by explicitly setting the output format
- to QPrinter::PdfFormat, QPrinter will generate its output as a PDF
- file.
-
- \row \li \b {Custom Backends}
-
- Support for a new backend can be implemented by deriving from the
- QPaintDevice class and reimplementing the virtual
- QPaintDevice::paintEngine() function to tell QPainter which paint
- engine should be used to draw on this particular device. To
- actually be able to draw on the device, this paint engine must be
- a custom paint engine created by deriving from the QPaintEngine
- class.
-
- \endtable
-
- \section1 Selecting the Painting Backend
-
- Since Qt 4.5, it is possible to replace the paint engines and paint
- devices used for widgets, pixmaps and the offscreen double buffer. By
- default the backends are:
-
- \table
- \row
- \li Windows
- \li Software Rasterizer
- \row
- \li X11
- \li X11
- \row
- \li Mac OS X
- \li CoreGraphics
- \row
- \li Embedded
- \li Software Rasterizer
- \endtable
-
- Passing a command line parameter to the application, such as,
- \c{-graphicssystem raster}, specifies that Qt should use the software
- rasterizer for this application. The Software rasterizer is fully
- supported on all platforms.
-
- \code
- > analogclock -graphicssystem raster
- \endcode
-
- There is also a \c{-graphicssystem opengl} mode that uses OpenGL for
- all drawing. Currently, this engine is experimental as it does not draw
- everything correctly.
-
- Qt also supports being configured using \c {-graphicssystem
- raster|opengl} in which case all applications will use the
- specified graphics system for its graphics.
-*/
-
-/*!
- \page paintsystem-drawing.html
- \title Drawing and Filling
-
- \previouspage Paint Devices and Backends
- \contentspage The Paint System
- \nextpage Coordinate System
-
- \section1 Drawing
-
- QPainter provides highly optimized functions to do most of the
- drawing GUI programs require. It can draw everything from simple
- graphical primitives (represented by the QPoint, QLine, QRect,
- QRegion and QPolygon classes) to complex shapes like vector
- paths. In Qt vector paths are represented by the QPainterPath
- class. QPainterPath provides a container for painting operations,
- enabling graphical shapes to be constructed and reused.
-
- \table 100%
- \row
- \li \image paintsystem-painterpath.png
- \li \b QPainterPath
-
- A painter path is an object composed of lines and curves. For
- example, a rectangle is composed by lines and an ellipse is
- composed by curves.
-
- The main advantage of painter paths over normal drawing operations
- is that complex shapes only need to be created once; then they can
- be drawn many times using only calls to the QPainter::drawPath()
- function.
-
- A QPainterPath object can be used for filling, outlining, and
- clipping. To generate fillable outlines for a given painter path,
- use the QPainterPathStroker class.
-
- \endtable
-
- Lines and outlines are drawn using the QPen class. A pen is
- defined by its style (i.e. its line-type), width, brush, how the
- endpoints are drawn (cap-style) and how joins between two
- connected lines are drawn (join-style). The pen's brush is a
- QBrush object used to fill strokes generated with the pen,
- i.e. the QBrush class defines the fill pattern.
-
- QPainter can also draw aligned text and pixmaps.
-
- When drawing text, the font is specified using the QFont class. Qt
- will use the font with the specified attributes, or if no matching
- font exists, Qt will use the closest matching installed font. The
- attributes of the font that is actually used can be retrieved
- using the QFontInfo class. In addition, the QFontMetrics class
- provides the font measurements, and the QFontDatabase class
- provides information about the fonts available in the underlying
- window system.
-
- Normally, QPainter draws in a "natural" coordinate system, but it
- is able to perform view and world transformations using the
- QTransform class. For more information, see \l {Coordinate
- System}, which also describes the rendering process, i.e. the
- relation between the logical representation and the rendered
- pixels, and the benefits of anti-aliased painting.
-
- \table 100%
- \row \li
- \b {Anti-Aliased Painting}
-
- When drawing, the pixel rendering is controlled by the
- QPainter::Antialiasing render hint. The QPainter::RenderHint enum
- is used to specify flags to QPainter that may or may not be
- respected by any given engine.
-
- The QPainter::Antialiasing value indicates that the engine should
- antialias edges of primitives if possible, i.e. smoothing the
- edges by using different color intensities.
-
- \li \image paintsystem-antialiasing.png
-
- \endtable
-
- \section1 Filling
-
- Shapes are filled using the QBrush class. A brush is defined
- by its color and its style (i.e. its fill pattern).
-
- Any color in Qt is represented by the QColor class which supports
- the RGB, HSV and CMYK color models. QColor also support
- alpha-blended outlining and filling (specifying the transparency
- effect), and the class is platform and device independent (the
- colors are mapped to hardware using the QColormap class). For more
- information, see the QColor class documentation.
-
- When creating a new widget, it is recommend to use the colors in
- the widget's palette rather than hard-coding specific colors. All
- widgets in Qt contain a palette and use their palette to draw
- themselves. A widget's palette is represented by the QPalette
- class which contains color groups for each widget state.
-
- The available fill patterns are described by the Qt::BrushStyle
- enum. These include basic patterns spanning from uniform color to
- very sparse pattern, various line combinations, gradient fills and
- textures. Qt provides the QGradient class to define custom
- gradient fills, while texture patterns are specified using the
- QPixmap class.
-
- \table 100%
- \row
- \li \image paintsystem-fancygradient.png
- \li \b QGradient
-
- The QGradient class is used in combination with QBrush to specify
- gradient fills.
-
- \image paintsystem-gradients.png
-
- Qt currently supports three types of gradient fills: Linear
- gradients interpolate colors between start and end points, radial
- gradients interpolate colors between a focal point and end points
- on a circle surrounding it, and conical gradients interpolate
- colors around a center point.
-
- \endtable
-*/
-
-/*!
- \page paintsystem-images.html
- \title Reading and Writing Image Files
-
- \previouspage Coordinate System
- \contentspage The Paint System
- \nextpage Styling
-
- The most common way to read images is through QImage and QPixmap's
- constructors, or by calling the QImage::load() and QPixmap::load()
- functions. In addition, Qt provides the QImageReader class which
- gives more control over the process. Depending on the underlying
- support in the image format, the functions provided by the class
- can save memory and speed up loading of images.
-
- Likewise, Qt provides the QImageWriter class which supports
- setting format specific options, such as the gamma level,
- compression level and quality, prior to storing the image. If you
- do not need such options, you can use QImage::save() or
- QPixmap::save() instead.
-
- \table 100%
- \row
- \li \b QMovie
-
- QMovie is a convenience class for displaying animations, using the
- QImageReader class internally. Once created, the QMovie class
- provides various functions for both running and controlling the
- given animation.
-
- \li \image paintsystem-movie.png
- \endtable
-
- The QImageReader and QImageWriter classes rely on the
- QImageIOHandler class which is the common image I/O interface for
- all image formats in Qt. QImageIOHandler objects are used
- internally by QImageReader and QImageWriter to add support for
- different image formats to Qt.
-
- A list of the supported file formats are available through the
- QImageReader::supportedImageFormats() and
- QImageWriter::supportedImageFormats() functions. Qt supports
- several file formats by default, and in addition new formats can
- be added as plugins. The currently supported formats are listed in
- the QImageReader and QImageWriter class documentation.
-
- Qt's plugin mechanism can also be used to write a custom image
- format handler. This is done by deriving from the QImageIOHandler
- class, and creating a QImageIOPlugin object which is a factory for
- creating QImageIOHandler objects. When the plugin is installed,
- QImageReader and QImageWriter will automatically load the plugin
- and start using it.
-
- \section1 Rendering SVG files
-
- \table 100%
- \row
- \li \image paintsystem-svg.png
- \li \b {SVG Rendering}
-
- Scalable Vector Graphics (SVG) is a language for describing two-dimensional
- graphics and graphical applications in XML. SVG 1.1 is a W3C Recommendation
- and forms the core of the current SVG developments in Qt. SVG 1.2 is the
- specification currently being developed by the \l{SVG Working Group}, and it
- is \l{http://www.w3.org/TR/SVG12/}{available in draft form}.
- The \l{Mobile SVG Profiles} (SVG Basic and SVG Tiny) are aimed at
- resource-limited devices and are part of the 3GPP platform for third generation
- mobile phones. You can read more about SVG at \l{About SVG}.
-
- Qt supports the \l{SVG 1.2 Tiny Static Features}{static features} of
- \l{SVG 1.2 Tiny}. ECMA scripts and DOM manipulation are currently not
- supported.
-
- SVG drawings can be rendered onto any QPaintDevice subclass. This
- approach gives developers the flexibility to experiment, in order
- to find the best solution for each application.
-
- The easiest way to render SVG files is to construct a QSvgWidget and
- load an SVG file using one of the QSvgWidget::load() functions.
-
- QSvgRenderer is the class responsible for rendering SVG files for
- QSvgWidget, and it can be used directly to provide SVG support for
- custom widgets.
- To load an SVG file, construct a QSvgRenderer with a file name or the
- contents of a file, or call QSvgRenderer::load() on an existing
- renderer. If the SVG file has been loaded successfully the
- QSvgRenderer::isValid() will return true.
-
- Once you have loaded the SVG file successfully, you can render it
- with the QSvgRenderer::render() function. Note that this scheme allows
- you to render SVG files on all paint devices supported by Qt, including
- QWidget, QGLWidget, and QImage. See the \l{SVG Viewer Example}{SVG Viewer}
- example for more details.
-
- \endtable
-*/
-
-/*!
- \page paintsystem-styling.html
- \title Styling
-
- \previouspage Reading and Writing Image Files
- \contentspage The Paint System
- \nextpage Printing with Qt
-
- Qt's built-in widgets use the QStyle class to perform nearly all
- of their drawing. QStyle is an abstract base class that
- encapsulates the look and feel of a GUI, and can be used to make
- the widgets look exactly like the equivalent native widgets or to
- give the widgets a custom look.
-
- Qt provides a set of QStyle subclasses that emulate the native
- look of the different platforms supported by Qt (QWindowsStyle,
- QMacStyle, QMotifStyle, etc.). These styles are built into the
- QtGui library, other styles can be made available using Qt's
- plugin mechansim.
-
- Most functions for drawing style elements take four arguments:
-
- \list
- \li an enum value specifying which graphical element to draw
- \li a QStyleOption object specifying how and where to render that element
- \li a QPainter object that should be used to draw the element
- \li a QWidget object on which the drawing is performed (optional)
- \endlist
-
- The style gets all the information it needs to render the
- graphical element from the QStyleOption class. The widget is
- passed as the last argument in case the style needs it to perform
- special effects (such as animated default buttons on Mac OS X),
- but it isn't mandatory. In fact, QStyle can be used to draw on any
- paint device (not just widgets), in which case the widget argument
- is a zero pointer.
-
- \image paintsystem-stylepainter.png
-
- The paint system also provides the QStylePainter class inheriting
- from QPainter. QStylePainter is a convenience class for drawing
- QStyle elements inside a widget, and extends QPainter with a set
- of high-level drawing functions implemented on top of QStyle's
- API. The advantage of using QStylePainter is that the parameter
- lists get considerably shorter.
-
- \table 100%
- \row
- \li \inlineimage paintsystem-icon.png
- \li \b QIcon
-
- The QIcon class provides scalable icons in different modes and states.
-
- QIcon can generate pixmaps reflecting an icon's state, mode and
- size. These pixmaps are generated from the set of pixmaps
- made available to the icon, and are used by Qt widgets to show an
- icon representing a particular action.
-
- The rendering of a QIcon object is handled by the QIconEngine
- class. Each icon has a corresponding icon engine that is
- responsible for drawing the icon with a requested size, mode and
- state.
-
- \endtable
-
- For more information about widget styling and appearance, see the
- \l{Styles and Style Aware Widgets}.
-*/
diff --git a/doc/src/gui/qtgui.qdoc b/doc/src/gui/qtgui.qdoc
deleted file mode 100644
index bffe07889a..0000000000
--- a/doc/src/gui/qtgui.qdoc
+++ /dev/null
@@ -1,39 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
-** Contact: http://www.qt-project.org/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** GNU Free Documentation License
-** 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.
-**
-** Other Usage
-** Alternatively, this file may be used in accordance with the terms
-** and conditions contained in a signed written agreement between you
-** and Nokia.
-**
-**
-**
-**
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \module QtGui
- \title QtGui Module
- \ingroup modules
-
- \brief The QtGui module extends QtCore with GUI functionality.
-
- To include the definitions of both modules' classes, use the
- following directive:
-
- \snippet doc/src/snippets/code/doc_src_qtgui.pro 0
-*/