Merge branch 'kinetic-declarativeui' of git@scm.dev.nokia.troll.no:qt/kinetic into kinetic-declarativeui

3 files changed, 175 insertions, 53 deletions

diff --git a/doc/src/declarative/focus.qdoc b/doc/src/declarative/focus.qdoc
index 8733b2d..ec6a02f 100644
--- a/doc/src/declarative/focus.qdoc
+++ b/doc/src/declarative/focus.qdoc
@@ -58,12 +58,14 @@ When the user presses or releases a key, the following occurs:
 \o The key event is delivered by the scene to the QML \l Item with \e {active focus}.  If no \l Item has \e {active focus}, the key event is \l {QEvent::ignore()}{ignored} and regular Qt key handling continues.
 \o If the QML \l Item with \e {active focus} accepts the key event, propagation stops.  Otherwise the event is "bubbled up", by recursively passing it to each \l Item's parent until either the event is accepted, or the root \l Item is reached.
 
-If the \c {Rectangle} element in the following example has active focus and the \e A key is pressed, it will bubble up to the \c {KeyActions}.  However, pressing the \e B key will bubble up to the root item and thus subsequently be \l {QEvent::ignore()}{ignored}.
+If the \c {Rectangle} element in the following example has active focus and the \e A key is pressed,
+it will bubble up to its parent.  However, pressing the \e B key will bubble up to the root
+item and thus subsequently be \l {QEvent::ignore()}{ignored}.
 
 \code
 Item {
-    KeyActions {
-        keyA: "print('Key A was pressed')"
+    Item {
+        Keys.onPressed: if (event.key == Qt.Key_A) { print('Key A was pressed'); event.accepted = true }
         Rectangle {}
     }
 }
@@ -91,8 +93,8 @@ An \l Item requests focus by setting the \c {Item::focus} property to true.
 
 For very simple cases simply setting the \c {Item::focus} property is sometimes
 sufficient.  If we run the following example in the \c qmlviewer, we see that
-the \c {KeyActions} element has \e {active focus} and pressing the
-\e A, \e B, or \e C keys modifies the text appropriately.
+the \c {keyHandler} element has \e {active focus} and pressing the 'A', 'B'
+or 'C' keys modifies the text appropriately.
 
 \table
 \row
@@ -100,11 +102,17 @@ the \c {KeyActions} element has \e {active focus} and pressing the
     Rectangle {
         color: "lightsteelblue"; width: 240; height: 25
         Text { id: myText }
-        KeyActions {
+        Item {
+            id: keyHandler
             focus: true
-            keyA: "myText.text = 'Key A was pressed'"
-            keyB: "myText.text = 'Key B was pressed'"
-            keyC: "myText.text = 'Key C was pressed'"
+            Keys.onPressed: {
+                if (event.key == Qt.Key_A)
+                    myText.text = 'Key A was pressed'
+                else if (event.key == Qt.Key_B)
+                    myText.text = 'Key B was pressed'
+                else if (event.key == Qt.Key_C)
+                    myText.text = 'Key C was pressed'
+            }
         }
     }
 \endcode
@@ -134,22 +142,34 @@ Rectangle {
     Rectangle {
         color: "lightsteelblue"; width: 240; height: 25
         Text { id: myText }
-        KeyActions {
+        Item {
+            id: keyHandler
             focus: true
-            keyA: "myText.text = 'Key A was pressed'"
-            keyB: "myText.text = 'Key B was pressed'"
-            keyC: "myText.text = 'Key C was pressed'"
+            Keys.onPressed: {
+                if (event.key == Qt.Key_A)
+                    myText.text = 'Key A was pressed'
+                else if (event.key == Qt.Key_B)
+                    myText.text = 'Key B was pressed'
+                else if (event.key == Qt.Key_C)
+                    myText.text = 'Key C was pressed'
+            }
         }
     }
     Rectangle {
         y: 30; focus: true
         color: "lightsteelblue"; width: 240; height: 25
         Text { id: myText }
-        KeyActions {
+        Item {
+            id: keyHandler
             focus: true
-            keyA: "myText.text = 'Key A was pressed'"
-            keyB: "myText.text = 'Key B was pressed'"
-            keyC: "myText.text = 'Key C was pressed'"
+            Keys.onPressed: {
+                if (event.key == Qt.Key_A)
+                    myText.text = 'Key A was pressed'
+                else if (event.key == Qt.Key_B)
+                    myText.text = 'Key B was pressed'
+                else if (event.key == Qt.Key_C)
+                    myText.text = 'Key C was pressed'
+            }
         }
     }
 }
@@ -166,9 +186,9 @@ of \c {Item::focus} in the other two instances is reverted back to false.  This
 is exactly the opposite of what was wanted!
 
 This problem is fundamentally one of visibility.  The \c {MyWidget}
-components each set their \c {KeyActions} as focused as that is all they can
+components each set their \c {keyHandler} Items as focused as that is all they can
 do - they don't know how they are going to be used, but they do know that when
-they're in use their \c {KeyActions} element is what needs focus.  Likewise
+they're in use their \c {keyHandler} element is what needs focus.  Likewise
 the code that uses the \c {MyWidget}'s sets the second \c {MyWidget} as
 focused because, while it doesn't know exactly how the \c {MyWidget} is
 implemented, it knows that it wants the second one to be focused.  No one piece
@@ -191,11 +211,17 @@ FocusScope {
     Rectangle {
         color: "lightsteelblue"; width: 240; height: 25
         Text { id: myText }
-        KeyActions {
+        Item {
+            id: keyHandler
             focus: true
-            keyA: "myText.text = 'Key A was pressed'"
-            keyB: "myText.text = 'Key B was pressed'"
-            keyC: "myText.text = 'Key C was pressed'"
+            Keys.onPressed: {
+                if (event.key == Qt.Key_A)
+                    myText.text = 'Key A was pressed'
+                else if (event.key == Qt.Key_B)
+                    myText.text = 'Key B was pressed'
+                else if (event.key == Qt.Key_C)
+                    myText.text = 'Key C was pressed'
+            }
         }
     }
 }
@@ -205,8 +231,11 @@ FocusScope {
 
 Conceptually \e {focus scopes} are quite simple.
 \list
-\o Within each \e {focus scope} one element may have \c {Item::focus} set to true.  If more than one \l Item has the \c {Item::focus} property set, the first is selected and the others are unset, just like when there are no \e {focus scopes}.
-\o When a \e {focus scope} receives \e {active focus}, the contained element with \c {Item::focus} set (if any) also gets \e {active focus}.  If this element is
+\o Within each \e {focus scope} one element may have \c {Item::focus} set to true.
+If more than one \l Item has the \c {Item::focus} property set, the first is selected
+and the others are unset, just like when there are no \e {focus scopes}.
+\o When a \e {focus scope} receives \e {active focus}, the contained element with
+\c {Item::focus} set (if any) also gets \e {active focus}.  If this element is
 also a \l FocusScope, the proxying behaviour continues.  Both the
 \e {focus scope} and the sub-focused item will have \c {Item::focus} set.
 \endlist
@@ -270,8 +299,11 @@ Rectangle {
         }
         delegate: FocusScope {
             width: contents.width; height: contents.height
-            Text { text: name }
-            KeyActions { return: "print(name)"; focus: true }
+            Text {
+                focus: true
+                text: name
+                Keys.onReturnPressed: print(name)
+            }
         }
     }
 }
@@ -285,7 +317,7 @@ property.  As the \l ListView is a \e {focus scope}, this doesn't effect the
 rest of the application.  However, if the \l ListView itself has
 \e {active focus} this causes the delegate itself to receive \e {active focus}.
 In this example, the root element of the delegate is also a \e {focus scope},
-which in turn gives \e {active focus} to the \c {KeyActions} element that
+which in turn gives \e {active focus} to the \c {Text} element that
 actually performs the work of handling the \e {Return} key.
 
 All of the QML view classes, such as \l PathView and \l GridView, behave
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
+
+
 */