diff options
Diffstat (limited to 'src/gui/doc/src')
| -rw-r--r-- | src/gui/doc/src/coordsys.qdoc | 43 | ||||
| -rw-r--r-- | src/gui/doc/src/paintsystem.qdoc | 182 | ||||
| -rw-r--r-- | src/gui/doc/src/qtgui.qdoc | 131 |
3 files changed, 150 insertions, 206 deletions
diff --git a/src/gui/doc/src/coordsys.qdoc b/src/gui/doc/src/coordsys.qdoc index bfa046f7fb..c0e33c974e 100644 --- a/src/gui/doc/src/coordsys.qdoc +++ b/src/gui/doc/src/coordsys.qdoc @@ -42,12 +42,12 @@ 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. + painted: Its drawing capabilities are inherited by the + QOpenGLPaintDevice, QImage, QPixmap and QPicture 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 @@ -195,12 +195,10 @@ \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. + the QPainter::shear() function. 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 @@ -225,12 +223,6 @@ 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. @@ -283,15 +275,6 @@ 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. @@ -457,5 +440,9 @@ \endtable \endomit - \sa {Analog Clock Example}, {Transformations Example} + \sa {Analog Clock Example} */ + +/* + ### DOC-TODO: rewrite analog clock to be QWindow based + */
\ No newline at end of file diff --git a/src/gui/doc/src/paintsystem.qdoc b/src/gui/doc/src/paintsystem.qdoc index 0864c3ba4a..ea0a3bdad6 100644 --- a/src/gui/doc/src/paintsystem.qdoc +++ b/src/gui/doc/src/paintsystem.qdoc @@ -78,8 +78,6 @@ \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 @@ -88,11 +86,6 @@ \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. */ @@ -108,18 +101,12 @@ 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. + implemented by the QImage, QPixmap, 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 @@ -152,40 +139,13 @@ 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} + constructing QRegion objects. - The QtOpenGL module also provides the QGLPixelBuffer class which - inherits QPaintDevice directly. + \row \li \b {OpenGL Paint Device} - 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. + As mentioned previously, Qt is offering classes that makes it easy + to use OpenGL in Qt applications. For example, the QOpenGLPaintDevice + enables the OpenGL API for rendering with QPainter. \row \li \b {Picture} @@ -199,23 +159,7 @@ 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} @@ -229,43 +173,6 @@ \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. */ /*! @@ -360,12 +267,6 @@ 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 @@ -398,7 +299,6 @@ \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() @@ -446,71 +346,3 @@ and start using it. */ -/*! - \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/src/gui/doc/src/qtgui.qdoc b/src/gui/doc/src/qtgui.qdoc index 7e11aa5233..64d9cb67fd 100644 --- a/src/gui/doc/src/qtgui.qdoc +++ b/src/gui/doc/src/qtgui.qdoc @@ -27,13 +27,138 @@ /*! \module QtGui - \title QtGui Module + \title The Qt GUI Module \ingroup modules - \brief The QtGui module extends QtCore with GUI functionality. + \brief The Qt GUI module provides the basic enablers for graphical + applications written with Qt. - To include the definitions of both modules' classes, use the + The Qt GUI module provides classes for windowing system + integration, event handling, OpenGL and OpenGL ES integration, 2D + graphics, imaging, fonts and typography. These classes are used + internally by Qt's user interface technologies and can also be + used directly, for instance to write applications using low-level + OpenGL ES graphics APIs. + + To include the definitions of the module's classes, use the following directive: \snippet code/doc_src_qtgui.pro 0 + + See the \l {Qt GUI Module Overview} for more details. + +*/ + +/*! + \page qtgui-overview.html + \title Qt GUI Module Overview + + The Qt GUI module provides classes for windowing system + integration, event handling, OpenGL and OpenGL ES integration, 2D + graphics, basic imaging, fonts and text. These classes are used + internally by Qt's user interface technologies and can also be + used directly, for instance to write applications using low-level + OpenGL ES graphics APIs. + + For application developers writing user interfaces, Qt provides + higher level API's, like Qt Quick, that are much more suitable + than the enablers found in the Qt GUI module. + + + + \section1 Application Windows + + The most important classes in the Qt GUI module are + QGuiApplication and QWindow. A Qt application that wants to show + content on screen, will need to make use of these. QGuiApplication + contains the main event loop, where all events from the window + system and other sources are processed and dispatched. It also + handles the application's initialization and finalization. + + The \l QWindow class represents a window in the underlying + windowing system. It provides a number of virtual functions to + handle events (\l {QEvent}) from the windowing system, such as + touch-input, exposure, focus, key strokes and geometry changes. + + + + \section1 2D Graphics + + The Qt GUI module contains classes for 2D graphics, imaging, fonts + and advanced typography. + + A \l QWindow created with the surface type \l + {QSurface::RasterSurface} can be used in combination with \l + {QBackingStore} and \l {QPainter}, Qt's highly optimized 2D vector + graphics API. QPainter supports drawing lines, polygons, vector + paths, images and text. For more information, see \l{Paint + System}. + + Qt can load and save images using the \l QImage and \l QPixmap + classes. By default, Qt supports the most common image formats + including JPEG and PNG among others. Users can add support for + additional formats via the \l QImageIOPlugin class. For more + information, see \l {Reading and Writing Image Files} + + Typography in Qt is done with \l QTextDocument which uses the \l + QPainter API in combination with Qt's font classes, primarily + QFont. Applications that prefer more low-level APIs to text + and font handling, classes like QRawFont and QGlyphRun can be + used. + + + + \section1 OpenGL and OpenGL ES integration + + QWindow supports rendering using desktop OpenGL, OpenGL ES 1.1 and + OpenGL ES 2.0, depending on what the platform supports. OpenGL + rendering is enabled by setting the QWindow's surface type to + QSurface::OpenGLSurface, then creating a QOpenGLContext to manage + the native OpenGL context. + + For more information, see \l {OpenGL Enablers}. + + The Qt GUI module also contains a few math classes to aid with the + most common mathmatical operations related to 3D graphics. These + classes include \l {QMatrix4x4}, \l {QVector4D} and \l {QQuaternion} + + A \l {QWindow} created with the \l {QSurface::OpenGLSurface} can + be used in combination with \l QPainter and \l QOpenGLPaintDevice + to have OpenGL hardware accellerated 2D graphics, by sacrificing + some of the visual quality. + + + + + \section1 Qt GUI prior to Qt 5.0 + + Prior to Qt 5.0, the Qt GUI library was the monolithic container + for all things relating to graphical user interfaces in Qt, and + included the Qt widget set, the item views, the graphics view + framework and also printing. Starting Qt 5, these classes have + been moved to the QtWidgets library. Printing has been + moved to the QtPrintSupport library. Please note that these + libraries can be excluded from a Qt installation. + + QtGui now contains only a small set of enablers, which are generally + useful for all graphical applications. + + */ + + +/* + + ### DOC-TODO: link under AppWindows to hello-world for QWindow in + examples/gui/windows/hello-qtgui. (Idea: QWindow which + reimplements mouseEvent() to exit) + + ### DOC-TODO: link under Painting to hello-raster for QWindow + in examples/gui/graphics/rasterwindow. Idea: QWindow with BS + which draws a rotating rectangle with some text underneath. + + ### DOC-TODO: link under OpenGL to hello-opengl for QWindow in + examples/gui/opengl/openglwindow. Idea: QWindow which draws a + triangle using GLES 2.0 compatible shaders. Do not care about + 1.1 API as almost everyone has 2.0 support these days. + */ |