doc/src/declarative/network.qdoc

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