summaryrefslogtreecommitdiffstats
path: root/src/gui/doc
diff options
context:
space:
mode:
authorSamuel Rødal <samuel.rodal@nokia.com>2012-08-31 15:43:49 +0200
committerQt by Nokia <qt-info@nokia.com>2012-09-01 11:21:46 +0200
commit65f5909df2b660402cf89031b8a1b308df289823 (patch)
tree0966b879b06c903cde7ca4cc67fb6b895ebce696 /src/gui/doc
parent3d04e4965e292be59464acc18c8306d89d3be3e1 (diff)
Moved gui example documentation to the proper location.
Gui example documentation should be in examples/gui/doc/ Change-Id: I3cd196a2bb5d76b6e275f336b29a2ad1811159dd Reviewed-by: Frederik Gladhorn <frederik.gladhorn@nokia.com>
Diffstat (limited to 'src/gui/doc')
-rw-r--r--src/gui/doc/examples/analogclockwindow.qdoc138
-rw-r--r--src/gui/doc/examples/rasterwindow.qdoc161
-rw-r--r--src/gui/doc/qtgui.qdocconf12
3 files changed, 8 insertions, 303 deletions
diff --git a/src/gui/doc/examples/analogclockwindow.qdoc b/src/gui/doc/examples/analogclockwindow.qdoc
deleted file mode 100644
index 17db0511f8..0000000000
--- a/src/gui/doc/examples/analogclockwindow.qdoc
+++ /dev/null
@@ -1,138 +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$
-**
-****************************************************************************/
-
-/*!
- \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 reasonable 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
deleted file mode 100644
index d78f003b40..0000000000
--- a/src/gui/doc/examples/rasterwindow.qdoc
+++ /dev/null
@@ -1,161 +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$
-**
-****************************************************************************/
-
-/*!
- \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 reasonable.
-
- 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/qtgui.qdocconf b/src/gui/doc/qtgui.qdocconf
index 5fdc9b7818..85fcbab3ca 100644
--- a/src/gui/doc/qtgui.qdocconf
+++ b/src/gui/doc/qtgui.qdocconf
@@ -71,12 +71,16 @@ depends += qtcore
headerdirs += ..
-sourcedirs += ..
+sourcedirs += .. \
+ ../../../examples/gui/doc
-exampledirs += ../../../examples \
+exampledirs += ../../../examples/gui \
+ ../../../doc/src/snippets \
../ \
snippets
-excludedirs += ../../../examples/widgets/doc
+excludedirs += snippets
-imagedirs += images
+imagedirs += images \
+ ../../../doc/src/images \
+ ../../../examples/gui/doc/images