doc/src/declarative/globalobject.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 qdeclarativeglobalobject.html
  30 \title QML Global Object
  31
  32 Contains all the properties of the JavaScript global object, plus:
  33
  34 \tableofcontents
  35
  36 \section1 Qt Object
  37
  38 The \l{QmlGlobalQtObject}{Qt object} provides useful enums and functions from Qt, for use in all QML
  39 files.
  40
  41 \section1 XMLHttpRequest
  42
  43 \target XMLHttpRequest
  44
  45 QML script supports the XMLHttpRequest object, which can be used to asynchronously obtain
  46 data from over a network.
  47
  48 The XMLHttpRequest API implements the same \l {http://www.w3.org/TR/XMLHttpRequest/}{W3C standard}
  49 as many popular web browsers with following exceptions:
  50 \list
  51 \i QML's XMLHttpRequest does not enforce the same origin policy.
  52 \i QML's XMLHttpRequest does not support \e synchronous requests.
  53 \endlist
  54
  55 Additionally, the \c responseXML XML DOM tree currently supported by QML is a reduced subset
  56 of the \l {http://www.w3.org/TR/DOM-Level-3-Core/}{DOM Level 3 Core} API supported in a web
  57 browser.  The following objects and properties are supported by the QML implementation:
  58
  59 \table
  60 \header
  61 \o \bold {Node}
  62 \o \bold {Document}
  63 \o \bold {Element}
  64 \o \bold {Attr}
  65 \o \bold {CharacterData}
  66 \o \bold {Text}
  67
  68 \row
  69 \o
  70 \list
  71 \o nodeName
  72 \o nodeValue
  73 \o nodeType
  74 \o parentNode
  75 \o childNodes
  76 \o firstChild
  77 \o lastChild
  78 \o previousSibling
  79 \o nextSibling
  80 \o attributes
  81 \endlist
  82
  83 \o
  84 \list
  85 \o xmlVersion
  86 \o xmlEncoding
  87 \o xmlStandalone
  88 \o documentElement
  89 \endlist
  90
  91 \o
  92 \list
  93 \o tagName
  94 \endlist
  95
  96 \o
  97 \list
  98 \o name
  99 \o value
 100 \o ownerElement
 101 \endlist
 102
 103 \o
 104 \list
 105 \o data
 106 \o length
 107 \endlist
 108
 109 \o
 110 \list
 111 \o isElementContentWhitespace
 112 \o wholeText
 113 \endlist
 114
 115 \endtable
 116
 117 The \l{declarative/xml/xmlhttprequest}{XMLHttpRequest example} demonstrates how to
 118 use the XMLHttpRequest object to make a request and read the response headers.
 119
 120 \section1 Offline Storage API
 121
 122 \section2 Database API
 123
 124 The \c openDatabaseSync() and related functions
 125 provide the ability to access local offline storage in an SQL database.
 126
 127 These databases are user-specific and QML-specific, but accessible to all QML applications.
 128 They are stored in the \c Databases subdirectory
 129 of QDeclarativeEngine::offlineStoragePath(), currently as SQLite databases.
 130
 131 The API can be used from JavaScript functions in your QML:
 132
 133 \snippet declarative/sqllocalstorage/hello.qml 0
 134
 135 The API conforms to the Synchronous API of the HTML5 Web Database API,
 136 \link http://www.w3.org/TR/2009/WD-webdatabase-20091029/ W3C Working Draft 29 October 2009\endlink.
 137
 138 The \l{declarative/sqllocalstorage}{SQL Local Storage example} demonstrates the basics of
 139 using the Offline Storage API.
 140
 141 \section3 db = openDatabaseSync(identifier, version, description, estimated_size, callback(db))
 142
 143 Returns the database identified by \e identifier. If the database does not already exist, it
 144 is created, and the function \e callback is called with the database as a parameter. \e description
 145 and \e estimated_size are written to the INI file (described below), but are otherwise currently
 146 unused.
 147
 148 May throw exception with code property SQLException.DATABASE_ERR, or SQLException.VERSION_ERR.
 149
 150 When a database is first created, an INI file is also created specifying its characteristics:
 151
 152 \table
 153 \header \o \bold {Key} \o \bold {Value}
 154 \row \o Name \o The name of the database passed to \c openDatabase()
 155 \row \o Version \o The version of the database passed to \c openDatabase()
 156 \row \o Description \o The description of the database passed to \c openDatabase()
 157 \row \o EstimatedSize \o The estimated size (in bytes) of the database passed to \c openDatabase()
 158 \row \o Driver \o Currently "QSQLITE"
 159 \endtable
 160
 161 This data can be used by application tools.
 162
 163 \section3 db.changeVersion(from, to, callback(tx))
 164
 165 This method allows you to perform a \e{Scheme Upgrade}.
 166
 167 If the current version of \e db is not \e from, then an exception is thrown.
 168
 169 Otherwise, a database transaction is created and passed to \e callback. In this function,
 170 you can call \e executeSql on \e tx to upgrade the database.
 171
 172 May throw exception with code property SQLException.DATABASE_ERR or SQLException.UNKNOWN_ERR.
 173
 174 \section3 db.transaction(callback(tx))
 175
 176 This method creates a read/write transaction and passed to \e callback. In this function,
 177 you can call \e executeSql on \e tx to read and modify the database.
 178
 179 If the callback throws exceptions, the transaction is rolled back.
 180
 181 \section3 db.readTransaction(callback(tx))
 182
 183 This method creates a read-only transaction and passed to \e callback. In this function,
 184 you can call \e executeSql on \e tx to read the database (with SELECT statements).
 185
 186 \section3 results = tx.executeSql(statement, values)
 187
 188 This method executes a SQL \e statement, binding the list of \e values to SQL positional parameters ("?").
 189
 190 It returns a results object, with the following properties:
 191
 192 \table
 193 \header \o \bold {Type} \o \bold {Property} \o \bold {Value} \o \bold {Applicability}
 194 \row \o int \o rows.length \o The number of rows in the result \o SELECT
 195 \row \o var \o rows.item(i) \o Function that returns row \e i of the result \o SELECT
 196 \row \o int \o rowsAffected \o The number of rows affected by a modification \o UPDATE, DELETE
 197 \row \o string \o insertId \o The id of the row inserted \o INSERT
 198 \endtable
 199
 200 May throw exception with code property SQLException.DATABASE_ERR, SQLException.SYNTAX_ERR, or SQLException.UNKNOWN_ERR.
 201
 202 \section1 Logging
 203
 204 \c console.log() and \c console.debug() can be used to print information
 205 to the console. See \l{Debugging QML} for more information.
 206
 207 */