1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information (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 either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** 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.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at qt-sales@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qmlnetwork.html
\title Network Transparency
QML supports network transparency by using URLs (rather than file names) for all
references from a QML document to other content. Since a \i relative URL is the same
as a relative file, development of QML on regular file systems remains simple.
\section1 Accessing Network Resources from QML
Whenever an object has a property of type URL (QUrl), assigning a string to that
property will actually assign an absolute URL - by resolving the string against
the URL of the document where the string is used.
For example, consider this content in \c{http://example.com/mystuff/test.qml}:
\code
Image {
source: "images/logo.png"
}
\endcode
The \l Image source property will be assigned \c{http://example.com/mystuff/images/logo.png},
but while the QML is being developed, in say \c C:\User\Fred\Documents\MyStuff\test.qml, it will be assigned
\c C:\User\Fred\Documents\MyStuff\images\logo.png.
Network transparency is supported throughout QML:
\list
\o Types - if the \c test.qml file above used "Hello { }", that would refer to \c http://example.com/mystuff/Hello.qml
\o Scripts - the \c source property of \l Script is a URL
\o Images - the \c source property of \l Image and similar types is a URL
\o Fonts - the \c source property of FontLoader is a URL
\o WebViews - the \c url property of WebView may be assigned a relative URL string
\endlist
Because of the declarative nature of QML and the asynchronous nature of network resources,
objects which reference network resource generally change state as the network resource loads.
For example, an Image with a network source will initially have
a \c width and \c height of 0, a \c status of \c Loading, and a \c progress of 0.0.
While the content loads, the \c progress will increase until
the content is fully loaded from the network,
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.
Applications can bind to these changing states to provide visual progress indicators where appropriate, or simply
bind to the \c width and \c height as if the content was a local file, adapting as those bound values change.
Note that when objects reference local files they immediately have the \c Ready status, but applications wishing
to remain network transparent should not rely on this. Future versions of QML may also use asynchronous local file I/O
to improve performance.
\section1 Limitations
The \c import statement only works network transparently if it has an "as" clause.
\list
\o \c{import "dir"} only works on local file systems
\o \c{import libraryUri} only works on local file systems
\o \c{import "dir" as D} works network transparently
\o \c{import libraryUrl as U} works network transparently
\endlist
\section1 Configuring the Network Access Manager
All network access from QML is managed by a QNetworkAccessManager set on the QmlEngine which executes the QML.
By default, this is an unmodified Qt QNetworkAccessManager. You may set a different manager using
QmlEngine::setNetworkAccessManager() as appropriate for the policies of your application.
For example, the \l qmlviewer tool sets a new QNetworkAccessManager which
trusts HTTP Expiry headers to avoid network cache checks, allows HTTP Pipelining, adds a persistent HTTP CookieJar,
a simple disk cache, and supports proxy settings.
\section1 QRC Resources
One of the URL schemes built into Qt is the "qrc" scheme. This allows content to be compiled into
the executable using \l{The Qt Resource System}. Using this, an executable can reference QML content
that is compiled into the executable:
\code
QmlView *canvas = new QmlView;
canvas->setUrl(QUrl("qrc:/dial.qml"));
\endcode
The content itself can then use relative URLs, and so be transparently unaware that the content is
compiled into the executable.
*/
|
