doc/src/qtquick1/globalobject.qdoc

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