doc

QT-2324
QT-2306

2 files changed, 115 insertions, 25 deletions

diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc
index 18bcd69..2328c8a 100644
--- a/doc/src/declarative/globalobject.qdoc
+++ b/doc/src/declarative/globalobject.qdoc
@@ -60,4 +60,54 @@ Contains all the properties of the ECMAScript global object, plus:
 
 \section1 Offline Storage API
 
+The \c openDatabase() and related functions
+provide the ability to access local offline storage in an SQL database.
+
+These databases are user-specific and QML-specific. They are stored in the \c Databases subdirectory
+of QmlEngine::offlineStoragePath(), currently as SQLite databases.
+
+The API is based on the HTML5 offline storage SQL draft API. The main difference is that this QML
+API is currently synchronous. You should avoid relying on synchronicity to make your scripts more
+portable, both to/from HTML5 and to future QML versions.
+
+The API can be used from JavaScript functions in your QML:
+
+\quotefile declarative/sql/hello.qml
+
+\section2 DbObject openDatabase(string name, string version, string description, int estimatedsize)
+
+Opens a database identified by the given \c name and \c version.
+If a database with this name and version does not exist, it is created. The \c version should
+always be "1.0" until schema upgrade semantics are defined.
+
+The \c description and \c estimatedsize are provided to allow application tools to give the user
+control over the databases created, but are otherwise not used by QML.
+
+The returned DbObject has a \c transaction() method by which SQL transactions can be done.
+
+When a database is first created, an INI file is also created specifying its characteristics:
+
+\table
+\header \o \bold {Key} \o \bold {Value}
+\row \o Name \o The name of the database passed to \c openDatabase()
+\row \o Version \o The version of the database passed to \c openDatabase()
+\row \o Description \o The description of the database passed to \c openDatabase()
+\row \o EstimatedSize \o The estimated size of the database passed to \c openDatabase()
+\row \o DbType \o Currently "QSQLITE"
+\endtable
+
+This data can be used by application tools.
+
+
+\section2 void DbObject::transaction(function usesql(DbTxObject), function errorcb=0, function successcb=0)
+
+Executes \c usesql() in a database transaction. The \c DbTxObject object has a \c executeSql() method by which the
+code of \c usesql can execute SQL. The optional second and third arguments are an error callback and success
+callback respectively (note that the order of these is the opposite to DbTxObject::executeSql()).
+
+\section2 void DbTxObject::executeSql(string sql, function successcb=0, function errorcb=0)
+
+Executes \c sql as an SQL block. The optional second and third arguments are a success callback and error
+callback respectively (note that the order of these is the opposite to DbObject::transaction()).
+
 */
diff --git a/doc/src/declarative/network.qdoc b/doc/src/declarative/network.qdoc
index e88dfdc..a81eb0f 100644
--- a/doc/src/declarative/network.qdoc
+++ b/doc/src/declarative/network.qdoc
@@ -44,36 +44,61 @@
 \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.
+references from a QML document to other content:
+
+\qml
+Image {
+    source: "http://www.example.com/images/logo.png"
+}
+\endqml
+
+Since a \e relative URL is the same
+as a relative file, development of QML on regular file systems remains simple:
+
+\qml
+Image {
+    source: "images/logo.png"
+}
+\endqml
+
+Network transparency is supported throughout QML, for example:
+
+\list
+\o Scripts - the \c source property of \l Script is a URL
+\o Fonts - the \c source property of FontLoader is a URL
+\o WebViews - the \c url property of WebView (obviously!)
+\endlist
+
+Even QML types themselves can be on the network - if \l qmlviewer is used to load
+\tt http://example.com/mystuff/Hello.qml and that content refers to a type "World", this
+will load from \tt http://example.com/mystuff/World.qml just as it would for a local file.
+Any other resources that \tt Hello.qml referred to, usually by a relative URL, would
+similarly be loaded from the network.
 
-\section1 Accessing Network Resources from QML
+
+\section1 Relative vs. Absolute URLs
 
 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}:
+For example, consider this content in \tt{http://example.com/mystuff/test.qml}:
 
-\code
+\qml
 Image {
     source: "images/logo.png"
 }
-\endcode
+\endqml
 
-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.
+The \l Image source property will be assigned \tt{http://example.com/mystuff/images/logo.png},
+but while the QML is being developed, in say \tt C:\User\Fred\Documents\MyStuff\test.qml, it will be assigned
+\tt C:\User\Fred\Documents\MyStuff\images\logo.png.
 
-Network transparency is supported throughout QML:
+If the string assigned to a URL is already an absolute URL, then "resolving" does
+not change it and the URL is assigned directly.
 
-\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
+
+\section1 Progressive Loading
 
 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.
@@ -89,16 +114,17 @@ Note that when objects reference local files they immediately have the \c Ready
 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.
+\section1 Accessing Network Services
+
+QML types such as XmlListModel, and JavaScript classes like XMLHttpRequest are intended
+entirely for accessing network services, which usually respond with references to
+content by URLs that can then be used directly in QML. For example, using these facilities
+to access an on-line photography service would provide the QML application with URLs to
+photographs, which can be directly set on an \l Image \c source property.
+
+See the \tt demos/declarative/flickr for a real demonstration of this.
 
-\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
 
@@ -109,6 +135,7 @@ 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
@@ -123,4 +150,17 @@ that is compiled into the executable:
 The content itself can then use relative URLs, and so be transparently unaware that the content is
 compiled into the executable.
 
+
+\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
+
+
 */