From 0cbcc61ef35b9bce1d65d048853c79004b755b87 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Wed, 11 May 2011 17:35:46 +0200 Subject: Squashed commit of changes from the 4.8-temp branch. --- doc/src/examples/applicationicon.qdoc | 88 +++++++++++++++ doc/src/examples/cube.qdoc | 178 ++++++++++++++++++++++++++++++ doc/src/examples/elidedlabel.qdoc | 162 ++++++++++++++++++++++++++++ doc/src/examples/maemovibration.qdoc | 164 ++++++++++++++++++++++++++++ doc/src/examples/orientation.qdoc | 143 ++++++++++++++++++++++++ doc/src/examples/symbianvibration.qdoc | 192 +++++++++++++++++++++++++++++++++ 6 files changed, 927 insertions(+) create mode 100644 doc/src/examples/applicationicon.qdoc create mode 100644 doc/src/examples/cube.qdoc create mode 100644 doc/src/examples/elidedlabel.qdoc create mode 100644 doc/src/examples/maemovibration.qdoc create mode 100644 doc/src/examples/orientation.qdoc create mode 100644 doc/src/examples/symbianvibration.qdoc (limited to 'doc/src/examples') 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 /^\}/ +*/ -- cgit v1.2.3