/usr/share/u1db-qt/doc/html/tutorial.html is in libu1db-qt5-doc 0.1.5+15.10.20150826.1-0ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- u1db.tutorial.qdoc -->
<title>Tutorial | U1Db-Qt </title>
<link rel="stylesheet" type="text/css" href="style/css.css">
<link rel="stylesheet" type="text/css" href="style/css_002.css">
<link rel="stylesheet" type="text/css" href="style/reset.css">
<link rel="stylesheet" type="text/css" href="style/qtquick.css">
<link rel="stylesheet" type="text/css" href="style/base.css">
<link rel="stylesheet" type="text/css" href="style/scratch.css">
<link rel="stylesheet" type="text/css" href="style/base.css" /></head>
<body>
<div class="wrapper">
<div class="main-content">
<li>Tutorial</li>
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#1-0-0-overview-of-u1db-qt">1.0.0 Overview of U1Db-Qt</a></li>
<li class="level1"><a href="#1-0-1-how-to-make-u1db-qt-available-to-a-qml-application">1.0.1 How to Make U1Db-Qt Available to a QML Application</a></li>
<li class="level1"><a href="#2-0-0-database-element">2.0.0 Database Element</a></li>
<li class="level1"><a href="#2-0-1-database-properties">2.0.1 Database Properties</a></li>
<li class="level1"><a href="#2-1-0-creating-a-database">2.1.0 Creating a Database</a></li>
<li class="level2"><a href="#2-1-1-example-of-creating-a-database">2.1.1 Example of Creating a Database</a></li>
<li class="level1"><a href="#3-0-0-document-element">3.0.0 Document Element</a></li>
<li class="level1"><a href="#3-0-1-document-properties">3.0.1 Document Properties</a></li>
<li class="level1"><a href="#3-1-0-creating-a-basic-document">3.1.0 Creating a Basic Document</a></li>
<li class="level2"><a href="#3-1-0-1-example-of-creating-a-basic-document">3.1.0.1 Example of Creating a Basic Document</a></li>
<li class="level1"><a href="#3-1-1-creating-a-document-at-runtime">3.1.1 Creating a Document At Runtime</a></li>
<li class="level2"><a href="#3-1-1-1-example-of-creating-a-document-at-runtime">3.1.1.1 Example of Creating a Document At Runtime</a></li>
<li class="level1"><a href="#3-1-2-creating-a-document-dynamically">3.1.2 Creating a Document Dynamically</a></li>
<li class="level2"><a href="#3-1-2-1-example-1-of-creating-a-document-dynamically">3.1.2.1 Example 1 of Creating a Document Dynamically</a></li>
<li class="level2"><a href="#3-1-2-2-example-2-of-creating-a-document-dynamically">3.1.2.2 Example 2 of Creating a Document Dynamically</a></li>
<li class="level1"><a href="#4-0-0-u1db-qt-and-qml-elements-and-models">4.0.0 U1Db-Qt and QML Elements and Models</a></li>
<li class="level1"><a href="#4-1-0-u1db-qt-and-standard-elements">4.1.0 U1Db-Qt and Standard Elements</a></li>
<li class="level2"><a href="#4-1-1-u1db-qt-and-textfield-textarea">4.1.1 U1Db-Qt and TextField & TextArea</a></li>
<li class="level3"><a href="#4-1-2-example-of-using-u1db-qt-with-standard-elements">4.1.2 Example of Using U1Db-Qt with Standard Elements</a></li>
<li class="level1"><a href="#4-2-0-u1db-qt-and-model-based-elements">4.2.0 U1Db-Qt and Model-Based Elements</a></li>
<li class="level2"><a href="#4-2-1-u1db-qt-and-listview">4.2.1 U1Db-Qt and ListView</a></li>
<li class="level3"><a href="#4-2-2-example-of-using-u1db-qt-with-model-based-elements">4.2.2 Example of Using U1Db-Qt with Model-Based Elements</a></li>
<li class="level1"><a href="#5-0-0-resources">5.0.0 Resources</a></li>
<li class="level1"><a href="#5-0-1-examples">5.0.1 Examples</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Tutorial</h1>
<span class="subtitle"></span>
<!-- $$$tutorial.html-description -->
<div class="descr"> <a name="details"></a>
<a name="1-0-0-overview-of-u1db-qt"></a>
<h2 id="1-0-0-overview-of-u1db-qt">1.0.0 Overview of U1Db-Qt</h2>
<p>U1Db-Qt is a QML plugin written in Qt C++. It provides declarative, easy to use, local data storage for QML applications, and in the future will also include remote sync capabilities.</p>
<p>U1Db-Qt is based on a procedural implementation in Python, but has been designed and developed from the start with declarative programming in mind.</p>
<p>While U1Db-Qt makes use of SQLite in the back end, and relies heavily on JSON, these are largely invisible to a QML developer who makes use of the plugin. However, because U1Db-Qt does rely on both technologies it is possible to easily debug applications using existing programs. For example, a developer could make use of SQLiteBrowser to read U1Db database files, which contain human readable JSON objects representing content derived from a QML application.</p>
<a name="1-0-1-how-to-make-u1db-qt-available-to-a-qml-application"></a>
<h2 id="1-0-1-how-to-make-u1db-qt-available-to-a-qml-application">1.0.1 How to Make U1Db-Qt Available to a QML Application</h2>
<p>Here is an example import statement:</p>
<pre class="cpp">import U1db <span class="number">1.0</span> as U1db</pre>
<a name="2-0-0-database-element"></a>
<h2 id="2-0-0-database-element">2.0.0 Database Element</h2>
<p>In U1Db-Qt, the Database element is the the central figure that works in conjunction with Document elements, and in the future indexing (currently under development), and querying (currently under development) elements. It is the Database element that defines the location of the data repository.</p>
<p>A Database element is also a valuable tool for cases where specific data from a repository needs to be retrieved quickly, without indexing or querying ahead of time. The 'contents' object associated with the Database element can be used together with base items such as <a href="http://developer.ubuntu.com/api/ubuntu-15.04/qml/mobile//qml-ubuntu-components-textfield.html">TextField</a> or <a href="http://developer.ubuntu.com/api/ubuntu-15.04/qml/mobile//qml-ubuntu-components-textarea.html">TextArea</a> and model-based items like ListView and <a href="http://developer.ubuntu.com/api/ubuntu-15.04/qml/mobile//qml-ubuntu-components-listitems-standard.html">ListItems.Standard</a>.</p>
<a name="2-0-1-database-properties"></a>
<h2 id="2-0-1-database-properties">2.0.1 Database Properties</h2>
<pre class="cpp"><span class="type">QString</span> path
<span class="type">QString</span> error</pre>
<a name="2-1-0-creating-a-database"></a>
<h2 id="2-1-0-creating-a-database">2.1.0 Creating a Database</h2>
<p>A Database is very simple to create. It requires nothing more than an id and a path where the file will be created.</p>
<a name="2-1-1-example-of-creating-a-database"></a>
<h3 >2.1.1 Example of Creating a Database</h3>
<pre class="cpp">import <span class="type">QtQuick</span> <span class="number">2.0</span>
import U1db <span class="number">1.0</span> as U1db
Item{
U1db<span class="operator">.</span>Database {
id: aDatabase
path: <span class="string">"aU1DbDatabase"</span>
}
}</pre>
<a name="3-0-0-document-element"></a>
<h2 id="3-0-0-document-element">3.0.0 Document Element</h2>
<p>The Document element is the primary vehicle for entering data into a repository, and can be helpful in some cases for getting data out as well. Indexing and querying would normally provide more robust functionality for extracting data from a repository, but in the case of U1Db-Qt both are still under development at the time of writing (and therefore not available for developers to use).</p>
<p>However, the Document element together with Database can still help developers in many common situations, and will continue to be very useful even when the indexing and querying functionality becomes available. When a developer wants unfiltered results from a database, or the cost of working with unfiltered results is reasonable, the Document+Database combination is fast and easy to use. In quite a number of use cases this may be exactly what a developer needs.</p>
<a name="3-0-1-document-properties"></a>
<h2 id="3-0-1-document-properties">3.0.1 Document Properties</h2>
<pre class="cpp">U1db<span class="operator">.</span>Database database
<span class="type">QString</span> docId
bool create
<span class="type">QVariant</span> defaults
<span class="type">QVariant</span> contents</pre>
<a name="3-1-0-creating-a-basic-document"></a>
<h2 id="3-1-0-creating-a-basic-document">3.1.0 Creating a Basic Document</h2>
<p>A Document declaration should contain at least a unique 'docId' and 'database', but these alone won't do anything by themselves. Additionally, although the 'id' property is not mandatory, this property will need to be set in order to more easily reference it from elsewhere in the program (e.g. within a function call).</p>
<a name="3-1-0-1-example-of-creating-a-basic-document"></a>
<h3 >3.1.0.1 Example of Creating a Basic Document</h3>
<pre class="cpp">import <span class="type">QtQuick</span> <span class="number">2.0</span>
import U1db <span class="number">1.0</span> as U1db
import Ubuntu<span class="operator">.</span>Components <span class="number">0.1</span>
Item{
width: units<span class="operator">.</span>gu(<span class="number">45</span>)
height: units<span class="operator">.</span>gu(<span class="number">80</span>)
U1db<span class="operator">.</span>Database {
id: aDatabase
path: <span class="string">"aU1DbDatabase"</span>
}
}</pre>
<a name="3-1-1-creating-a-document-at-runtime"></a>
<h2 id="3-1-1-creating-a-document-at-runtime">3.1.1 Creating a Document At Runtime</h2>
<p>A Document can be declared at runtime, and default data entered into the repository. This requires the same properties to be set as in the basic example ('id', 'database' and 'docId'), plus setting 'create' (to true) and a 'default' string.</p>
<a name="3-1-1-1-example-of-creating-a-document-at-runtime"></a>
<h3 >3.1.1.1 Example of Creating a Document At Runtime</h3>
<pre class="cpp">import <span class="type">QtQuick</span> <span class="number">2.0</span>
import U1db <span class="number">1.0</span> as U1db
import Ubuntu<span class="operator">.</span>Components <span class="number">0.1</span>
Item{
width: units<span class="operator">.</span>gu(<span class="number">45</span>)
height: units<span class="operator">.</span>gu(<span class="number">80</span>)
U1db<span class="operator">.</span>Database {
id: aDatabase
path: <span class="string">"aU1DbDatabase"</span>
}
U1db<span class="operator">.</span>Document {
id: aDocument
database: aDatabase
docId: <span class="char">'helloworld'</span>
create: <span class="keyword">true</span>
defaults: { <span class="string">"hello"</span>: <span class="string">"Hello World!"</span> }
}
}</pre>
<a name="3-1-2-creating-a-document-dynamically"></a>
<h2 id="3-1-2-creating-a-document-dynamically">3.1.2 Creating a Document Dynamically</h2>
<p>Creating a Document in a dynamic fashion is the most common way of putting data into a data repository based on UI activity (e.g. when a user presses a button).</p>
<a name="3-1-2-1-example-1-of-creating-a-document-dynamically"></a>
<h3 >3.1.2.1 Example 1 of Creating a Document Dynamically</h3>
<p>Another way of creating a new Document is to copy an existing Document:</p>
<pre class="cpp">import <span class="type">QtQuick</span> <span class="number">2.0</span>
import U1db <span class="number">1.0</span> as U1db
import Ubuntu<span class="operator">.</span>Components <span class="number">0.1</span>
Item{
width: units<span class="operator">.</span>gu(<span class="number">45</span>)
height: units<span class="operator">.</span>gu(<span class="number">80</span>)
U1db<span class="operator">.</span>Database {
id: aDatabase
path: <span class="string">"aU1DbDatabase"</span>
}
U1db<span class="operator">.</span>Document {
id: aDocument
database: aDatabase
docId: <span class="char">'helloworld'</span>
}
function someFunction() {
var tempDocument <span class="operator">=</span> {}
tempDocument <span class="operator">=</span> aDocument
}
}</pre>
<a name="3-1-2-2-example-2-of-creating-a-document-dynamically"></a>
<h3 >3.1.2.2 Example 2 of Creating a Document Dynamically</h3>
<p>One way of creating a new Document dynamically is to make use of Qt.createQmlObject:</p>
<pre class="cpp">import <span class="type">QtQuick</span> <span class="number">2.0</span>
import U1db <span class="number">1.0</span> as U1db
import Ubuntu<span class="operator">.</span>Components <span class="number">0.1</span>
Item{
width: units<span class="operator">.</span>gu(<span class="number">45</span>)
height: units<span class="operator">.</span>gu(<span class="number">80</span>)
U1db<span class="operator">.</span>Database {
id: aDatabase
path: <span class="string">"aU1DbDatabase"</span>
Component<span class="operator">.</span>onCompleted: { newDocumentObject() }
function newDocumentObject() {
var qmlString <span class="operator">=</span> <span class="string">"import QtQuick 2.0; import U1db 1.0 as U1db; U1db.Document {id: aDcoument; database: aDatabase; docId: 'helloworld'; create: true; defaults: { 'hello': 'Hello New Document!' }}"</span>
<span class="type">Qt</span><span class="operator">.</span>createQmlObject(qmlString<span class="operator">,</span> aDatabase);
}
}
}</pre>
<a name="4-0-0-u1db-qt-and-qml-elements-and-models"></a>
<h2 id="4-0-0-u1db-qt-and-qml-elements-and-models">4.0.0 U1Db-Qt and QML Elements and Models</h2>
<a name="4-1-0-u1db-qt-and-standard-elements"></a>
<h2 id="4-1-0-u1db-qt-and-standard-elements">4.1.0 U1Db-Qt and Standard Elements</h2>
<a name="4-1-1-u1db-qt-and-textfield-textarea"></a>
<h3 >4.1.1 U1Db-Qt and TextField & TextArea</h3>
<a name="4-1-2-example-of-using-u1db-qt-with-standard-elements"></a>
<h4 >4.1.2 Example of Using U1Db-Qt with Standard Elements</h4>
<pre class="cpp">import <span class="type">QtQuick</span> <span class="number">2.0</span>
import U1db <span class="number">1.0</span> as U1db
import Ubuntu<span class="operator">.</span>Components <span class="number">0.1</span>
Item{
width: units<span class="operator">.</span>gu(<span class="number">45</span>)
height: units<span class="operator">.</span>gu(<span class="number">80</span>)
function getContent(fieldName){
var tempContents <span class="operator">=</span> {};
tempContents <span class="operator">=</span> aDocument<span class="operator">.</span>contents
<span class="keyword">return</span> tempContents<span class="operator">[</span>fieldName<span class="operator">]</span>
}
U1db<span class="operator">.</span>Database {
id: aDatabase
path: <span class="string">"aU1DbDatabase"</span>
}
U1db<span class="operator">.</span>Document {
id: aDocument
database: aDatabase
docId: <span class="char">'helloworld'</span>
create: <span class="keyword">true</span>
defaults: { <span class="string">"hello"</span>: <span class="string">"Hello World 1!"</span> }
}
TextField {
id: addressBar
width: units<span class="operator">.</span>gu(<span class="number">45</span>)
text: getContent(<span class="char">'hello'</span>)
}
}</pre>
<a name="4-2-0-u1db-qt-and-model-based-elements"></a>
<h2 id="4-2-0-u1db-qt-and-model-based-elements">4.2.0 U1Db-Qt and Model-Based Elements</h2>
<a name="4-2-1-u1db-qt-and-listview"></a>
<h3 >4.2.1 U1Db-Qt and ListView</h3>
<a name="4-2-2-example-of-using-u1db-qt-with-model-based-elements"></a>
<h4 >4.2.2 Example of Using U1Db-Qt with Model-Based Elements</h4>
<pre class="cpp">import <span class="type">QtQuick</span> <span class="number">2.0</span>
import U1db <span class="number">1.0</span> as U1db
import Ubuntu<span class="operator">.</span>Components <span class="number">0.1</span>
Item{
width: units<span class="operator">.</span>gu(<span class="number">45</span>)
height: units<span class="operator">.</span>gu(<span class="number">80</span>)
U1db<span class="operator">.</span>Database {
id: aDatabase
path: <span class="string">"aU1DbDatabase"</span>
}
U1db<span class="operator">.</span>Document {
id: aDocument1
database: aDatabase
docId: <span class="char">'helloworld'</span>
create: <span class="keyword">true</span>
defaults: { <span class="string">"hello"</span>: <span class="string">"Hello World 1!"</span> }
}
U1db<span class="operator">.</span>Document {
id: aDocument2
database: aDatabase
docId: <span class="char">'helloworld'</span>
create: <span class="keyword">true</span>
defaults: { <span class="string">"hello"</span>: <span class="string">"Hello World 2!"</span> }
}
ListView {
model: aDatabase
width: units<span class="operator">.</span>gu(<span class="number">45</span>)
height: units<span class="operator">.</span>gu(<span class="number">80</span>)
delegate: Text {
x: <span class="number">66</span>; y: <span class="number">77</span>
text: contents<span class="operator">.</span>hello
}
}
}</pre>
<a name="5-0-0-resources"></a>
<h2 id="5-0-0-resources">5.0.0 Resources</h2>
<a name="5-0-1-examples"></a>
<h2 id="5-0-1-examples">5.0.1 Examples</h2>
<p>One can find several examples in the bzr branch of U1Db-Qt (bzr branch lp:u1db-qt) either in the subdirectory "examples" or from the following url:</p>
<p>http://bazaar.launchpad.net/~uonedb-qt/u1db-qt/trunk/files/head:/examples/</p>
<p>These examples are currently under development (as is U1Db-Qt in general), but should still be able to demonstrate the fundamentals discussed within this document.</p>
</div>
<!-- @@@tutorial.html -->
</div>
</div>
</body>
</html>
|