Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731

1 files changed, 262 insertions, 0 deletions

diff --git a/doc/coordsys.doc b/doc/coordsys.doc
new file mode 100644
index 000000000..f614116a3
--- /dev/null
+++ b/doc/coordsys.doc
@@ -0,0 +1,262 @@
+/****************************************************************************
+**
+** Qt Coordinate System Documentation
+**
+** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be used under the terms of the GNU General
+** Public License versions 2.0 or 3.0 as published by the Free
+** Software Foundation and appearing in the files LICENSE.GPL2
+** and LICENSE.GPL3 included in the packaging of this file.
+** Alternatively you may (at your option) use any later version
+** of the GNU General Public License if such license has been
+** publicly approved by Trolltech ASA (or its successors, if any)
+** and the KDE Free Qt Foundation.
+**
+** Please review the following information to ensure GNU General
+** Public Licensing retquirements will be met:
+** http://trolltech.com/products/qt/licenses/licensing/opensource/.
+** If you are unsure which license is appropriate for your use, please
+** review the following information:
+** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
+** or contact the sales department at sales@trolltech.com.
+**
+** This file may be used under the terms of the Q Public License as
+** defined by Trolltech ASA and appearing in the file LICENSE.QPL
+** included in the packaging of this file.  Licensees holding valid Qt
+** Commercial licenses may use this file in accordance with the Qt
+** Commercial License Agreement provided with the Software.
+**
+** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
+** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
+** herein.
+**
+**********************************************************************/
+
+/*!
+\page coordsys.html
+
+\title The Coordinate System
+
+A \link QPaintDevice paint device\endlink in Qt is a drawable 2D
+surface. \l QWidget, \l QPixmap, \l QPicture and \l QPrinter are all
+paint devices. A \l QPainter is an object which can draw on such
+devices.
+
+The default coordinate system of a paint device has its origin at the
+top left corner. X increases to the right and Y increases downwards.
+The unit is one pixel on pixel-based devices and one point on
+printers.
+
+\section1 An Example
+
+The illustration below shows a highly magnified portion of the top
+left corner of a paint device.
+
+\img coordsys.png
+
+The rectangle and the line were drawn by this code (with the grid
+added and colors touched up in the illustration):
+
+\code
+    void MyWidget::paintEvent( QPaintEvent * )
+    {
+	QPainter p( this );
+	p.setPen( darkGray );
+	p.drawRect( 1,2, 5,4 );
+	p.setPen( lightGray );
+	p.drawLine( 9,2, 7,7 );
+    }
+\endcode
+
+Note that all of the pixels drawn by drawRect() are inside the size
+specified (5*4 pixels). This is different from some toolkits; in Qt
+the size you specify exactly encompasses the pixels drawn. This
+applies to all the relevant functions in QPainter.
+
+Similarly, the drawLine() call draws both endpoints of the line, not
+just one.
+
+Here are the classes that relate most closely to the coordinate
+system:
+
+\table
+
+\row \i \l QPoint
+     \i A single 2D point in the coordinate system. Most functions in
+	Qt that deal with points can accept either a QPoint argument
+	or two ints, for example \l QPainter::drawPoint().
+\row \i \l QSize
+     \i 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 a QSize or two ints, for
+	example \l QWidget::resize().
+\row \i \l QRect
+     \i A 2D rectangle. Most functions accept either a QRect or four
+	ints, for example \l QWidget::setGeometry().
+\row \i \l QRegion
+     \i An arbitrary set of points, including all the normal set
+	operations, e.g. \l QRegion::intersect(), and also a less
+	usual function to return a list of rectangles whose union is
+	equal to the region. QRegion is used e.g. by \l
+	QPainter::setClipRegion(), \l QWidget::repaint() and \l
+	QPaintEvent::region().
+\row \i \l QPainter
+     \i The class that paints. It can paint on any device with the
+	same code. There are differences between devices, \l
+	QPrinter::newPage() is a good example, but QPainter works the
+	same way on all devices.
+\row \i \l QPaintDevice
+     \i A device on which QPainter can paint. There are two internal
+	devices, both pixel-based, and two external devices, \l
+	QPrinter and \l QPicture (which records QPainter commands to a
+	file or other \l QIODevice, and plays them back). Other
+	devices can be defined.
+\endtable
+
+\section1 Transformations
+
+Although Qt's default coordinate system works as described above, \l
+QPainter also supports arbitrary transformations.
+
+This transformation engine is a three-step pipeline, closely following
+the model outlined in books such as
+\link http://www.amazon.com/exec/obidos/ASIN/0201848406/trolltech/t
+Foley \& Van Dam \endlink and the
+\link http://www.amazon.com/exec/obidos/ASIN/0201604582/trolltech/t
+OpenGL Programming Guide.\endlink Refer to those for in-depth
+coverage; here we give just a brief overview and an example.
+
+The first step uses the world transformation matrix. Use this matrix
+to orient and position your objects in your model. Qt provides
+methods such as \l QPainter::rotate(), \l QPainter::scale(), \l
+QPainter::translate() and so on to operate on this matrix.
+
+\l QPainter::save() and \l QPainter::restore() save and restore this
+matrix. You can also use \l QWMatrix objects, \l
+QPainter::worldMatrix() and \l QPainter::setWorldMatrix() to store and
+use named matrices.
+
+The second step uses the window. The window describes the view
+boundaries in model coordinates. The matrix positions the \e objects
+and \l QPainter::setWindow() positions the \e window, deciding what
+coordinates will be visible. (If you have 3D experience, the window
+is what's usually called projection in 3D.)
+
+The third step uses the viewport. The viewport too, describes the view
+boundaries, but in device coordinates. The viewport and the windows
+describe the same rectangle, but in different coordinate systems.
+
+On-screen, the default is the entire \l QWidget or \l QPixmap where
+you are drawing, which is usually appropriate. For printing this
+function is vital, since very few printers can print over the entire
+physical page.
+
+So each object to be drawn is transformed into model
+coordinates using \l QPainter::worldMatrix(), then positioned
+on the drawing device using \l QPainter::window() and
+\l QPainter::viewport().
+
+It is perfectly possible to do without one or two of the stages. If,
+for example, your goal is to draw something scaled, then just using \l
+QPainter::scale() makes perfect sense. If your goal is to use a
+fixed-size coordinate system, \l QPainter::setWindow() is
+ideal. And so on.
+
+Here is a short example that uses all three mechanisms: the function
+that draws the clock face in the \l aclock/aclock.cpp example. We
+recommend compiling and running the example before you read any
+further. In particular, try resizing the window to different sizes.
+
+\quotefile aclock/aclock.cpp
+\skipto ::drawClock
+\printline ::drawClock
+\printline {
+\printline save
+
+Firstly, we save the painter's state, so that the calling function
+is guaranteed not to be disturbed by the transformations we're going
+to use.
+
+\printline setWindow
+
+We set the model coordinate system we want a 1000*1000 window where
+0,0 is in the middle.
+
+\printline viewport
+\printline QMIN
+
+The device may not be square and we want the clock to be, so we find
+its current viewport and compute its shortest side.
+
+\printline setViewport
+\printline height
+
+Then we set a new square viewport, centered in the old one.
+
+We're now done with our view. From this point on, when we draw in a
+1000*1000 area around 0,0, what we draw will show up in the largest
+possible square that'll fit in the output device.
+
+Time to start drawing.
+
+\skipto pts
+\printline pts
+
+\e pts is just a temporary variable to hold some points.
+
+Next come three drawing blocks, one for the hour hand, one for the
+minute hand and finally one for the clock face itself. First we draw
+the hour hand:
+
+\skipto save
+\printline save
+\printline rotate
+
+We save the painter and then rotate it so that one axis points along
+the hour hand.
+
+\printline setPoints
+\printline drawConvexPolygon
+
+We set \e pts to a four-point polygon that looks like the hour hand at
+three o'clock, and draw it. Because of the rotation, it's drawn
+pointed in the right direction.
+
+\printline restore
+
+We restore the saved painter, undoing the rotation. We could also
+call rotate( -30 ) but that might introduce rounding errors, so it's
+better to use save() and restore(). Next, the minute hand, drawn
+almost the same way:
+
+\printline save
+\printline rotate
+\printline setPoints
+\printline drawConvexPolygon
+\printline restore
+
+The only differences are how the rotation angle is computed and the
+shape of the polygon.
+
+The last part to be drawn is the clock face itself.
+
+\printline for
+\printline drawLine
+\printline rotate
+\printline }
+
+Twelve short hour lines at thirty-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.
+
+\printline restore
+\printline }
+
+The final line of the function restores the painter, so that the
+caller won't be affected by all the transformations we've done.
+
+*/