diff options
Diffstat (limited to 'doc/src/gui')
| -rw-r--r-- | doc/src/gui/coordsys.qdoc | 461 | ||||
| -rw-r--r-- | doc/src/gui/paintsystem.qdoc | 560 | ||||
| -rw-r--r-- | doc/src/gui/qtgui.qdoc | 39 |
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 -*/ |