doc/src/declarative/network.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Free Documentation License
  17 ** Alternatively, this file may be used under the terms of the GNU Free
  18 ** Documentation License version 1.3 as published by the Free Software
  19 ** Foundation and appearing in the file included in the packaging of this
  20 ** file.
  21 **
  22 ** If you have questions regarding the use of this file, please contact
  23 ** Nokia at qt-info@nokia.com.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qdeclarativenetwork.html
  30 \ingroup qml-features
  31 \previouspage {Dynamic Object Management in QML}{Dynamic Object Management}
  32 \nextpage {QML Internationalization}{Internationalization}
  33 \contentspage QML Features
  34 \title Network Transparency
  35
  36 QML supports network transparency by using URLs (rather than file names) for all
  37 references from a QML document to other content:
  38
  39 \qml
  40 Image {
  41     source: "http://www.example.com/images/logo.png"
  42 }
  43 \endqml
  44
  45 Since a \e relative URL is the same
  46 as a relative file, development of QML on regular file systems remains simple:
  47
  48 \qml
  49 Image {
  50     source: "images/logo.png"
  51 }
  52 \endqml
  53
  54 Network transparency is supported throughout QML, for example:
  55
  56 \list
  57 \o Fonts - the \c source property of FontLoader is a URL
  58 \o WebViews - the \c url property of WebView (obviously!)
  59 \endlist
  60
  61 Even QML types themselves can be on the network - if the \l {QML Viewer} is used to load
  62 \tt http://example.com/mystuff/Hello.qml and that content refers to a type "World", the engine
  63 will load \tt http://example.com/mystuff/qmldir and resolve the type just as it would for a local file.
  64 For example if the qmldir file contains the line "World World.qml", it will load
  65 \tt http://example.com/mystuff/World.qml
  66 Any other resources that \tt Hello.qml referred to, usually by a relative URL, would
  67 similarly be loaded from the network.
  68
  69
  70 \section1 Relative vs. Absolute URLs
  71
  72 Whenever an object has a property of type URL (QUrl), assigning a string to that
  73 property will actually assign an absolute URL - by resolving the string against
  74 the URL of the document where the string is used.
  75
  76 For example, consider this content in \tt{http://example.com/mystuff/test.qml}:
  77
  78 \qml
  79 Image {
  80     source: "images/logo.png"
  81 }
  82 \endqml
  83
  84 The \l Image source property will be assigned \tt{http://example.com/mystuff/images/logo.png},
  85 but while the QML is being developed, in say \tt C:\\User\\Fred\\Documents\\MyStuff\\test.qml, it will be assigned
  86 \tt C:\\User\\Fred\\Documents\\MyStuff\\images\\logo.png.
  87
  88 If the string assigned to a URL is already an absolute URL, then "resolving" does
  89 not change it and the URL is assigned directly.
  90
  91
  92 \section1 Progressive Loading
  93
  94 Because of the declarative nature of QML and the asynchronous nature of network resources,
  95 objects which reference network resource generally change state as the network resource loads.
  96 For example, an Image with a network source will initially have
  97 a \c width and \c height of 0, a \c status of \c Loading, and a \c progress of 0.0.
  98 While the content loads, the \c progress will increase until
  99 the content is fully loaded from the network,
 100 at which point the \c width and \c height become the content size, the \c status becomes \c Ready, and the \c progress reaches 1.0.
 101 Applications can bind to these changing states to provide visual progress indicators where appropriate, or simply
 102 bind to the \c width and \c height as if the content was a local file, adapting as those bound values change.
 103
 104 Note that when objects reference local files they immediately have the \c Ready status, but applications wishing
 105 to remain network transparent should not rely on this. Future versions of QML may also use asynchronous local file I/O
 106 to improve performance.
 107
 108
 109 \section1 Accessing Network Services
 110
 111 QML types such as XmlListModel, and JavaScript classes like XMLHttpRequest are intended
 112 entirely for accessing network services, which usually respond with references to
 113 content by URLs that can then be used directly in QML. For example, using these facilities
 114 to access an on-line photography service would provide the QML application with URLs to
 115 photographs, which can be directly set on an \l Image \c source property.
 116
 117 See the \tt demos/declarative/flickr for a real demonstration of this.
 118
 119
 120 \section1 Configuring the Network Access Manager
 121
 122 All network access from QML is managed by a QNetworkAccessManager set on the QDeclarativeEngine which executes the QML.
 123 By default, this is an unmodified Qt QNetworkAccessManager. You may set a different manager by
 124 providing a QDeclarativeNetworkAccessManagerFactory and setting it via
 125 QDeclarativeEngine::setNetworkAccessManagerFactory().
 126 For example, the \l {QML Viewer} sets a QDeclarativeNetworkAccessManagerFactory which
 127 creates QNetworkAccessManager that trusts HTTP Expiry headers to avoid network cache checks,
 128 allows HTTP Pipelining, adds a persistent HTTP CookieJar, a simple disk cache, and supports proxy settings.
 129
 130
 131 \section1 QRC Resources
 132
 133 One of the URL schemes built into Qt is the "qrc" scheme. This allows content to be compiled into
 134 the executable using \l{The Qt Resource System}. Using this, an executable can reference QML content
 135 that is compiled into the executable:
 136
 137 \code
 138     QDeclarativeView *canvas = new QDeclarativeView;
 139     canvas->setUrl(QUrl("qrc:/dial.qml"));
 140 \endcode
 141
 142 The content itself can then use relative URLs, and so be transparently unaware that the content is
 143 compiled into the executable.
 144
 145
 146 \section1 Limitations
 147
 148 The \c import statement is only network transparent if it has an "as" clause.
 149
 150 More specifically:
 151 \list
 152 \o \c{import "dir"} only works on local file systems
 153 \o \c{import libraryUri} only works on local file systems
 154 \o \c{import "dir" as D} works network transparently
 155 \o \c{import libraryUrl as U} works network transparently
 156 \endlist
 157
 158
 159 */