diff options
Diffstat (limited to 'doc/src/declarative/qmlruntime.qdoc')
| -rw-r--r-- | doc/src/declarative/qmlruntime.qdoc | 161 |
1 files changed, 161 insertions, 0 deletions
diff --git a/doc/src/declarative/qmlruntime.qdoc b/doc/src/declarative/qmlruntime.qdoc new file mode 100644 index 0000000..8bb3ec7 --- /dev/null +++ b/doc/src/declarative/qmlruntime.qdoc @@ -0,0 +1,161 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \page qmlruntime.html + \title Qt Declarative UI Runtime + \keyword qml runtime + \ingroup qttools + + This page documents the \e{Declarative UI Runtime} for the Qt GUI + toolkit, and the \c qml executable which can be used to run apps + written for the runtime. The \c qml executable 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 on application (using a QDeclarativeView) or with the simple \c qml application. + The \c qml application 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 \c qml tool. + \endlist + + To run an application with the \c qml tool, pass the filename as an argument: + + \code + qml myQmlFile.qml + \endcode + + Deploying a QML application via the \c qml executable 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 'qml MyApp.qml' or by + opening the qml file if your system has the \c qml executable 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 \c qml application functionality + The \c qml application implements some additional functionality to help it serve the role of a launcher + for myriad applications. If you implement your own launcher 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, qml shows available options. + + \section2 Dummy Data + + The secondary use of the qml runtime 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 Screen Orientation + + A special piece of dummy data which is integrated into the runtime is + a simple orientation property. The orientation can be set via the + settings menu in the application, or by pressing Ctrl+T to toggle it. + + To use this from within your QML file, import QDeclarativeViewer 1.0 and create a + Screen object. This object has a property, orientation, which can be either + Screen.Landscape or Screen.Portrait and which can be bound to in your + application. An example is below: + +\code + import QDeclarativeViewer 1.0 as QDeclarativeViewer + + Item { + QDeclarativeViewer.Screen { id: screen } + state: (screen.orientation == QDeclarativeViewer.Screen.Landscape) ? 'landscape' : '' + } +\endcode + + This allows your application to respond to the orientation of the screen changing. The runtime + 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. + +*/ |