diff options
Diffstat (limited to 'src/gui/doc/examples')
| -rw-r--r-- | src/gui/doc/examples/analogclockwindow.qdoc | 138 | ||||
| -rw-r--r-- | src/gui/doc/examples/rasterwindow.qdoc | 161 |
2 files changed, 299 insertions, 0 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. + + */ |