diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/gui/doc/examples/analogclockwindow.qdoc | 138 | ||||
| -rw-r--r-- | src/gui/doc/examples/rasterwindow.qdoc | 161 | ||||
| -rw-r--r-- | src/gui/doc/images/analogclock-window-example.png | bin | 0 -> 2383 bytes | |||
| -rw-r--r-- | src/gui/doc/images/analogclockwindow-viewport.png | bin | 0 -> 29668 bytes | |||
| -rw-r--r-- | src/gui/doc/src/coordsys.qdoc | 25 | ||||
| -rw-r--r-- | src/gui/doc/src/qtgui.qdoc | 22 |
6 files changed, 316 insertions, 30 deletions
diff --git a/src/gui/doc/examples/analogclockwindow.qdoc b/src/gui/doc/examples/analogclockwindow.qdoc new file mode 100644 index 0000000000..0fdad483c6 --- /dev/null +++ b/src/gui/doc/examples/analogclockwindow.qdoc @@ -0,0 +1,138 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example gui/analogclock + \title Analog Clock Window Example + + The Analog Clock Window example shows how to draw the contents of + a custom window. + + \image analogclock-window-example.png Screenshot of the Analog + Clock Window example + + This example demonstrates how the transformation and scaling + features of QPainter can be used to make drawing easier. + + \section1 AnalogClockWindow Class Definition + + The \c AnalogClockWindow class provides a clock with hour and + minute hands that is automatically updated every few seconds. We + make use of the RasterWindow from the \l {Raster Window Example} + and reimplement the \c render function to draw the clock face: + + \snippet gui/analogclock/main.cpp 5 + + \section1 AnalogClock Class Implementation + + \snippet gui/analogclock/main.cpp 6 + + We set a title on the window and resize to a resonable size. Then + we start a timer which we will use to redraw the clock every + second. + + \snippet gui/analogclock/main.cpp 7 + + The timerEvent function is called every second as a result of + our startTimer call. Making use of the convenience in the base + class, we schedule the window to be repainted. + + Checking the timer's id is not strictly needed as we only have + one active timer in this instance, but it is good practice to do + so. + + \snippet gui/analogclock/main.cpp 14 + \snippet gui/analogclock/main.cpp 8 + + Before we set up the painter and draw the clock, we first define + two lists of \l {QPoint}s and two \l{QColor}s that will be used + for the hour and minute hands. The minute hand's color has an + alpha component of 191, meaning that it's 75% opaque. + + \snippet gui/analogclock/main.cpp 9 + + We call QPainter::setRenderHint() with QPainter::Antialiasing to + turn on antialiasing. This makes drawing of diagonal lines much + smoother. + + \snippet gui/analogclock/main.cpp 10 + + The translation moves the origin to the center of the window, and + the scale operation ensures that the following drawing operations + are scaled to fit within the window. We use a scale factor that + let's us use x and y coordinates between -100 and 100, and that + ensures that these lie within the length of the window's shortest + side. + + To make our code simpler, we will draw a fixed size clock face that will + be positioned and scaled so that it lies in the center of the window. + + We also determine the length of the window's shortest side so that we + can fit the clock face inside the window. + + The painter takes care of all the transformations made during the + rendering, and ensures that everything is drawn correctly. Letting + the painter handle transformations is often easier than performing + manual calculations. + + \image analogclockwindow-viewport.png + + We draw the hour hand first, using a formula that rotates the coordinate + system counterclockwise by a number of degrees determined by the current + hour and minute. This means that the hand will be shown rotated clockwise + by the required amount. + + \snippet gui/analogclock/main.cpp 11 + + We set the pen to be Qt::NoPen because we don't want any outline, + and we use a solid brush with the color appropriate for + displaying hours. Brushes are used when filling in polygons and + other geometric shapes. + + \snippet gui/analogclock/main.cpp 2 + + We save and restore the transformation matrix before and after the + rotation because we want to place the minute hand without having to + take into account any previous rotations. + + \snippet gui/analogclock/main.cpp 12 + + We draw markers around the edge of the clock for each hour. We + draw each marker then rotate the coordinate system so that the + painter is ready for the next one. + + \snippet gui/analogclock/main.cpp 13 + \snippet gui/analogclock/main.cpp 3 + + The minute hand is rotated in a similar way to the hour hand. + + \snippet gui/analogclock/main.cpp 4 + + Again, we draw markers around the edge of the clock, but this + time to indicate minutes. We skip multiples of 5 to avoid drawing + minute markers on top of hour markers. +*/ diff --git a/src/gui/doc/examples/rasterwindow.qdoc b/src/gui/doc/examples/rasterwindow.qdoc new file mode 100644 index 0000000000..fd69d6d9f9 --- /dev/null +++ b/src/gui/doc/examples/rasterwindow.qdoc @@ -0,0 +1,161 @@ +**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example gui/rasterwindow + \title Raster Window Example + + This example shows how to create a minimal QWindow based + application using QPainter for rendering. + + + \section1 Application Entry Point + + \snippet gui/rasterwindow/main.cpp 1 + + The entry point for a QWindow based application is the \l + QGuiApplication class. It manages the GUI application's control + flow and main settings. We pass the command line arguments which + can be used to pick up certain system wide options. + + From there, we go on to create our window instance and then call + the \l QWindow::show() function to tell the windowing system that + this window should now be made visible on screen. + + Once this is done, we enter the application's event loop so the + application can run. + + + \section1 RasterWindow Declaration + + \snippet gui/rasterwindow/rasterwindow.h 1 + + We first start by including the the QtGui headers. This means we + can use all classes in the Qt GUI module. Classes can also be + included individually if that is preferred. + + The RasterWindow class subclasses QWindow directly and provides a + constructor which allows the window to be a sub-window of another + QWindow. Parent-less QWindows show up in the windowing system as + top-level windows. + + The class declares a QBackingStore which is what we use to manage + the window's back buffer for QPainter based graphics. + + \e {The raster window is also reused in a few other examples and adds + a few helper functions, like renderLater().} + + + \section1 RasterWindow Implementation + + \snippet gui/rasterwindow/rasterwindow.cpp 1 + + The constructor first of all calls \l QWindow::create(). This will + create the window in the windowing system. Without calling create, + the window will not get events and will not be visible in the + windowing system. The call to create does not show the window. We + then set the geometry to be something resonable. + + Then we create the backingstore and pass it the window instance it + is supposed to manage. + + \snippet gui/rasterwindow/rasterwindow.cpp 2 + + Shortly after calling \l QWindow::show() on a created window, the + virtual function \l QWindow::exposeEvent() will be called to + notify us that the window's exposure in the windowing system has + changed. The event contains the exposed sub-region, but since we + will anyway draw the entire window every time, we do not make use + of that. + + The function \l QWindow::isExposed() will tell us if the window is + showing or not. We need this as the exposeEvent is called also + when the window becomes obscured in the windowing system. If the + window is showing, we call renderNow() to draw the window + immediately. We want to draw right away so we can present the + system with some visual content. + + + \snippet gui/rasterwindow/rasterwindow.cpp 5 + + The resize event is guaranteed to be called prior to the window + being shown on screen and will also be called whenever the window + is resized while on screen. We use this to resize the back buffer + and call renderNow() if we are visible to immediately update the + visual representation of the window on screen. + + \snippet gui/rasterwindow/rasterwindow.cpp 3 + + The renderNow function sets up what is needed for a \l QWindow to + render its content using QPainter. As obscured windows have will + not be visible, we abort if the window is not exposed in the + windowing system. This can for instance happen when another window + fully obscures this window. + + We start the drawing by calling \l QBackingStore::beginPaint() on + the region we want to draw. Then we get the \l QPaintDevice of the + back buffer and create a QPainter to render to that paint device. + + To void leaving traces from the previous rendering and start with a + clean buffer, we fill the entire buffer with the color white. Then + we call the virtual render() function which does the actual + drawing of this window. + + After drawing is complete, we call endPaint() to signal that we + are done rendering and present the contents in the back buffer + using \l QBackingStore::flush(). + + + \snippet gui/rasterwindow/rasterwindow.cpp 4 + + The render function contains the drawing code for the window. In + this minial example, we only draw the string "QWindow" in the + center. + + + \section1 Rendering Asynchronously + + + \snippet gui/rasterwindow/rasterwindow.cpp 6 + + We went through a few places where the window needed to repainted + immediately. There are some cases where this is not desierable, + but rather let the application return to the event loop and + later. We acheive this by posting an even to ourself which will + then be delivered when the application returns to the \l + QGuiApplication event loop. To avoid posting new requests when one + is already pending, we store this state in the \c m_update_pending + variable. + + \snippet gui/rasterwindow/rasterwindow.cpp 7 + + We reimplement the virtual \l QObject::event() function to handle + the update event we posted to ourselves. When the event comes in + we reset the pending update flag and call renderNow() to render + the window right away. + + */ diff --git a/src/gui/doc/images/analogclock-window-example.png b/src/gui/doc/images/analogclock-window-example.png Binary files differnew file mode 100644 index 0000000000..ffd7baa716 --- /dev/null +++ b/src/gui/doc/images/analogclock-window-example.png diff --git a/src/gui/doc/images/analogclockwindow-viewport.png b/src/gui/doc/images/analogclockwindow-viewport.png Binary files differnew file mode 100644 index 0000000000..31ce0c3c6e --- /dev/null +++ b/src/gui/doc/images/analogclockwindow-viewport.png diff --git a/src/gui/doc/src/coordsys.qdoc b/src/gui/doc/src/coordsys.qdoc index c0e33c974e..b4be1c0b27 100644 --- a/src/gui/doc/src/coordsys.qdoc +++ b/src/gui/doc/src/coordsys.qdoc @@ -230,14 +230,13 @@ \row \li {2,1} - \snippet widgets/analogclock/analogclock.cpp 9 + \snippet gui/analogclock/main.cpp 1 - 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. + 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 @@ -245,7 +244,7 @@ See also the \l {Window-Viewport Conversion} section. - \snippet widgets/analogclock/analogclock.cpp 18 + \snippet gui/analogclock/main.cpp 2 We draw the clock's hour hand by rotating the coordinate system and calling QPainter::drawConvexPolygon(). Thank's to the @@ -260,14 +259,14 @@ the code guarantees that the code that follows won't be disturbed by the transformations we've used. - \snippet widgets/analogclock/analogclock.cpp 24 + \snippet gui/analogclock/main.cpp 3 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 widgets/analogclock/analogclock.cpp 27 + \snippet gui/analogclock/main.cpp 4 Finally, we draw the clock face, which consists of twelve short lines at 30-degree intervals. At the end of that, the painter is @@ -440,9 +439,5 @@ \endtable \endomit - \sa {Analog Clock Example} + \sa {Analog Clock Window Example} */ - -/* - ### DOC-TODO: rewrite analog clock to be QWindow based - */
\ No newline at end of file diff --git a/src/gui/doc/src/qtgui.qdoc b/src/gui/doc/src/qtgui.qdoc index 64d9cb67fd..0421b172cf 100644 --- a/src/gui/doc/src/qtgui.qdoc +++ b/src/gui/doc/src/qtgui.qdoc @@ -63,9 +63,10 @@ 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. + than the enablers found in the Qt GUI module. + - \section1 Application Windows The most important classes in the Qt GUI module are @@ -73,7 +74,7 @@ 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. + 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 @@ -83,16 +84,16 @@ \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}. + System} and \l {Raster Window Example}. Qt can load and save images using the \l QImage and \l QPixmap classes. By default, Qt supports the most common image formats @@ -109,7 +110,7 @@ \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 @@ -126,7 +127,6 @@ be used in combination with \l QPainter and \l QOpenGLPaintDevice to have OpenGL hardware accellerated 2D graphics, by sacrificing some of the visual quality. - @@ -148,14 +148,6 @@ /* - ### 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 |
