Merge branch 'master' of git@scm.dev.nokia.troll.no:qt/qt

12 files changed, 415 insertions, 3 deletions

diff --git a/doc/src/containers.qdoc b/doc/src/containers.qdoc
index 11a4b0b..2a34716 100644
--- a/doc/src/containers.qdoc
+++ b/doc/src/containers.qdoc
@@ -682,7 +682,7 @@
     \header \o{1,2}          \o{2,1} Key lookup            \o{2,1} Insertion
     \header                  \o Average     \o Worst case  \o Average            \o Worst case
     \row    \o QMap<Key, T>  \o O(log \e n) \o O(log \e n) \o O(log \e n)        \o O(log \e n)
-    \row    \o QMultiMap<Key, T>  \o O((log \e n) \o O(log \e n) \o O(log \e n)   \o O(log \e n)
+    \row    \o QMultiMap<Key, T>  \o O(log \e n) \o O(log \e n) \o O(log \e n)   \o O(log \e n)
     \row    \o QHash<Key, T> \o Amort. O(1) \o O(\e n)     \o Amort. O(1)        \o O(\e n)
     \row    \o QSet<Key>     \o Amort. O(1) \o O(\e n)     \o Amort. O(1)        \o O(\e n)
     \endtable
diff --git a/doc/src/examples-overview.qdoc b/doc/src/examples-overview.qdoc
index 4313c43..3db4a45 100644
--- a/doc/src/examples-overview.qdoc
+++ b/doc/src/examples-overview.qdoc
@@ -238,6 +238,17 @@
   These examples demonstrate the basic techniques used to take advantage of
   OpenGL in Qt applications.
 
+  \section1 \l{Qt Examples#Multimedia}{Multimedia}
+
+  \l{Qt Examples#Multimedia}
+
+  Qt provides low-level audio support on linux,windows and mac platforms by default and
+  an audio plugin API to allow developers to implement there own audio support for
+  custom devices and platforms.
+
+  These examples demonstrate the basic techniques used to take advantage of
+  Audio API in Qt applications.
+
   \section1 \l{Qt Examples#SQL}{SQL}
 
   \l{Qt Examples#SQL}{\inlineimage sql-examples.png
diff --git a/doc/src/examples.qdoc b/doc/src/examples.qdoc
index e85acd1..7f9264b 100644
--- a/doc/src/examples.qdoc
+++ b/doc/src/examples.qdoc
@@ -255,6 +255,14 @@
     \o \l{phonon/musicplayer}{Music Player}\raisedaster
     \endlist
 
+    \section1 Multimedia
+
+    \list
+    \o \l{multimedia/audio/audiodevices}{Audio Devices}\raisedaster
+    \o \l{multimedia/audio/audiooutput}{Audio Output}\raisedaster
+    \o \l{multimedia/audio/audioinput}{Audio Input}\raisedaster
+    \endlist
+
     \section1 Qt Designer
 
     \list
@@ -322,6 +330,7 @@
     \o \l{statemachine/eventtransitions}{Event Transitions}\raisedaster
     \o \l{statemachine/factorial}{Factorial States}\raisedaster
     \o \l{statemachine/pingpong}{Ping Pong States}\raisedaster
+    \o \l{statemachine/rogue}{Rogue}\raisedaster
     \o \l{statemachine/trafficlight}{Traffic Light}\raisedaster
     \o \l{statemachine/twowaybutton}{Two-way Button}\raisedaster
     \endlist
diff --git a/doc/src/examples/audiodevices.qdoc b/doc/src/examples/audiodevices.qdoc
new file mode 100644
index 0000000..3b8cdd8
--- /dev/null
+++ b/doc/src/examples/audiodevices.qdoc
@@ -0,0 +1,54 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://www.qtsoftware.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example multimedia/audio/audiodevices
+    \title Audio Devices Example
+
+    The Audio Devices example demonstrates the basic use of QAudioDeviceInfo class
+    provided with Qt.
+
+    Qt provides the QAudioDeviceInfo class to enable audio querying within
+    a standard application user interface.
+
+    This example allows you to browse audio devices available and  try out different
+    configurations to see if they are supported.
+*/
diff --git a/doc/src/examples/audioinput.qdoc b/doc/src/examples/audioinput.qdoc
new file mode 100644
index 0000000..5dfe76e
--- /dev/null
+++ b/doc/src/examples/audioinput.qdoc
@@ -0,0 +1,54 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://www.qtsoftware.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example multimedia/audio/audioinput
+    \title AudioInput Example
+
+    The Audio Input example demonstrates the basic use of QAudioInput class
+    provided with Qt.
+
+    Qt provides the QAudioInput class to enable audio functionality within
+    a standard application user interface.
+
+    This example uses a fast-fourier transform on the input audio from the microphone
+    and displays the output.
+*/
diff --git a/doc/src/examples/audiooutput.qdoc b/doc/src/examples/audiooutput.qdoc
new file mode 100644
index 0000000..9c8a75f
--- /dev/null
+++ b/doc/src/examples/audiooutput.qdoc
@@ -0,0 +1,52 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://www.qtsoftware.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example multimedia/audio/audiooutput
+    \title Audio Output Example
+
+    The Audio Output example demonstrates the basic use of the QAudioOutput class
+    provided with Qt.
+
+    This example provides a tone generator to supply continuous audio playback.
+    The first button allows pause and resume of the playback.
+    The second button allows toggling between push and pull modes of operation.
+*/
diff --git a/doc/src/examples/rogue.qdoc b/doc/src/examples/rogue.qdoc
new file mode 100644
index 0000000..8fa2c69
--- /dev/null
+++ b/doc/src/examples/rogue.qdoc
@@ -0,0 +1,222 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://www.qtsoftware.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example statemachine/rogue
+    \title Rogue Example
+
+    The Rogue example shows how to use the Qt state machine for event
+    handling.
+
+    \image rogue-example.png
+
+    This example implements a simple text based game. Do you see the
+    \c{@} in the screenshot? That's you, the rogue. The \c{#}
+    characters are walls, and the dots represent floor. In a real
+    game, other ASCII characters would represent all kinds of objects
+    and creatures. For instance, ancient dragons (\c{D}'s) or food
+    rations (\c{%}'s). But let's not get carried away. In this game,
+    the rogue is simply running around in an empty room.
+
+    The rogue is moved with the keypad (2, 4, 8, 6). That aside, we
+    have implemented a \c quit command that triggers if the player
+    types \c {q}. The player is then asked if he/she really wants to
+    quit.
+
+    Most games have commands that need more than one key press and
+    that may require a different sequence of keys based on questions
+    asked the user. In this game, only the \c quit command falls under
+    this category, but for the sake of argument, let's imagine a
+    fully-fledged game with a rich set of commands. If we were to
+    implement these by catching key events in
+    \l{QWidget::}{keyPressEvent()}, we would have to keep a lot of
+    class member variables to track the sequence of keys already typed
+    (or find some other way of deducing the current state of a
+    command). This can easily lead to spaghetti, which is--as we all
+    well know, I'm sure--unpleasant. With a state machine, on the
+    other hand, separate states can wait for a single key press, and
+    that makes our lives a lot simpler.
+
+    The example consists of two classes:
+
+    \list
+        \o \c Window draws the text display of the game and sets
+            up the state machine. The window also has a status bar
+            above the area in which the rouge moves.
+        \o \c MovementTransition is a transition that carries out
+            a single move of the rogue.
+    \endlist
+
+    Before we embark on a code walkthrough, it is necessary to take a
+    closer look at the design of the machine. Here is a state chart
+    that shows what we want to achieve:
+
+    \image rogue-statechart.png
+
+    The input state waits for a key press to start a new command.
+    When receiving a key it recognizes, it transitions to one of the
+    two commands of the game; though, as we will see, movement is
+    handled by the transition itself. The quit state waits for the
+    player to answer yes or no (by typing \c y or \c n) when asked
+    whether he/she really wants to quit the game.
+
+    The chart demonstrates how we use one state to wait for a single
+    key press. The press received may trigger one of the transitions
+    connected to the state.
+
+    \section1 Window Class Definition
+
+    The \c Window class is a widget that draws the text display of the
+    game. It also sets up the state machine, i.e., creates and
+    connects the states in the machine. It is the key events from this
+    widget that are used by the machine.
+
+    \snippet examples/statemachine/rogue/window.h 0
+
+    \c Direction specifies the direction in which the rogue is to
+    move. We use this in \c movePlayer(), which moves the rogue and
+    repaints the window. The game has a status line above the area in
+    which the rogue moves. The \c status property contains the text of
+    this line. We use a property because the QState class allows
+    setting any Qt \l{Qt's Property System}{property} when entered.
+    More on this later.
+
+    \snippet examples/statemachine/rogue/window.h 1
+
+    The \c map is an array with the characters that are currently
+    displayed. We set up the array in \c setupMap(), and update it
+    when the rogue is moved. \c pX and \c pY is the current position
+    of the rogue. \c WIDTH and \c HEIGHT are macros specifying the
+    dimensions of the map.
+
+    The \c paintEvent() function is left out of this walkthrough. We
+    also do not discuss other code that does not concern the state
+    machine (the \c setupMap(), \c status(), \c setStatus(), \c
+    movePlayer(), and \c sizeHint() functions). If you wish to take a
+    look at the code, click on the link for the \c window.cpp file at
+    the top of this page.
+
+    \section1 Window Class Implementation
+
+    Here is the constructor of \c Window:
+
+    \snippet examples/statemachine/rogue/window.cpp 0
+    \dots
+    \snippet examples/statemachine/rogue/window.cpp 1
+
+    The player starts off at position (5, 5). We then set up the map
+    and statemachine. Let's proceed with the \c buildMachine()
+    function:
+
+    \snippet examples/statemachine/rogue/window.cpp 2
+
+    We enter \c inputState when the machine is started and from the \c
+    quitState if the user wants to continue playing. We then set the
+    status to a helpful reminder of how to play the game.
+
+    First, the \c Movement transition is added to the input state.
+    This will enable the rogue to be moved with the keypad.  Notice
+    that we don't set a target state for the movement transition. This
+    will cause the transition to be triggered (and the
+    \l{QAbstractTransition::}{onTransition()} function to be invoked),
+    but the machine will not leave the \c inputState. If we had set \c
+    inputState as the target state, we would first have left and then
+    entered the \c inputState again.
+
+    \snippet examples/statemachine/rogue/window.cpp 3
+
+    When we enter \c quitState, we update the status bar of the
+    window.
+    
+    \c QKeyEventTransition is a utility class that removes the hassle
+    of implementing transitions for \l{QKeyEvent}s. We simply need to
+    specify the key on which the transition should trigger and the
+    target state of the transition.
+
+    \snippet examples/statemachine/rogue/window.cpp 4
+
+    The transition from \c inputState allows triggering the quit state
+    when the player types \c {q}.
+    
+    \snippet examples/statemachine/rogue/window.cpp 5
+
+    The machine is set up, so it's time to start it.
+
+    \section1 The MovementTransition Class
+
+    \c MovementTransition is triggered when the player request the
+    rogue to be moved (by typing 2, 4, 6, or 8) when the machine is in
+    the \c inputState.
+
+    \snippet examples/statemachine/rogue/movementtransition.h 0
+
+    In the constructor, we tell QEventTransition to only send
+    \l{QEvent::}{KeyPress} events to the
+    \l{QAbstractTransition::}{eventTest()} function:
+
+    \snippet examples/statemachine/rogue/movementtransition.h 1
+
+    The KeyPress events come wrapped in \l{QWrappedEvent}s. \c event
+    must be confirmed to be a wrapped event because Qt uses other
+    events internally. After that, it is simply a matter of checking
+    which key has been pressed.
+
+    Let's move on to the \c onTransition() function:
+
+    \snippet examples/statemachine/rogue/movementtransition.h 2
+
+    When \c onTransition() is invoked, we know that we have a
+    \l{QEvent::}{KeyPress} event with 2, 4, 6, or 8, i.e., the event
+    is already unwrapped.
+
+    \section1 The Roguelike Tradition
+
+    You might have been wondering why the game features a rogue. Well,
+    these kinds of text based dungeon exploration games date back to a
+    game called, yes, "Rogue". Although outflanked by the technology
+    of modern 3D computer games, roguelikes have a solid community of
+    hard-core, devoted followers.
+
+    Playing these games can be surprisingly addictive (despite the
+    lack of graphics). Angband, the perhaps most well-known rougelike,
+    is found here: \l{http://rephial.org/}.
+*/
+
diff --git a/doc/src/images/rogue-example.png b/doc/src/images/rogue-example.png
new file mode 100644
index 0000000..7aeb0e5
--- /dev/null
+++ b/doc/src/images/rogue-example.png
diff --git a/doc/src/images/rogue-statechart.png b/doc/src/images/rogue-statechart.png
new file mode 100644
index 0000000..c5f4048
--- /dev/null
+++ b/doc/src/images/rogue-statechart.png
diff --git a/doc/src/qmake-manual.qdoc b/doc/src/qmake-manual.qdoc
index 0921ae7..211d7e9 100644
--- a/doc/src/qmake-manual.qdoc
+++ b/doc/src/qmake-manual.qdoc
@@ -558,7 +558,8 @@
     \o \c -makefile \BR
         \c qmake output will be a Makefile.
     \o \c -project \BR
-        \c qmake output will be a project file.
+        \c qmake output will be a project file. \BR
+\bold{Note:} It is likely that the created file will need to be edited for example adding the \c QT variable to suit what modules are required for the project.
     \endlist
 
     The following \c options are used to specify both general and mode-specific
diff --git a/doc/src/qsqldatatype-table.qdoc b/doc/src/qsqldatatype-table.qdoc
index 2055e6a..bc88c30 100644
--- a/doc/src/qsqldatatype-table.qdoc
+++ b/doc/src/qsqldatatype-table.qdoc
@@ -1,7 +1,7 @@
 /****************************************************************************
 **
 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
-** Contact: Qt Software Information (qt-info@nokia.com)
+** Contact: Nokia Corporation (qt-info@nokia.com)
 **
 ** This file is part of the documentation of the Qt Toolkit.
 **
diff --git a/doc/src/snippets/code/src_gui_image_qicon.cpp b/doc/src/snippets/code/src_gui_image_qicon.cpp
index 2b7c893..455fd84 100644
--- a/doc/src/snippets/code/src_gui_image_qicon.cpp
+++ b/doc/src/snippets/code/src_gui_image_qicon.cpp
@@ -20,3 +20,12 @@ void MyWidget::drawIcon(QPainter *painter, QPoint pos)
     painter->drawPixmap(pos, pixmap);
 }
 //! [2]
+
+//! [3]
+    QIcon undoicon = QIcon::fromTheme("edit-undo");
+//! [3]
+
+//! [4]
+    QIcon undoicon = QIcon::fromTheme("edit-undo", QIcon(":/undo.png"));
+//! [4]
+