From cfdc5628b1fc2cbafa2aebca38995e5718fcb0de Mon Sep 17 00:00:00 2001 From: Casper van Donderen Date: Mon, 7 May 2012 15:50:31 +0200 Subject: Doc: Modularize QtGui documentation. This change moves the snippets and images to the modularized directories. Change-Id: I5f86f598fbe7c47d632c613b85d94ced89ba2c29 Reviewed-by: Marius Storm-Olsen --- src/gui/doc/src/coordsys.qdoc | 461 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 461 insertions(+) create mode 100644 src/gui/doc/src/coordsys.qdoc (limited to 'src/gui/doc/src/coordsys.qdoc') diff --git a/src/gui/doc/src/coordsys.qdoc b/src/gui/doc/src/coordsys.qdoc new file mode 100644 index 0000000000..655dbf7cf3 --- /dev/null +++ b/src/gui/doc/src/coordsys.qdoc @@ -0,0 +1,461 @@ +/**************************************************************************** +** +** 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} +*/ -- cgit v1.2.3 From 47799adc0d1bfb9e0e592dbc9af3eb4680e0c81b Mon Sep 17 00:00:00 2001 From: Casper van Donderen Date: Wed, 9 May 2012 12:35:30 +0200 Subject: Doc: Move some remaining files over for modularization. The files in this change were still in qtbase/doc/src or required for it. qtbase/doc/src should now only contain example documentation and images for the example documentation. Change-Id: Ia7ca8e7fd2b316e77c706a08df71303bc8294213 Reviewed-by: Marius Storm-Olsen --- src/gui/doc/src/coordsys.qdoc | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'src/gui/doc/src/coordsys.qdoc') diff --git a/src/gui/doc/src/coordsys.qdoc b/src/gui/doc/src/coordsys.qdoc index 655dbf7cf3..bfa046f7fb 100644 --- a/src/gui/doc/src/coordsys.qdoc +++ b/src/gui/doc/src/coordsys.qdoc @@ -97,10 +97,10 @@ \row \li - \snippet doc/src/snippets/code/doc_src_coordsys.cpp 0 + \snippet code/doc_src_coordsys.cpp 0 \li - \snippet doc/src/snippets/code/doc_src_coordsys.cpp 1 + \snippet code/doc_src_coordsys.cpp 1 \endtable When rendering with a pen with an even number of pixels, the @@ -163,10 +163,10 @@ \row \li - \snippet doc/src/snippets/code/doc_src_coordsys.cpp 2 + \snippet code/doc_src_coordsys.cpp 2 \li - \snippet doc/src/snippets/code/doc_src_coordsys.cpp 3 + \snippet code/doc_src_coordsys.cpp 3 \endtable \section1 Transformations @@ -238,7 +238,7 @@ \row \li {2,1} - \snippet examples/widgets/analogclock/analogclock.cpp 9 + \snippet 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 @@ -253,7 +253,7 @@ See also the \l {Window-Viewport Conversion} section. - \snippet examples/widgets/analogclock/analogclock.cpp 18 + \snippet 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 @@ -268,14 +268,14 @@ 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 + \snippet 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 + \snippet 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 @@ -319,7 +319,7 @@ -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 + \snippet 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 @@ -333,7 +333,7 @@ viewport and "window" maintain the same aspect ratio to prevent deformation: - \snippet doc/src/snippets/code/doc_src_coordsys.cpp 5 + \snippet 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() -- cgit v1.2.3