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
|
/*
* Copyright (C) 2013 Canonical Ltd.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation; version 3.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/*!
\page statesaving.html
\title Automatic State Saving
\nextpage Application name, IDs
During application development it is often required to start an application
from a view which depends on the previous application runs. Like a web browser
should remember the number of opened tabs, their content or the browsing
history, or a news reader application should continue from the last news the
application was opened on, preferably from the same position.
Ubuntu UI toolkit provides a simple way to save the state of any component
within an application, by using the attached component \l StateSaver. By simply
attaching this component to any QtQuick component and specifying the
\l{StateSaver::properties}{properties} to be saved, applications can be restored
to any previous state they were before being closed.
Consider the following simple QtQuick application, which on button press
randomly changes its background.
\snippet statesaver/ColorChanger.qml color-saver
But let's see what else is neded to properly save an application's components
proeprties.
*/
/*!
\page statesaving1.html
\title Application name, IDs
\section1 Application name
First of all, the application must have a proper application name set. If you
use Qt Creator's Ubuntu project wizards, you will have the application name
set by default, name which is in sync with the name from the application's
desktop file.
The application name plays an essential role in storing the state archive. By
specifying different application names, different state archives can be serialized
for the application. However runtime application name change would require
application restart.
Having these preconditions, we can deduct that \l {MainView::applicationName}{MainView.applicationName}
property is one of the properties which cannot be serialized.
\section1 IDs
Components for which property saving is wanted should define an ID, even though
it is otherwise not justified. For example the following code snippet would give
runtime error:
\qml
Rectangle {
color: "green"
StateSaver.properties: "color"
}
\endqml
but giving an ID would make it serializable:
\qml
Rectangle {
id: rectangle
color: "green"
StateSaver.properties: "color"
}
\endqml
This rule must also be applied on component parents in the object hierarchy.
\qml
Item {
id: root
Rectangle {
id: rectangle
color: "green"
StateSaver.properties: "color"
}
}
\endqml
\nextpage Saving multiple properties
*/
/*!
\page statesaving2.html
\title Saving multiple properties
\section1 Specifying more properties
So far we have saved one single property, but as the \{StateSaver::properties}
property name suggests, there can be more properties serialized at the same time.
For example, to serialize both color and opacity of a Rectangle, the code would
look as follows:
\qml
Rectangle {
id: rectangle
color: "green"
opacity: 0.9
StateSaver.properties: "color, opacity"
}
\endqml
\b Note that not all types of properties can be saved. Object types or list
models for example are excluded from the types that can be saved, but all
properties listed as \l{http://qt-project.org/doc/qt-5.0/qtqml/qtqml-typesystem-basictypes.html}{QML base types}
can be serialized.
\section1 Grouped properties
Grouped properties, which have serializable types can also be saved. It simply
needs to be specified together with the group identifier.
\snippet statesaver/MultiplePropertySaver.qml group-saver
\section1 Property groups
Using the same logic, custom property groups can also be saved.
\snippet statesaver/PropertyGroupSaver.qml property-group-saver
Alternatively, individual properties of the property group can be saved in
the following way:
\snippet statesaver/PropertyGroupSaver2.qml alt-group-saver
\nextpage Recap on state saving
*/
/*!
\page statesaving3.html
\title Recap on state saving
The following issues must be considered when deciding on state saving:
\list
\li - don't try to save MainView.applicationName, as its change will take
effect next time the application is launched
\li - specify IDs for all components as well as for parents even if their
presence is not justified in the document
\li types other than the ones listed in \l{http://qt-project.org/doc/qt-5.0/qtqml/qtqml-typesystem-basictypes.html}{QML base types}
will not be serialized
\li - grouped properties can be saved by specifying the complete path to
the property i.e. \a border.width, \a border.color, etc.
\endlist
\raw HTML
<br>
\endraw
When chosing the IDs, try to use as unique identifiers as possible. In most
of the cases applications load content (document) dynamically using Loaders.
Usually elements in these documents use different IDs for their elements,
but there can be cases when the same IDs will be used with the same hierarchy
(i.e. root->item can occur in several documents). UID computation takes into
account the file name and line number the property's owner (attachee) is declared,
therefore the property saving will be successful in these cases too.
See documentation on \l StateSaver properties under \l{Services} section.
\nextpage {Ubuntu User Interface Toolkit}
*/
|