Squashed commit of changes from the 4.8-temp branch.

6 files changed, 927 insertions, 0 deletions

diff --git a/doc/src/examples/applicationicon.qdoc b/doc/src/examples/applicationicon.qdoc
new file mode 100644
index 0000000000..d03bf3634a
--- /dev/null
+++ b/doc/src/examples/applicationicon.qdoc
@@ -0,0 +1,88 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial Usage
+** Licensees holding valid Qt Commercial licenses may use this file in
+** accordance with the Qt Commercial License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in a
+** written agreement between you and Nokia.
+**
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*! \example widgets/applicationicon
+    \group all-examples
+    \title Application Icon Example
+
+    The example shows how to add an application icon to a mobile application.
+
+    \image appicon_screenshot.png The icon on a Nokia XPressMusic 5800
+
+    \section1 Creating an icon for Maemo
+
+    Maemo expects the icon of an application to be a 64x64 PNG image file. The
+    file name of the icon should be the same as the executable with a \c .png
+    extension. You also need a \c .desktop file that gives the window manager
+    hints about the application, such as name, type and icon.
+
+    \quotefile examples/widgets/applicationicon/applicationicon.desktop
+
+    The \c Icon field should also contain the name of the executable. On the
+    device, application icons are stored in the
+    \c /usr/share/icons/hicolor/64x64/apps directory
+    and desktop files in the \c /usr/share/applications/hildon directory.
+
+    \section1 Creating an icon for Symbian
+
+    Symbian uses Scalable Vector Graphics (SVG Tiny 1.1+) to render
+    application icons in the application menu. Therefore icons could be
+    created manually with a text editor, since SVG files are plain text with
+    XML syntax, but usually you would use a vector graphics program that is
+    able to output SVG files. Popular graphics programs such as Adobe
+    Illustrator or Inkscape are able to do so.
+
+    For best results, the icon should be created on a 44x44 pixel canvas.
+    Otherwise the image might be scaled in unexpected ways.
+
+    Once you have created your icon, make sure that it is stored according to
+    the SVG-Tiny 1.1+ standard. Inkscape, for instance, is not able to save
+    images that way, but there are tools that can convert general SVG files
+    into the Tiny format. For instance, the svg2svgt tool that is bundled with
+    Symbian 3rd and 5th editon SDKs under the folder s60tools can do this
+    conversion to some extent. Another tool to convert SVG to SVG Tiny is SVG
+    Pony.
+
+    \section1 Adding the icons to the project
+
+    Edit the .pro file and specify the ICON variable for the symbian target. 
+    For Maemo, we need to add that the \c .desktop and icon file should be
+    installed.
+
+    \quotefile examples/widgets/applicationicon/applicationicon.pro
+
+    Currently, Qt Creator doesn't include the icon and desktop files in the
+    application package for Maemo, merely the executable file is included. As a
+    workaround for this, the files can be added manually in the Projects tab.
+    In the "Create Package" build step for the Maemo target, the \c .desktop
+    file and icon can be added to be a part of the package contents.
+    Unfortunately, these additions are only stored as a part of the
+    \c .pro.user file. This issue will be resolved in a future release of
+    Qt Creator.
+
+    \image appicon_packagecontents.png Manual addition of files to the "Create Package" build step
+*/
diff --git a/doc/src/examples/cube.qdoc b/doc/src/examples/cube.qdoc
new file mode 100644
index 0000000000..0603941c7b
--- /dev/null
+++ b/doc/src/examples/cube.qdoc
@@ -0,0 +1,178 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example opengl/cube
+    \group all-examples
+    \title Cube OpenGL ES 2.0 example
+
+    The Cube OpenGL ES 2.0 example shows how to write mouse rotateable
+	textured 3D cube using OpenGL ES 2.0 with Qt. It shows how to handle
+	polygon geometries efficiently and how to write simple vertex and
+	fragment shader for programmable graphics pipeline. In addition it
+	shows how to use quaternions for representing 3D object orientation.
+
+    This example has been written for OpenGL ES 2.0 but it works also on
+	desktop OpenGL because this example is simple enough and for the
+	most parts desktop OpenGL API is same. It compiles also without OpenGL
+	support but then it just shows a label stating that OpenGL support is
+	required.
+
+	\image cube.png Screenshot of the Cube example running on N900
+
+	The example consist of two classes:
+
+	\list
+	\o \c MainWidget extends QGLWidget and contains OpenGL ES 2.0
+		initialization and drawing and mouse and timer event handling
+	\o \c GeometryEngine handles polygon geometries. Transfers polygon geometry
+		to vertex buffer objects and draws geometries from vertex buffer objects.
+	\endlist
+
+	We'll start by initializing OpenGL ES 2.0 in \c MainWidget.
+
+	\tableofcontents
+
+	\section1 Initializing OpenGL ES 2.0
+
+	Since OpenGL ES 2.0 doesn't support fixed graphics pipeline anymore it has to
+	be implemented by ourselves. This makes graphics pipeline very flexible but
+	in the same time it becomes more difficult because user has to implement graphics
+	pipeline to get even the simplest example running. It also makes graphics pipeline
+	more efficient because user can decide what kind of pipeline is needed for the
+	application.
+
+	First we have to implement vertex shader. It gets vertex data and
+	model-view-projection matrix (MVP) as parameters. It transforms vertex position
+	using MVP matrix to screen space and passes texture coordinate to
+	fragment shader. Texture coordinate will be automatically interpolated on polygon
+	faces.
+
+	\snippet examples/opengl/cube/vshader.glsl 0
+
+	After that we need to implement second part of the graphics pipeline - fragment
+	shader. For this exercise we need to implement fragment shader that handles
+	texturing. It gets interpolated texture coordinate as a parameter and looks up
+	fragment color from the given texture.
+
+	\snippet examples/opengl/cube/fshader.glsl 0
+
+	Using \c QGLShaderProgram we can compile, link and bind shader code to
+	graphics pipeline. This code uses Qt Resource files to access shader source code.
+
+	\snippet examples/opengl/cube/mainwidget.cpp 3
+
+	The following code enables depth buffering and back face culling.
+
+	\snippet examples/opengl/cube/mainwidget.cpp 2
+
+	\section1 Loading textures from Qt Resource files
+
+	\c QGLWidget interface implements methods for loading textures from QImage to GL
+	texture memory. We still need to use OpenGL provided functions for specifying
+	the GL texture unit and configuring texture filtering options.
+
+	\snippet examples/opengl/cube/mainwidget.cpp 4
+
+	\section1 Cube Geometry
+
+	There are many ways to render polygons in OpenGL but the most efficient way is
+	to use only triangle strip primitives and render vertices from graphics hardware
+	memory. OpenGL has a mechanism to create buffer objects to this memory area and
+	transfer vertex data to these buffers. In OpenGL terminology these are referred
+	as Vertex Buffer Objects (VBO).
+
+	\image cube_faces.png Cube faces and vertices
+
+	This is how cube faces break down to triangles. Vertices are ordered this way
+	to get vertex ordering correct using triangle strips. OpenGL determines triangle
+	front and back face based on vertex ordering. By default OpenGL uses
+	counter-clockwise order for front faces. This information is used by back face
+	culling which improves rendering performance by not rendering back faces of the
+	triangles. This way graphics pipeline can omit rendering sides of the triangle that
+	aren't facing towards screen.
+
+	Creating vertex buffer objects and transferring data to them is quite simple using
+	OpenGL provided functions.
+
+	\snippet examples/opengl/cube/geometryengine.cpp 0
+
+	\snippet examples/opengl/cube/geometryengine.cpp 1
+
+	Drawing primitives from VBOs and telling programmable graphics pipeline how to
+	locate vertex data requires few steps. First we need to bind VBOs to be used.
+	After that we bind shader program attribute names and configure what
+	kind of data it has in the bound VBO. Finally we'll draw triangle
+	strip primitives using indices from the other VBO.
+
+	\snippet examples/opengl/cube/geometryengine.cpp 2
+
+	\section1 Perspective projection
+
+	Using \c QMatrix4x4 helper methods it's really easy to calculate perpective
+	projection matrix. This matrix is used to project vertices to screen space.
+
+	\snippet examples/opengl/cube/mainwidget.cpp 5
+
+	\section1 Orientation of the 3D object
+
+	Quaternions are handy way to represent orientation of the 3D object. Quaternions
+	involve quite complex mathematics but fortunately all the necessary mathematics
+	behind quaternions is implemented in \c QQuaternion. That allows us to store
+	cube orientation in quaternion and rotating cube around given axis is quite
+	simple.
+
+	The following code calculates rotation axis and angular speed based on mouse events.
+
+	\snippet examples/opengl/cube/mainwidget.cpp 0
+
+	\c QBasicTimer is used to animate scene and update cube orientation. Rotations
+	can be concatenated simply by multiplying quaternions.
+
+	\snippet examples/opengl/cube/mainwidget.cpp 1
+
+	Model-view matrix is calculated using the quaternion and by moving world by Z axis.
+	This matrix is multiplied with the projection matrix to get MVP matrix for shader
+	program.
+
+	\snippet examples/opengl/cube/mainwidget.cpp 6
+
+*/
diff --git a/doc/src/examples/elidedlabel.qdoc b/doc/src/examples/elidedlabel.qdoc
new file mode 100644
index 0000000000..4c6e8e8128
--- /dev/null
+++ b/doc/src/examples/elidedlabel.qdoc
@@ -0,0 +1,162 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial Usage
+** Licensees holding valid Qt Commercial licenses may use this file in
+** accordance with the Qt Commercial License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in a
+** written agreement between you and Nokia.
+**
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example widgets/elidedlabel
+    \group all-examples
+    \title Elided Label Example
+
+    This example creates a widget similar to QLabel, that elides the last
+    visible line, if the text is too long to fit the widget's geometry.
+
+    \image elidedlabel-example.png Elided Label example on XPressMusic 5800
+
+    When text of varying length has to be displayed in a uniformly sized
+    area, for instance within a list or grid view where all list items have the
+    same size, it can be useful to give the user a visual clue when not all
+    text is visible. QLabel can elide text that doesn't fit within it, but only
+    in one line. The \c ElidedLabel widget shown in this example word wraps its
+    text by its width, and elides the last visible line if some text is left
+    out. \c TestWidget gives control to the features of \c ElidedWidget and
+    forms the example application.
+
+
+    \section1 ElidedLabel Class Definition
+
+    Like QLabel, \c ElidedLabel inherits from QFrame. Here's the definition of
+    the \c ElidedLabel class:
+
+
+    \snippet examples/widgets/elidedlabel/elidedlabel.h 0
+
+    The \c isElided property depends the font, text content and geometry of the
+    widget. Whenever any of these change, the \c elisionChanged() signal might
+    trigger. We cache the current elision value in \c elided, so that it
+    doesn't have to be recomputed every time it's asked for.
+
+
+    \section1 ElidedLabel Class Implementation
+
+    Except for initializing the member variables, the constructor sets the size
+    policy to be horizontally expanding, since it's meant to fill the width of
+    its container and grow vertically.
+
+    \snippet examples/widgets/elidedlabel/elidedlabel.cpp 0
+
+    Changing the \c content require a repaint of the widget.
+
+    \snippet examples/widgets/elidedlabel/elidedlabel.cpp 1
+
+    QTextLayout is used in the \c paintEvent() to divide the \c content into
+    lines, that wrap on word boundaries. Each line, except the last visible
+    one, is drawn \c lineSpacing pixels below the previous one. The \c draw()
+    method of QTextLine will draw the line using the coordinate point as the
+    top left corner.
+
+    \snippet examples/widgets/elidedlabel/elidedlabel.cpp 2
+
+    Unfortunately, QTextLayout does not elide text, so the last visible line
+    has to be treated differently. This last line is elided if it is too wide.
+    The \c drawText() method of QPainter draws the text starting from the base
+    line, which is \c ascecnt() pixels below the last drawn line.
+
+    Finally, one more line is created to see if everything fit on this line.
+
+    \snippet examples/widgets/elidedlabel/elidedlabel.cpp 3
+
+    If the text was elided and wasn't before or vice versa, cache it in
+    \c elided and emit the change.
+
+    \snippet examples/widgets/elidedlabel/elidedlabel.cpp 4
+
+
+    \section1 TestWidget Class Definition
+
+    \c TestWidget is a QWidget and is the main window of the example. It
+    contains an \c ElidedLabel which can be resized with two QSlider widgets.
+
+    \snippet examples/widgets/elidedlabel/testwidget.h 0
+
+    \section1 TestWidget Class Implementation
+
+    The constructor initializes the whole widget. Strings of different length
+    are stored in \c textSamples. The user is able to switch between these.
+
+    \snippet examples/widgets/elidedlabel/testwidget.cpp 0
+
+    An \c ElidedLabel is created to contain the first of the sample strings.
+    The frame is made visible to make it easier to see the actual size of the
+    widget.
+
+    \snippet examples/widgets/elidedlabel/testwidget.cpp 1
+
+    The buttons and the elision label are created. By connecting the
+    \c elisionChanged() signal to the \c setVisible() slot of the \c label,
+    it will act as an indicator to when the text is elided or not. This signal
+    could, for instance, be used to make a "More" button visible, or similar.
+
+    \snippet examples/widgets/elidedlabel/testwidget.cpp 2
+
+    The \c widthSlider and \c heightSlider specify the size of the
+    \c elidedText. Since the y-axis is inverted, the \c heightSlider has to be
+    inverted to act appropriately.
+
+    \snippet examples/widgets/elidedlabel/testwidget.cpp 3
+
+    The components are all stored in a QGridLayout, which is made the layout of
+    the \c TestWidget.
+
+    \snippet examples/widgets/elidedlabel/testwidget.cpp 4
+
+    On the Maemo platform, windows are stuck in landscape mode by default. With
+    this attribute set, the window manager is aware that this window can be
+    rotated.
+
+    \snippet examples/widgets/elidedlabel/testwidget.cpp 5
+
+    The \c widthSlider and \c heightSlider have the exact same length as the
+    dimensions of the \c elidedText. The maximum value for both of them is
+    thus their lengths, and each tick indicates one pixel.
+
+    \snippet examples/widgets/elidedlabel/testwidget.cpp 6
+
+    The \c switchText() slot simply cycles through all the available sample
+    texts.
+
+    \snippet examples/widgets/elidedlabel/testwidget.cpp 7
+
+    These slots set the width and height of the \c elided text, in response to
+    changes in the sliders.
+
+    \section1 The \c main() Function
+
+    The \c main() function creates an instance of \c TestWidget fullscreen and
+    enters the message loop.
+
+    \snippet examples/widgets/elidedlabel/main.cpp 0
+*/
+
diff --git a/doc/src/examples/maemovibration.qdoc b/doc/src/examples/maemovibration.qdoc
new file mode 100644
index 0000000000..280dc30c99
--- /dev/null
+++ b/doc/src/examples/maemovibration.qdoc
@@ -0,0 +1,164 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial Usage
+** Licensees holding valid Qt Commercial licenses may use this file in
+** accordance with the Qt Commercial License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in a
+** written agreement between you and Nokia.
+**
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example widgets/maemovibration
+    \group all-examples
+    \title Maemo Vibration Example
+
+    The Maemo Vibration example shows how to tell the Maemo Mode Control Entity
+    (MCE) to vibrate a maemo device.
+
+    The MCE is a system service on Maemo that, among other things, provides an
+    D-Bus interface to trigger vibrations. The vibrations are specified as
+    patterns and are defined in a system configuration file.
+
+    The example program reads the configuration file to look for possible
+    vibration patterns and display a button for each. Pressing a button will
+    make the device vibrate accordingly, until the application closes, or
+    another pattern is started.
+
+    \image maemovibration-example.png Screenshot of the Maemo Vibration Example
+
+    The code makes use of two classes:
+
+    \list
+    \o \c MceVibrator connects to the MCE service and can start a certain
+       vibrator pattern. It also is responsible to parse the configuration
+       file.
+
+    \o \c ButtonWidget provides a button for each pattern. Pressing the button
+       activates the pattern in question.
+    \endlist
+
+
+    \section1 MceVibrator Class Definition
+
+    \snippet examples/widgets/maemovibration/mcevibrator.h 0
+
+    The \c MceVibrator class inherits from QObject and provides a specialized
+    and Qt friendly interface to the MCE vibration facilty. The slot \c vibrate()
+    can be called to make the device vibrate according to a specific pattern
+    name. We will connect it to a signal of a \c ButtonWidget object later. The
+    static method \c ParsePatternNames() can be called to find out which patterns
+    are available to us.
+
+    \list
+    \o \c mceInterface is our D-Bus handle to the MCE service. We use it to
+       invoke methods on the MCE request object.
+
+    \o \c lastPatternName contains the pattern that was activated last time. We
+       have to keep track of this, because the last pattern has to be
+       deactivated before activating a new pattern.
+    \endlist
+
+
+    \section1 MceVibrator Class Implementation
+
+    To connect to the service, we initialize the D-Bus interface handle. The
+    system header \c "mce/dbus-names.h" contains definitions of the D-Bus
+    service name and request object path and interface. These are passed to the
+    constructor of the handle, and Qt will automatically establish a connection
+    to it, if it is possible.
+
+    The MCE expects us to first enable the vibrator before we can use it. This
+    is done with the call to the \c MCE_ENABLE_VIBRATOR D-Bus method.
+
+    \snippet examples/widgets/maemovibration/mcevibrator.cpp 0
+
+    From now on we can activate vibration patterns. Each time a vibration
+    pattern is activated, the last pattern has to be deactivated first. In the
+    vibrate slot we use the MCE interface to call the activation method.
+
+    \snippet examples/widgets/maemovibration/mcevibrator.cpp 1
+
+    The calls to the private method deactivate simply makes sure to deactivate
+    the last pattern used, if there was one.
+
+    \snippet examples/widgets/maemovibration/mcevibrator.cpp 2
+
+    Calling either the activate or deactivate MCE D-Bus method with invalid
+    pattern names are ignored.
+
+    Finally, the destructor disables the vibrator. When the destructor of the
+    MCE interface handle is called, the connection is also closed.
+
+    \snippet examples/widgets/maemovibration/mcevibrator.cpp 3
+
+    The MCE configuration file contains options for many different things. We
+    are only interested in one line that contains the vibration patterns. It
+    has the following format:
+
+
+    \code
+    VibratorPatterns=semicolon;separated;list;of;values
+    \endcode
+
+    The static method \c ParsePatternNames looks for this line and returns a
+    QStringList containing the values, which are the pattern names we can use.
+
+    \snippet examples/widgets/maemovibration/mcevibrator.cpp 4
+
+    The helper function \c checkError() saves us some code duplication. None of the
+    called methods return anything of use to us, so we're only interested in
+    getting error messages for debugging.
+
+    \snippet examples/widgets/maemovibration/mcevibrator.cpp 5
+
+
+    \section1 ButtonWidget Class Definition
+
+    \snippet examples/widgets/maemovibration/buttonwidget.h 0
+
+    The \c ButtonWidget class inherits from QWidget and provides the main user
+    interface for the application. It creates a grid of buttons, one for each
+    string in the stringlist passed to the constructor. Pressing a button emits
+    the \c clicked() signal, where the string is the text of the button that
+    was pressed.
+
+    This class is taken from the QSignalMapper documentation. The only change
+    is the number of columns in the grid from three to two, to make the button
+    labels fit.
+
+
+    \section1 ButtonWidget Class Implementation
+
+    \snippet examples/widgets/maemovibration/buttonwidget.cpp 0
+
+
+    \section1 \c main() Function
+
+    The main function begins with looking up the patterns available to us.
+
+    \snippet examples/widgets/maemovibration/main.cpp 0
+
+    Then we create one instance of both classes, and connects the
+    \c ButtonWidget's clicked signal to the \c MceVibrator's \c vibrate() slot.
+    This works, since the button texts are the same as the pattern names.
+
+    \snippet examples/widgets/maemovibration/main.cpp 1
+*/
diff --git a/doc/src/examples/orientation.qdoc b/doc/src/examples/orientation.qdoc
new file mode 100644
index 0000000000..cfe17576e7
--- /dev/null
+++ b/doc/src/examples/orientation.qdoc
@@ -0,0 +1,143 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial Usage
+** Licensees holding valid Qt Commercial licenses may use this file in
+** accordance with the Qt Commercial License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in a
+** written agreement between you and Nokia.
+**
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*! \example widgets/orientation
+    \group all-examples
+    \title Orientation Example
+
+    The example shows a simple way to use different UIs depending on the screen
+    orientation of a mobile device.
+
+    \image orientation-landscape.png The UI in landscape mode
+    \image orientation-portrait.png The UI in portrait mode
+
+    The screen on many mobile devices can be viewed in both portrait and
+    landscape orientation. The orientation can be swiched with the help of a
+    hardware or software trigger. Due to the often small physical screen size,
+    user interfaces has to be very simple and compact to stay usable, and
+    applications usually occupy the whole screen. Designing a user interface
+    that works equally well in both landscape and portrait mode is not always
+    possible, however, so making a different layout for each case usually pays
+    off.
+
+    The example application makes use of two different UI widgets created with
+    the Qt Designer, one for portrait and one for landscape orientation. The
+    application has a widget that contains an image and the user is able to
+    select one of three images for it to show. In addition to the two UIs, the
+    application consists of a \c MainWindow class.
+
+    \section1 Landscape UI
+
+    If the screen is in landscape mode, the user probably holds the device with
+    both hands and is ready to give full attention to the application. The
+    landscape UI looks like this:
+
+    \image orientation-landscape-ui.png The landscape UI
+
+    To the left is a QWidget called \c choiceWidget, which will show the
+    current image, and to the right are three QRadioButton instances. The
+    active radio button specifies the image to show.
+
+    \section1 Portrait UI
+
+    When the device is in portrait mode, it usually means that the user holds
+    it with one hand, and can comfortably use the thumb for small amounts of
+    input. The layout is simpler, and is focused on consuming content. The
+    portrait UI looks like this:
+
+    \image orientation-portrait-ui.png The portrait UI
+
+    Similarly, it contains a QWidget, also called \c choiceWidget, that will
+    show the current image. In contrast to the landscape UI, this one doesn't
+    provide any controls to change the image.
+
+    \section1 MainWindow Class Definition
+
+    \c MainWindow inherits from QWidget and acts as the top level widget of the
+    application.
+
+    \snippet examples/widgets/orientation/mainwindow.h 0
+
+    The \c resizeEvent() method is re-implemented, and used to check which
+    UI to show. The \c onRadioButtonClicked() slot is connected to the
+    landscape UI's radio button group and selects the current image.
+
+    \c landscapeWidget and \c portraitWidget will contain the UI layouts. Only
+    one of them is visible at a time.
+
+    \section1 MainWindow Class Implementation
+
+    In the constructor, the widgets that will hold the UIs are created and set
+    up.
+
+    \snippet examples/widgets/orientation/mainwindow.cpp 0
+
+    Since the exit buttons on the layouts are different from each other, both
+    of them have to have their \c clicked() signal connected to the \c close()
+    slot of the main widget. The first image is also made current with the call
+    to \c onRadioButtonClicked().
+
+    \snippet examples/widgets/orientation/mainwindow.cpp 1
+
+    On the Maemo platform, windows are stuck in landscape mode by default. The
+    application has to explicitly say that rotation is supported.
+
+    \snippet examples/widgets/orientation/mainwindow.cpp 2
+
+    The \c resizeEvent() is called when the main window is first created, and
+    also whenever the window has been resized. If the window is shown in
+    full screen, this is an indication that the orientation of the screen has
+    changed.
+
+    The dimensions of \c landscapeWidget is the transpose of the dimensions of
+    \c portraitWidget. When the orientation is known, both are set to the
+    (possibly transposed) size of the window. Depending on the orientation, one
+    widget is made visible and the other invisible.
+
+    \snippet examples/widgets/orientation/mainwindow.cpp 3
+
+    When the user selects one of the radio buttons in the landscape UI, the
+    current image is changed. The image is displayed by specifying the
+    background style of the choice widget. Since both \c portrait and
+    \c landscape have a \c choiceWidget of their own, the change has to be
+    reflected in both instances.
+
+    \snippet examples/widgets/orientation/mainwindow.cpp 4
+
+    Synchronizing both UIs like this might become unfeasible when there are
+    many things that can change. In that case it is better to make use of the
+    \l{Introduction to Model/View Programming}{Model-View-Controller pattern}
+    more extensively and share the content between both portrait and landscape
+    widgets. Then an interface for displaying and manipulating it can be tailor
+    made for both orientations.
+
+    \section1 The \c main() Function
+
+    The main function creates a \c MainWindow instance and shows it full
+    screen.
+    \snippet examples/widgets/orientation/main.cpp 0
+*/
diff --git a/doc/src/examples/symbianvibration.qdoc b/doc/src/examples/symbianvibration.qdoc
new file mode 100644
index 0000000000..a0de23685d
--- /dev/null
+++ b/doc/src/examples/symbianvibration.qdoc
@@ -0,0 +1,192 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial Usage
+** Licensees holding valid Qt Commercial licenses may use this file in
+** accordance with the Qt Commercial License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in a
+** written agreement between you and Nokia.
+**
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*! \example widgets/symbianvibration
+    \group all-examples
+    \title Symbian Vibration Example
+
+    The Symbian Vibrator example shows how to get fine-grained vibration
+    control on Symbian devices.
+
+    Native Symbian APIs have to be used to enable vibration, since QtMobility
+    doesn't provide an interface for it yet. It is, however, planned to be
+    included in a future release. In anticipation for that, we make use of the
+    \c XQVibra class that was a part of the Mobile Extensions Technology Preview
+    API for Qt for Symbian. The pre-compiled libraries are no longer compatible
+    with Qt 4.6, but we can include the source code itself with the project.
+
+    \image symbianvibration-example.png Screenshot of the Symbian Vibration example
+
+    The example application divides the window into rectangles, which can be
+    pressed to make the device vibrate. Pressing different rectangles make the
+    device vibrate with different intensities. Each rectangle has a different
+    color and its intensity number is drawn on top of it. Moving the cursor
+    from one rectangle to another changes the vibration intensity to that of
+    the new one.  Vibration stops when the mouse button has been released. It
+    is also possible to launch a short burst of vibration through the menu.
+
+    The example consists of four classes:
+
+    \list
+    \o \c XQVibra is the vibration interface class taken from the Mobile
+       Extensions for Qt for Symbian.
+
+    \o \c XQVibraPrivate is the Symbian specific private implementation of the
+       vibration implementation.
+
+    \o \c VibrationSurface is a custom widget that uses a XQVibra instance to
+       vibrate the device depending on where the user presses.
+
+    \o \c MainWindow inherits from QMainWindow and contains a \c VibrationSurface
+       as its central widget, and also has a menu from which it is possible to
+       make the phone vibrate.
+    \endlist
+
+    \section1 XQVibra Class Definition
+
+    The \c XQVibra class uses the pimpl-idiom to hide the platform specific
+    implementation behind a common interface. Technically it would be possible
+    to support more target platforms, with only the addition of a private
+    implementation. The rest of the code would work the same, since only the
+    common interface is used.
+
+    \snippet examples/widgets/symbianvibration/xqvibra.h 0
+
+    \c XQVibra provides a very simple interface for us to use. The interesting
+    part are the three slots \c start(), \c stop() and \c setIntensity(). Calling the start
+    method initiates vibration for the specified duration. Calling it while the
+    device is already vibrating causes it to stop the current one and start the
+    new one, even if the intensities are the same. The \c setIntensity() method
+    should be called before starting vibration.
+
+
+    \section1 VibrationSurface Class Definition
+
+    \c VibrationSurface inherits from QWidget and acts like a controller for a
+    \c XQVibra object. It responds to mouse events and performs custom painting.
+
+    \snippet examples/widgets/symbianvibration/vibrationsurface.h 0
+
+    The virtual event methods are reimplemented from QWidget. As can be seen,
+    there is no public programmable interface beyond what QWidget provides.
+
+
+    \section1 VibrationSurface Class Implementation
+
+    Mouse events control the intensity of the vibration.
+
+    \snippet examples/widgets/symbianvibration/vibrationsurface.cpp 0
+    \codeline
+    \snippet examples/widgets/symbianvibration/vibrationsurface.cpp 1
+    \codeline
+    \snippet examples/widgets/symbianvibration/vibrationsurface.cpp 2
+
+    Presses starts the vibration, movement changes the intensity and releases
+    stops the vibration. To set the right amount of vibration, the private
+    method \c applyIntensity() is used. It sets the vibration intensity according to
+    which rectangle the mouse currently resides in.
+
+    \snippet examples/widgets/symbianvibration/vibrationsurface.cpp 3
+
+    We make sure only to change the intensity if it is different than last
+    time, so that the vibrator isn't stopped and restarted unnecessarily.
+
+    The range of vibration intensity ranges from 0 to XQVibra::MaxIntensity. We
+    divide this range into a set of levels. The number of levels and the intensity
+    increase for each level are stored in two constants.
+
+    \snippet examples/widgets/symbianvibration/vibrationsurface.cpp 4
+
+    Each rectangle has an intensity of one \c IntensityPerLevel more than the
+    previous one.
+
+    \snippet examples/widgets/symbianvibration/vibrationsurface.cpp 5
+
+    The rectangles are either put in a row, if the widget's width is greater
+    than its height (landscape), otherwise they are put in a column (portrait).
+    Each rectangle's size is thus dependent on the length of the width or the
+    height of the widget, whichever is longer. The length is then divided by
+    the number of levels, which gets us either the height or the width of each
+    rectangle. The dx and dy specify the distance from one rectangle to the
+    next, which is the same as either the width or height of the rectangle.
+
+    \snippet examples/widgets/symbianvibration/vibrationsurface.cpp 6
+
+    For each level of intensity, we draw a rectangle with increasing
+    brightness.  On top of the rectangle a text label is drawn, specifying the
+    intesity of this level. We use the rectangle rect as a template for
+    drawing, and move it down or right at each iteration.
+
+    The intensity is calculated by dividing the greater of the width and height
+    into \c NumberOfLevels slices.
+
+    \snippet examples/widgets/symbianvibration/vibrationsurface.cpp 7
+
+    In case the widget's geometry is too small to fit all the levels, the user
+    interface will not work. For simplicity, we just return 0.
+
+    When we know the axis along which the rectangles lie, we can find the one
+    in which the mouse cursor lie.
+
+    \snippet examples/widgets/symbianvibration/vibrationsurface.cpp 8
+
+    The final clamp of the intensity value at the end is necessary in case the
+    mouse coordinate lies outside the widget's geometry.
+
+
+    \section1 MainWindow Class Definition
+
+    Here's the definition of the \c MainWindow class:
+
+    \snippet examples/widgets/symbianvibration/mainwindow.h 0
+
+    \c MainWindow is a top level window that uses a \c XQVibra and a
+    \c VibrationSurface. It also adds a menu option to the menu bar which can
+    start a short vibration.
+
+    \section1 MainWindow Class Implementation
+
+    In the \c MainWindow constructor the \c XQVibra and the \c VibrationSurface
+    are created. An action is added to the menu and is connected to the vibrate
+    slot.
+
+    \snippet examples/widgets/symbianvibration/mainwindow.cpp 0
+
+    The \c vibrate() slot offers a way to invoke the vibration in case no
+    mouse is present on the device.
+
+    \snippet examples/widgets/symbianvibration/mainwindow.cpp 1
+
+    \section1 Symbian Vibration Library
+
+    The \c XQVibra class requires a platform library to be included. It is
+    included in the \c .pro file for the symbian target.
+
+    \quotefromfile examples/widgets/symbianvibration/symbianvibration.pro
+    \skipto /^symbian \{/
+    \printuntil /^\}/
+*/