From 93ab98ae693c3a1d0b3b96c33543469f520145dd Mon Sep 17 00:00:00 2001 From: Bea Lam Date: Wed, 30 Jun 2010 11:56:06 +1000 Subject: Rewrite runtime & qmlviewer docs and emphasise that qmlviewer shouldn't be used for deployment Task-number: QTBUG-11287 --- doc/src/declarative/declarativeui.qdoc | 1 + doc/src/declarative/qmlruntime.qdoc | 275 +++++++++++++-------------------- doc/src/declarative/qmlviewer.qdoc | 234 ++++++++++++++++++++++++++++ 3 files changed, 345 insertions(+), 165 deletions(-) create mode 100644 doc/src/declarative/qmlviewer.qdoc 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_.qm", where 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 + #include + + 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 + #include + + 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_.qm", where 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 + +*/ + -- cgit v0.12