Rewrite runtime & qmlviewer docs and emphasise that qmlviewer shouldn't

be used for deployment

Task-number: QTBUG-11287

3 files changed, 345 insertions, 165 deletions

diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc
index f113147..4235c27 100644
--- a/doc/src/declarative/declarativeui.qdoc
+++ b/doc/src/declarative/declarativeui.qdoc
@@ -104,6 +104,7 @@ application or to build completely new applications.  QML is fully \l
 \o \l {QML Security}
 \o \l {QtDeclarative Module}
 \o \l {Debugging QML}
+\o \l {QML Viewer}
 \o \l {QML Performance}
 \o \l {QML Coding Conventions}
 \endlist
diff --git a/doc/src/declarative/qmlruntime.qdoc b/doc/src/declarative/qmlruntime.qdoc
index 15d8567..d44e774 100644
--- a/doc/src/declarative/qmlruntime.qdoc
+++ b/doc/src/declarative/qmlruntime.qdoc
@@ -26,172 +26,117 @@
 ****************************************************************************/
 
 /*!
-    \page qmlruntime.html
-    \title Qt Declarative UI Runtime
-    \keyword QML Viewer
-    \ingroup qttools
-
-    This page documents the \e{Declarative UI Runtime} for the Qt GUI
-    toolkit, and the \QQV which can be used to run apps
-    written for the runtime. The \QQV reads a declarative
-    user interface definition (\c .qml) file and displays the user interface it describes.
-
-    QML is a runtime, as you can run plain QML files which pull in their required modules.
-    To run apps with the QML runtime, you can either start the runtime
-    from your own application (using a QDeclarativeView) or with the simple \QQV.
-    The launcher can be installed in a production environment, assuming that it is not already
-    present in the system. It is generally packaged alongside Qt.
-
-    To deploy an application using the QML runtime, you have two options:
-
-    \list
-    \o Write your own Qt application including a QDeclarative view and deploy it the same as
-    any other Qt application (not discussed further on this page), or
-    \o Write a main QML file for your application, and run your application using the included \QQV.
-    \endlist
-
-    To run an application with the \QQV, pass the filename as an argument:
-
-    \code
-    qmlviewer myQmlFile.qml
-    \endcode
-
-    Deploying a QML application via the \QQV allows for QML only deployments, but can also
-    include custom C++ modules just as easily. Below is an example of how you might structure
-    a complex application deployed via the QML runtime, it is a listing of the files that would
-    be included in the deployment package.
-
-    \code
-    MyApp.qml
-    MyAppCore/qmldir
-    MyAppCore/libMyAppCore.so
-    MyAppCore/MyAppCore.dll
-    MyAppCore/AnAppElement.qml
-    MyAppCore/AnotherElement.qml
-    MyAppCore/images/Logo.png
-    OtherModule/qmldir
-    OtherModule/OtherElement.qml
-    \endcode
-
-    Note that this example is for deploying the example to both windows and linux. You will still need to compile the C++
-    modules for each target platform, but you can deploy multiple versions of the modules across platforms with different naming conventions,
-    as the appropriate module file is chosen based on platform naming conventions. The C++ 
-    modules must contain a QDeclarativeExtentionPlugin subclass.
-
-    The application would be executed either with your own application, the command 'qmlviewer MyApp.qml' or by
-    opening the file if your system has the \QQV registered as the handler for QML files. The MyApp.qml file would have access
-    to all of the deployed types using the import statements such as the following:
-
-    \code
-    import "MyAppCore"
-    import "OtherModule" 1.0 as Other
-    \endcode
-
-    \section1 Qt QML Viewer functionality
-    The \QQV implements some additional functionality to help it supporting
-    myriad applications. If you implement your own application, you may also wish to reimplement
-    some or all of this functionality. However, much of this functionality is intended to aid the prototyping of
-    QML applications and may not be necessary for a deployed application.
-
-    \section2 Options
-
-    When run with the \c -help option, \c qmlviewer shows available options.
-
-    \section2 Translations
-
-    When the launcher loads an initial QML file, it will install a translation file from
-    a "i18n" subdirectory relative to that initial QML file. The actual translation file
-    loaded will be according to the system locale and have the form
-    "qml_<language>.qm", where <language> is a two-letter ISO 639 language,
-    such as "qml_fr.qm", optionally followed by an underscore and an uppercase two-letter ISO 3166 country
-    code, such as "qml_fr_FR.qm" or "qml_fr_CA.qm".
-
-    Such files can be created using \l{Qt Linguist}.
-
-    See the \l{scripting.html#internationalization}{Qt Internationalization} documentation for information about how to make
-    the JavaScript in QML files use translatable strings.
-
-    Additionally, the launcher will load translation files specified on the
-    command line via the \c -translation option.
-
-    \section2 Dummy Data
-
-    The secondary use of the launcher is to allow QML files to be viewed with
-    dummy data. This is useful when prototyping the UI, as the dummy data can
-    be later replaced with actual data and bindings from a C++ plugin. 
-    To provide dummy data: create a directory called "dummydata" in the same directory as
-    the target QML file and create files there with the "qml" extension.
-    All such files will be loaded as QML objects and bound to the root
-    context as a property with the name of the file (without ".qml").
-
-    To replace this with real data, you simply bind the real object to 
-    the root context in C++.
-
-    For example, if the Qt application has a "clock.time" property
-    that is a qreal from 0 to 86400 representing the number of seconds since
-    midnight, dummy data for this could be provided by \c dummydata/clock.qml:
-    \code
-    QtObject { property real time: 12345 }
-    \endcode
-    Any QML can be used in the dummy data files. You could even animate the
-    fictional data!
-
-    \section2 Runtime Object
-
-    All applications using the launcher will have access to the \c runtime
-    property on the root context. This property contains several pieces of
-    information about the runtime environment of the application.
-
-    \section3 Screen Orientation
-
-    A special piece of dummy data which is integrated into the launcher is
-    a simple orientation property. The orientation can be set via the
-    settings menu in the application, or by pressing Ctrl+T to rotate it.
-
-    To use this from within your QML file, access \c runtime.orientation,
-    which can be one of the following values:
-
-    \list
-    \o \c Orientation.Portrait
-    \o \c Orientation.Landscape
-    \o \c Orientation.PortraitInverted (Portrait orientation, upside-down)
-    \o \c Orientation.LandscapeInverted (Landscape orientation, upside-down)
-    \endlist
-
-    These values can be bound to in your application. For example:
-
-    \code
-    Item {
-        state: (runtime.orientation == Orientation.Landscape) ? 'landscape' : ''
+\page qmlruntime.html
+\title Qt Declarative UI Runtime
+
+QML documents are loaded and executed by the QML runtime. This includes the 
+Declarative UI engine along with the built-in QML elements and plugin modules,
+and it also provides access to third-party QML elements and modules.
+
+Applications that use QML need to invoke the QML runtime in order to 
+execute QML documents. This can be done by creating a QDeclarativeView 
+or a QDeclarativeEngine, as described below. In addition, the Declarative UI 
+package includes the \QQV tool, which loads \c .qml files. This tool is
+useful for developing and testing QML code without the need to write
+a C++ application to load the QML runtime.
+
+
+
+\section1 Deploying QML-based applications
+
+To deploy an application that uses QML, the QML runtime must be invoked by 
+the application. This is done by writing a Qt C++ application that loads the
+QDeclarativeEngine by either:
+
+\list
+\o Loading the QML file through a QDeclarativeView instance, or
+\o Creating a QDeclarativeEngine instance and loading QML files with QDeclarativeComponent
+\endlist
+
+
+\section2 Deploying with QDeclarativeView
+
+QDeclarativeView is a QWidget-based class that is able to load QML files.
+For example, if there is a QML file, \c application.qml, like this:
+
+\qml
+    import Qt 4.7
+    
+    Rectangle { width: 100; height: 100; color: "red" }
+\endqml
+
+It can be loaded in a Qt application's \c main.cpp file like this:
+ 
+\code
+    #include <QApplication>
+    #include <QDeclarativeView>
+
+    int main(int argc, char *argv[])
+    {
+        QApplication app(argc, argv);
+
+        QDeclarativeView view;
+        view.setSource(QUrl::fromLocalFile("application.qml"));
+        view.show();
+
+        return app.exec();
     }
-    \endcode
-
-    This allows your application to respond to changes in the screen's orientation. The launcher
-    will automatically update this on some platforms (currently the N900 only) to match the physical
-    screen's orientation. On other plaforms orientation changes will only happen when explictly asked for.
-
-    \section3 Window Active
-
-    The \c runtime.isActiveWindow property tells whether the main window of the launcher is currently active
-    or not. This is especially useful for embedded devices when you want to pause parts of your application,
-    including animations, when your application loses focus or goes to the background.
-
-    The example below, stops the animation when the application's window is deactivated and resumes on activation:
-
-    \code
-    Item {
-        width: 300; height: 200
-        Rectangle {
-            width: 100; height: 100
-            color: "green"
-            SequentialAnimation on x {
-                running: runtime.isActiveWindow
-                loops: Animation.Infinite
-                NumberAnimation {to: 200}
-                NumberAnimation {to: 0}
-            }
-        }
+\endcode
+       
+This creates a QWidget-based view that displays the contents of 
+\c application.qml.
+ 
+The application's \c .pro \l{qmake Project Files}{project file} must specify
+the \c declarative module for the \c QT variable. For example:
+
+\code
+    TEMPLATE += app
+    QT += gui declarative
+    SOURCES += main.cpp
+\endcode
+
+
+\section2 Creating a QDeclarativeEngine directly
+     
+If \c application.qml does not have any graphical components, or if it is 
+preferred to avoid QDeclarativeView for other reasons, the QDeclarativeEngine
+can be constructed directly instead. In this case, \c application.qml is
+loaded as a QDeclarativeComponent instance rather than placed into a view:
+
+\code
+    #include <QCoreApplication>
+    #include <QDeclarativeEngine>    
+
+    int main(int argc, char *argv[])
+    {
+        QCoreApplication app(argc, argv);
+    
+        QDeclarativeEngine engine;
+        QDeclarativeContext *windowContext = new QDeclarativeContext(engine.rootContext());
+    
+        QDeclarativeComponent component(&engine, "application.qml");
+        QObject *window = component.create(windowContext);
+         
+        // ... delete window and windowContext when necessary
+    
+        return app.exec();
     }
-    \endcode
+\endcode
+
+See \l {Using QML in C++ Applications} for more information about using 
+QDeclarativeEngine, QDeclarativeContext and QDeclarativeComponent, as well 
+as details on including QML files through \l{The Qt Resource System}{Qt's Resource system}.
+
+
+
+\section1 Developing and prototyping with QML Viewer
+
+The Declarative UI package includes a QML runtime tool, the \QQV, which loads
+and displays QML documents. This is useful during the application development
+phase for prototyping QML-based applications without writing your own C++ 
+applications to invoke the QML runtime. 
+
+See the \l{QML Viewer} documentation for more details.
 
 */
+
diff --git a/doc/src/declarative/qmlviewer.qdoc b/doc/src/declarative/qmlviewer.qdoc
new file mode 100644
index 0000000..efff9cc
--- /dev/null
+++ b/doc/src/declarative/qmlviewer.qdoc
@@ -0,0 +1,234 @@
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+
+\page qmlviewer.html
+\title QML Viewer
+\ingroup qttools
+
+The Declarative UI package includes \QQV, a tool for loading QML documents that 
+makes it easy to quickly develop and debug QML applications. It invokes the QML 
+runtime to load QML documents and also includes additional features useful for 
+the development of QML-based applications.
+
+The QML Viewer is a tool for testing and developing QML applications. It is 
+\e not intended for use in a production environment and should not be used for the 
+deployment of QML applications. In those cases, the QML runtime should be invoked
+from a Qt application instead; see \l {Qt Declarative UI Runtime} for more
+information.
+
+The viewer is located at QTDIR/bin/qmlviewer. To load a \c .qml file
+with the viewer, run the viewer and select the file to be opened, or provide the 
+file path on the command line:
+
+\code
+    qmlviewer myqmlfile.qml
+\endcode
+    
+On Mac OS X, the QML Viewer application is named \c QMLViewer.app instead. You
+can launch the viewer by opening the QMLViewer application from the Finder, or 
+from the command line:
+
+\code
+    QMLViewer.app/Contents/MacOS/QMLViewer myqmlfile.qml
+\endcode
+
+The QML Viewer has a number of configuration options involving features such as 
+fullscreen display, module import path configurations, video recording of QML
+animations, and OpenGL support.
+
+To see the configuration options, run \c qmlviewer with the \c -help argument.
+
+
+\section1 Adding module import paths
+
+Additional module import paths can be provided using the \c -I flag.
+For example, the \l{declarative/cppextensions/plugins}{QML plugins example} creates 
+a C++ plugin identified as \c com.nokia.TimeExample. Since this has a namespaced
+identifier, the viewer has to be run with the \c -I flag from the example's
+base directory:
+
+\code
+qmlviewer -I . plugins.qml
+\endcode
+
+This adds the current directory to the import path so that the viewer will
+find the plugin in the \c com/nokia/TimeExample directory.
+
+Note by default, the current directory is included in the import search path,
+but namespaced modules like \c com.nokia.TimeExample are not found unless
+the path is explicitly added.
+
+
+\section1 Loading translation files
+
+When the QML Viewer loads a QML file, it installs a translation file from a 
+"i18n" subdirectory relative to that initial file. This directory should contain 
+translation files named "qml_<language>.qm", where <language> is a two-letter
+ISO 639 language, such as "qml_fr.qm", optionally followed by an underscore and
+an uppercase two-letter ISO 3166 country code, such as "qml_fr_FR.qm" or
+"qml_fr_CA.qm". 
+
+Such files can be created using \l {Qt Linguist}.
+
+The actual translation file that is loaded depends on the system locale. 
+Additionally, the viewer will load any translation files specified on the command
+line via the \c -translation option.
+
+See the \l{declarative/i18n}{QML i18n example} for an example. Also, the
+\l{scripting.html#internationalization}{Qt Internationalization} documentation
+shows how JavaScript code in QML files can be made to use translatable strings.
+
+
+\section1 Loading placeholder data with QML Viewer
+
+Often, QML applications are prototyped with fake data that is later replaced
+by real data sources from C++ plugins. QML Viewer assists in this aspect by
+loading fake data into the application context: it looks for a directory named
+"dummydata" in the same directory as the target QML file, and any \c .qml 
+files in that directory are loaded as QML objects and bound to the root context
+as properties named after the files.
+
+For example, this QML document refers to a \c lottoNumbers property which does
+not actually exist within the document:
+
+\qml
+import Qt 4.7
+
+ListView {
+    width: 200; height: 300
+    model: lottoNumbers
+    delegate: Text { text: number }
+}        
+\endqml
+
+If within the document's directory, there is a "dummydata" directory which
+contains a \c lottoNumbers.qml file like this:
+
+\qml
+import Qt 4.7
+
+ListModel {
+    ListElement { number: 23 }
+    ListElement { number: 44 }
+    ListElement { number: 78 }
+}
+\endqml
+
+Then this model would be automatically loaded into the ListView in the previous document.
+
+Child properties are included when loaded from dummy data. The following document
+refers to a \c clock.time property:
+
+\qml
+import Qt 4.7    
+Text { text: clock.time }
+\endqml
+    
+The text value could be filled by a \c dummydata/clock.qml file with a \c time
+property in the root context:
+
+\qml
+import Qt 4.7    
+QtObject { property int time: 54321 }
+\endqml
+
+To replace this with real data, you can simply bind the real data object to
+the root context in C++ using QDeclarativeContext::setContextProperty(). This
+is detailed in \l {Using QML in C++ Applications}.
+
+\section1 Using the \c runtime object
+
+QML applications that are loaded with the QML Viewer have access to a special
+\c runtime property on the root context. This property provides additional 
+information about the application's runtime environment through the following properties:
+
+\table
+\row 
+
+\o \c runtime.isActiveWindow
+
+\o This property indicates whether the QML Viewer window is the current active
+window on the system. It is useful for "pausing" an application, particularly
+animations, when the QML Viewer loses focus or moves to the background.
+
+For example, the following animation is only played when the QML Viewer is 
+the active window:
+    
+\qml
+Rectangle {
+    width: 200; height: 200
+
+    ColorAnimation on color {
+        running: runtime.isActiveWindow
+        loops: Animation.Infinite
+        from: "green"; to: "blue"; duration: 2000
+    }
+}
+\endqml
+
+\row
+
+\o \c runtime.orientation
+
+\o This property indicates the current orientation of the QML Viewer. On the
+N900 platform, this property automatically updates to reflect the device's 
+actual orientation; on other platforms, this indicates the orientation currently
+selected in the QML Viewer's \e {Settings -> Properties} menu. The
+\c orientation value can be one of the following:
+
+\list
+\o \c Orientation.Portrait
+\o \c Orientation.Landscape
+\o \c Orientation.PortraitInverted (Portrait orientation, upside-down)
+\o \c Orientation.LandscapeInverted (Landscape orientation, upside-down)
+\endlist
+
+When the viewer's orientation changes, the appearance of the loaded QML document
+does not change unless it has been set to respond to changes in 
+\c runtime.orientation. For example, the following Rectangle changes its
+aspect ratio depending on the orientation of the QML Viewer:
+
+\qml
+Rectangle {
+    id: window
+    width: 640; height: 480
+            
+    states: State {
+        name: "landscape"
+        PropertyChanges { target: window; width: 480; height: 640 }
+    }
+    state: (runtime.orientation == Orientation.Landscape 
+            || runtime.orientation == Orientation.LandscapeInverted) ? 'landscape' : ''
+}
+\endqml
+
+\endtable
+
+*/
+