<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- plugin.cpp -->
<title>Qt Quick Local Storage QML Types | Qt Quick 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.9</td><td ><a href="qtquick-index.html">Qt Quick</a></td><td >Qt Quick Local Storage QML Types</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#methods">Methods</a></li>
<li class="level1"><a href="#detailed-description">Detailed Description</a></li>
<li class="level1"><a href="#method-documentation">Method Documentation</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt Quick Local Storage QML Types</h1>
<span class="subtitle"></span>
<!-- $$$QtQuick.LocalStorage-description -->
<div class="descr"> <a name="details"></a>
<p>This is a singleton type for reading and writing to SQLite databases.</p>
<a name="methods"></a>
<h2 id="methods">Methods</h2>
<ul>
<li>object <b><a href="qtquick-localstorage-qmlmodule.html#opendatabasesync">openDatabaseSync</a></b>(string name, string version, string description, int estimated_size, jsobject callback(db))</li>
</ul>
<a name="detailed-description"></a>
<h2 id="detailed-description">Detailed Description</h2>
<p>To use the types in this module, import the module and call the relevant functions using the <code>LocalStorage</code> type:</p>
<pre class="cpp">
import <span class="type"><a href="qtquick-qmlmodule.html">QtQuick</a></span><span class="operator">.</span>LocalStorage <span class="number">2.0</span>
import <span class="type"><a href="qtquick-qmlmodule.html">QtQuick</a></span> <span class="number">2.0</span>
Item {
Component<span class="operator">.</span>onCompleted: {
var db <span class="operator">=</span> LocalStorage<span class="operator">.</span>openDatabaseSync(<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>)
}
}
</pre>
<p>These databases are user-specific and QML-specific, but accessible to all QML applications. They are stored in the <code>Databases</code> subdirectory of QQmlEngine::offlineStoragePath(), currently as SQLite databases.</p>
<p>Database connections are automatically closed during Javascript garbage collection.</p>
<p>The API can be used from JavaScript functions in your QML:</p>
<pre class="qml">
import QtQuick 2.0
<span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
<span class="name">color</span>: <span class="string">"white"</span>
<span class="name">width</span>: <span class="number">200</span>
<span class="name">height</span>: <span class="number">100</span>
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> {
<span class="name">text</span>: <span class="string">"?"</span>
<span class="name">anchors</span>.horizontalCenter: <span class="name">parent</span>.<span class="name">horizontalCenter</span>
<span class="keyword">function</span> <span class="name">findGreetings</span>() {
var <span class="name">db</span> = <span class="name">openDatabaseSync</span>(<span class="string">"QDeclarativeExampleDB"</span>, <span class="string">"1.0"</span>, <span class="string">"The Example QML SQL!"</span>, <span class="number">1000000</span>);
<span class="name">db</span>.<span class="name">transaction</span>(
<span class="keyword">function</span>(<span class="name">tx</span>) {
<span class="comment">// Create the database if it doesn't already exist</span>
<span class="name">tx</span>.<span class="name">executeSql</span>(<span class="string">'CREATE TABLE IF NOT EXISTS Greeting(salutation TEXT, salutee TEXT)'</span>);
<span class="comment">// Add (another) greeting row</span>
<span class="name">tx</span>.<span class="name">executeSql</span>(<span class="string">'INSERT INTO Greeting VALUES(?, ?)'</span>, [ <span class="string">'hello'</span>, <span class="string">'world'</span> ]);
<span class="comment">// Show all added greetings</span>
var <span class="name">rs</span> = <span class="name">tx</span>.<span class="name">executeSql</span>(<span class="string">'SELECT * FROM Greeting'</span>);
var <span class="name">r</span> = <span class="string">""</span>
<span class="keyword">for</span> (<span class="keyword">var</span> <span class="name">i</span> = <span class="number">0</span>; <span class="name">i</span> <span class="operator"><</span> <span class="name">rs</span>.<span class="name">rows</span>.<span class="name">length</span>; i++) {
<span class="name">r</span> <span class="operator">+=</span> <span class="name">rs</span>.<span class="name">rows</span>.<span class="name">item</span>(<span class="name">i</span>).<span class="name">salutation</span> <span class="operator">+</span> <span class="string">", "</span> <span class="operator">+</span> <span class="name">rs</span>.<span class="name">rows</span>.<span class="name">item</span>(<span class="name">i</span>).<span class="name">salutee</span> <span class="operator">+</span> <span class="string">"\n"</span>
}
<span class="name">text</span> <span class="operator">=</span> <span class="name">r</span>
}
)
}
<span class="name">Component</span>.onCompleted: <span class="name">findGreetings</span>()
}
}
</pre>
<p>The API conforms to the Synchronous API of the HTML5 Web Database API, <a href="http://www.w3.org/TR/2009/WD-webdatabase-20091029/">W3C Working Draft 29 October 2009</a>.</p>
<p>The <a href="qtquick-localstorage-example.html">SQL Local Storage example</a> demonstrates the basics of using the Offline Storage API.</p>
<a name="open-or-create-a-database"></a>
<h4 >Open or Create a Database</h4>
<pre class="cpp">
import <span class="type"><a href="qtquick-qmlmodule.html">QtQuick</a></span><span class="operator">.</span>LocalStorage <span class="number">2.0</span> as Sql
db <span class="operator">=</span> Sql<span class="operator">.</span>openDatabaseSync(identifier<span class="operator">,</span> version<span class="operator">,</span> description<span class="operator">,</span> estimated_size<span class="operator">,</span> callback(db))
</pre>
<p>The above code returns the database identified by <i>identifier</i>. If the database does not already exist, it is created, and the function <i>callback</i> is called with the database as a parameter. <i>identifier</i> is the name of the physical file (with or without full path) containing the database. <i>description</i> and <i>estimated_size</i> are written to the INI file (described below), but are currently unused.</p>
<p>May throw exception with code property SQLException.DATABASE_ERR, or SQLException.VERSION_ERR.</p>
<p>When a database is first created, an INI file is also created specifying its characteristics:</p>
<div class="table"><table class="generic">
<thead><tr class="qt-style"><th ><b>Key</b></th><th ><b>Value</b></th></tr></thead>
<tr valign="top" class="odd"><td >Identifier</td><td >The name of the database passed to <code>openDatabase()</code></td></tr>
<tr valign="top" class="even"><td >Version</td><td >The version of the database passed to <code>openDatabase()</code></td></tr>
<tr valign="top" class="odd"><td >Description</td><td >The description of the database passed to <code>openDatabase()</code></td></tr>
<tr valign="top" class="even"><td >EstimatedSize</td><td >The estimated size (in bytes) of the database passed to <code>openDatabase()</code></td></tr>
<tr valign="top" class="odd"><td >Driver</td><td >Currently "QSQLITE"</td></tr>
</table></div>
<p>This data can be used by application tools.</p>
<a name="db-changeversion-from-to-callback-tx"></a>
<h4 >db.changeVersion(from, to, callback(tx))</h4>
<p>This method allows you to perform a <i>Scheme Upgrade</i>.</p>
<p>If the current version of <i>db</i> is not <i>from</i>, then an exception is thrown.</p>
<p>Otherwise, a database transaction is created and passed to <i>callback</i>. In this function, you can call <i>executeSql</i> on <i>tx</i> to upgrade the database.</p>
<p>May throw exception with code property SQLException.DATABASE_ERR or SQLException.UNKNOWN_ERR.</p>
<p>See example below.</p>
<pre class="js">
var db = LocalStorage.openDatabaseSync("ActivityTrackDB", "", "Database tracking sports activities", 1000000);
if (db.version == "0.1") {
db.changeVersion("0.1", "0.2", function(tx) {
tx.executeSql("INSERT INTO trip_log VALUES(?, ?, ?)",
[ "01/10/2016","Sylling - Vikersund", "53" ]);
}
});
</pre>
<a name="db-transaction-callback-tx"></a>
<h4 >db.transaction(callback(tx))</h4>
<p>This method creates a read/write transaction and passed to <i>callback</i>. In this function, you can call <i>executeSql</i> on <i>tx</i> to read and modify the database.</p>
<p>If the callback throws exceptions, the transaction is rolled back. Below you will find an example of a database transaction which catches exceptions.</p>
<pre class="js">
var db = LocalStorage.openDatabaseSync("ActivityTrackDB", "", "Database tracking sports activities", 1000000);
db.transaction(
try {
function(tx) {
tx.executeSql("INSERT INTO trip_log VALUES(?, ?, ?)",
[ "01/10/2016","Sylling - Vikersund", "53" ]);
}
} catch (err) {
console.log("Error inserting into table trip_log: " + err);
}
)
</pre>
<p>In the example you can see an <code>insert</code> statement where values are assigned to the fields, and the record is written into the table. That is an <code>insert</code> statement with a syntax that is usual for a relational database. It is however also possible to work with JSON objects and store them in a table.</p>
<p>Let's suppose a simple example where we store trips in JSON format using <code>date</code> as the unique key. An example of a table that could be used for that purpose:</p>
<pre class="js">
create table trip_log(date text, data text)
</pre>
<p>The assignment of values to a JSON object:</p>
<pre class="js">
var obj = {description = "Vikersund - Noresund", distance = "60"}
</pre>
<p>In that case, the data could be saved in the following way:</p>
<pre class="js">
db.transaction(function(tx) {
result = tx.executeSQL("insert into trip_log values (?,?)",
["01/11/2016", JSON.stringify(obj)])
}
</pre>
<a name="db-readtransaction-callback-tx"></a>
<h4 >db.readTransaction(callback(tx))</h4>
<p>This method creates a read-only transaction and passed to <i>callback</i>. In this function, you can call <i>executeSql</i> on <i>tx</i> to read the database (with <code>select</code> statements).</p>
<a name="results-tx-executesql-statement-values"></a>
<h4 >results = tx.executeSql(statement, values)</h4>
<p>This method executes an SQL <i>statement</i>, binding the list of <i>values</i> to SQL positional parameters ("?").</p>
<p>It returns a results object, with the following properties:</p>
<div class="table"><table class="generic">
<thead><tr class="qt-style"><th ><b>Type</b></th><th ><b>Property</b></th><th ><b>Value</b></th><th ><b>Applicability</b></th></tr></thead>
<tr valign="top" class="odd"><td >int</td><td >rows.length</td><td >The number of rows in the result</td><td >SELECT</td></tr>
<tr valign="top" class="even"><td >var</td><td >rows.item(i)</td><td >Function that returns row <i>i</i> of the result</td><td >SELECT</td></tr>
<tr valign="top" class="odd"><td >int</td><td >rowsAffected</td><td >The number of rows affected by a modification</td><td >UPDATE, DELETE</td></tr>
<tr valign="top" class="even"><td >string</td><td >insertId</td><td >The id of the row inserted</td><td >INSERT</td></tr>
</table></div>
<p>May throw exception with code property SQLException.DATABASE_ERR, SQLException.SYNTAX_ERR, or SQLException.UNKNOWN_ERR.</p>
<p>See below for an example:</p>
<pre class="js">
// Retrieve activity date, description and distance based on minimum
// distance parameter Pdistance
function db_distance_select(Pdistance)
{
var db = LocalStorage.openDatabaseSync("ActivityTrackDB", "", "Database tracking sports activities", 1000000);
db.transaction(
function(tx) {
var results = tx.executeSql("SELECT rowid,
date,
trip_desc,
distance FROM trip_log
where distance >= ?",[Pdistance]);
for (var i = 0; i < results.rows.length; i++) {
listModel.append({"id": results.rows.item(i).rowid,
"date": results.rows.item(i).date,
"trip_desc": results.rows.item(i).trip_desc,
"distance": results.rows.item(i).distance});
}
}
}
</pre>
<a name="method-documentation"></a>
<h2 id="method-documentation">Method Documentation</h2>
<a name="opendatabasesync"></a><pre class="cpp">
object openDatabaseSync(string name<span class="operator">,</span> string version<span class="operator">,</span> string description<span class="operator">,</span> <span class="type">int</span> estimated_size<span class="operator">,</span> jsobject callback(db))
</pre>
<p>Opens or creates a local storage sql database by the given parameters.</p>
<ul>
<li><code>name</code> is the database name</li>
<li><code>version</code> is the database version</li>
<li><code>description</code> is the database display name</li>
<li><code>estimated_size</code> is the database's estimated size, in bytes</li>
<li><code>callback</code> is an optional parameter, which is invoked if the database has not yet been created.</li>
</ul>
<p>Returns the created database object.</p>
</div>
<!-- @@@QtQuick.LocalStorage -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
