Skip to content

Commit e116379

Browse files
Skycoder42Skycoder42
committed
added update installer doc
1 parent 62b5708 commit e116379

File tree

4 files changed

+317
-14
lines changed

4 files changed

+317
-14
lines changed

‎doc/updateinstaller.dox‎

Lines changed: 280 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
/*!
2+
@class QtAutoUpdater::UpdateInstaller
3+
4+
This class can be used to perform an update of the application from within the running process,
5+
without the need of an external installer. It can also be used if an external installer provides
6+
enough details about an installation for them to be presented via this class.
7+
8+
Instances of the installer are provided via Updater::showInstaller if such an installer was selected
9+
by Updater::runUpdater. You can then use the public API of the installer to select components to be
10+
installed and perform their installation.
11+
12+
When implementing a custom updater backend, you can use this as abstract base class for a custom
13+
installer.
14+
15+
@note Using such an installer requires the UpdaterBackend to have the
16+
UpdaterBackend::Feature::PerformInstall flag set.
17+
18+
@sa Updater, Updater::showInstaller, UpdaterBackend
19+
*/
20+
21+
/*!
22+
@property QtAutoUpdater::UpdateInstaller::features
23+
24+
@default{`UpdateInstaller::Feature::None`}
25+
26+
The flags indicate which features are supported and which are not.
27+
28+
@accessors{
29+
@readAc{features()}
30+
@constantAc
31+
}
32+
33+
@sa UpdateInstaller::Feature, UpdaterBackend::features()
34+
*/
35+
36+
/*!
37+
@property QtAutoUpdater::UpdateInstaller::components
38+
39+
@default{`<empty>`}
40+
41+
This property only returns enabled components. If a component was disabled by the user, it is not
42+
visible via this property. You can thuse use this to figure out which components are actually
43+
installed. When setting this property, all components set are marked as enabled and thus are visible
44+
through this property.
45+
46+
@accessors{
47+
@readAc{components()}
48+
@writeAc{setComponents()}
49+
@notifyAc{componentsChanged()}
50+
}
51+
52+
@sa UpdateInstaller::componentModel, UpdateInstaller::setComponentEnabled
53+
*/
54+
55+
/*!
56+
@property QtAutoUpdater::UpdateInstaller::componentModel
57+
58+
@default{`<instance>`}
59+
60+
By default, the model provides the following roles and columns. Strings represent those accessible
61+
from QML via role names, others are enum values for access via C++.
62+
63+
Column | role | UpdateInfo property: type | writable
64+
--------|-----------------------|-----------------------------------|----------
65+
0 | Qt::DisplayRole | name: QString | false
66+
0 | Qt::ToolTipRole | name: QString | false
67+
0 | Qt::CheckStateRole | _&lt;enabled&gt;_: Qt::CheckState | true
68+
0 | "name" | name: QString | false
69+
0 | "version" | version: QString | false
70+
0 | "selected" | _&lt;enabled&gt;_: bool | true
71+
0 | "updateInfo" | _&lt;gadget&gt;_: UpdateInfo | false
72+
1 | Qt::DisplayRole | version: QString | false
73+
1 | Qt::ToolTipRole | version: QString | false
74+
75+
However, backends can decide to provide additional/different columns and roles as well. The model
76+
should always provide a way for the user to enable or disable components.
77+
78+
@note This model is useless unless the Feature::SelectComponents was set in
79+
UpdateInstaller::features
80+
81+
@accessors{
82+
@readAc{componentModel()}
83+
@constantAc
84+
}
85+
86+
@sa UpdateInstaller::components, UpdateInstaller::setComponentEnabled, UpdateInstaller::Feature,
87+
UpdateInstaller::features
88+
*/
89+
90+
/*!
91+
@property QtAutoUpdater::UpdateInstaller::progressModel
92+
93+
@default{`<instance>`}
94+
95+
By default, the model provides the following roles and columns. Strings represent those accessible
96+
from QML via role names, others are enum values for access via C++. None are writable. "progress"
97+
and "status" are special properties that can be set via updateComponentProgress()
98+
99+
Column | role | UpdateInfo property: type
100+
--------|-----------------------|---------------------------
101+
0 | Qt::DisplayRole | name: QString
102+
0 | Qt::ToolTipRole | name: QString
103+
0 | "name" | name: QString
104+
0 | "progress" | progress: double
105+
0 | "status" | status: QString
106+
0 | "updateInfo" | _&lt;gadget&gt;_: UpdateInfo
107+
1 | Qt::DisplayRole | status: QString
108+
1 | Qt::ToolTipRole | status: QString
109+
2 | Qt::DisplayRole | progress: double
110+
2 | Qt::ToolTipRole | progress: double
111+
112+
However, backends can decide to provide additional/different columns and roles as well. The model
113+
should connect to the updateComponentProgress() signal to be able to catch the progress of
114+
components and should always display those in some way via the model.
115+
116+
@note This model is useless unless the Feature::DetailedProgress was set in
117+
UpdateInstaller::features
118+
119+
@accessors{
120+
@readAc{progressModel()}
121+
@constantAc
122+
}
123+
124+
@sa UpdateInstaller::updateComponentProgress, UpdateInstaller::Feature, UpdateInstaller::features
125+
*/
126+
127+
/*!
128+
@fn QtAutoUpdater::UpdateInstaller::startInstall
129+
130+
Call this to start an installation.
131+
132+
@attention Do **not** reimplement this method yourself unless you have a custom progressModel!!!
133+
Instead, implement startInstallImpl(), as that method is called directly from this one.
134+
135+
@sa UpdateInstaller::startInstallImpl, UpdateInstaller::progressModel
136+
*/
137+
138+
/*!
139+
@fn QtAutoUpdater::UpdateInstaller::cancelInstall
140+
141+
Call this to abort an ongoing installation.
142+
143+
@note For this method to ever be called, the Feature::DetailedProgress must be set in
144+
UpdateInstaller::features
145+
146+
@warning Even if this is supported by a backend, cancelling can **always** have fatal repercussions
147+
on an installation and possibly corrupt it into an unrepairable state! When allowing users to
148+
cancel, always make them aware of this fact.
149+
150+
@sa UpdateInstaller::startInstall, UpdateInstaller::Feature, UpdateInstaller::features
151+
*/
152+
153+
/*!
154+
@fn QtAutoUpdater::UpdateInstaller::eulaHandled
155+
156+
@param id The id of the EULA that was passed to it's show request
157+
@param accepted true, if the user accepted the EULA, false if not
158+
159+
Call this method from a GUI to notify the installer that a required EULA was accepted or rejected.
160+
161+
For the implementation of this method, a rejected EULA should always lead to a failed installation.
162+
163+
@sa UpdateInstaller::showEula
164+
*/
165+
166+
/*!
167+
@fn QtAutoUpdater::UpdateInstaller::restartApplication
168+
169+
Implement this method if you are going to emit installSucceeded(true). The method should quit the
170+
current application and restart it, using the updated version of your application.
171+
172+
@sa UpdateInstaller::installSucceeded
173+
*/
174+
175+
/*!
176+
@fn QtAutoUpdater::UpdateInstaller::updateGlobalProgress
177+
178+
@param progress The progress of the full installation
179+
@param status The current status of the installation
180+
181+
Emit this signal to give the user some feedback on the current state of the installation. percent
182+
can either range from 0.0 to 1.0 to present an actual percentage, or be -1.0 to represent an
183+
indeterminate progress. Status can be left empty to be unchanged/unset. Emitting this signal is
184+
optional, but recommended.
185+
186+
@sa UpdateInstaller::updateComponentProgress
187+
*/
188+
189+
/*!
190+
@fn QtAutoUpdater::UpdateInstaller::updateComponentProgress
191+
192+
@param id The id of the component
193+
@param progress The progress of the full installation
194+
@param status The current status of the installation
195+
196+
Emit this signal to give the user some feedback on the current state of a certain component that is
197+
part of the installation. The semantics are the same as for updateGlobalProgress(). The id is the
198+
same as the UpdateInfo::identifier property of the UpdateInfo that represents that component.
199+
200+
This signal is typically consumed by the progressModel, which displays it.
201+
202+
@note This signal is ignored unless the Feature::DetailedProgress was set in
203+
UpdateInstaller::features
204+
205+
@sa UpdateInstaller::updateGlobalProgress, UpdateInstaller::progressModel
206+
*/
207+
208+
/*!
209+
@fn QtAutoUpdater::UpdateInstaller::showEula
210+
211+
@param id An internally used id to identify the EULA
212+
@param htmlText The EULAs text, formatted as HTML-text
213+
@param required Specifies whether the EULA must be accepted or not
214+
215+
Emit this signal to make the user accept an EULA. The id is used internally and only actually needed
216+
for required EULAs, as it is passed to eulaHandled() to report the result. The text is interpreted
217+
as HTML, but should only consist of the HTML-subset supported by styled QML Labels.
218+
219+
If required is false, the EULA should only be shown to the user, but he doesn't have to accept it.
220+
If set true however, the user must accept the EULA and the result must be reported via
221+
eulaHandled().
222+
223+
Required EULAs should block the installation until accepted and their rejection should fail an
224+
installation.
225+
226+
@sa UpdateInstaller::eulaHandled
227+
*/
228+
229+
/*!
230+
@fn QtAutoUpdater::UpdateInstaller::installSucceeded
231+
232+
@param shouldRestart Specify whether the application should be restarted
233+
234+
Emit this from your custom installer on a successfully completed installation. If you set the
235+
shouldRestart to true, the user will be asked if he wants to restart the application. If he accepts,
236+
restartApplication() will be called to do so. Otherwise, the user is not presented the option and
237+
nothing happens.
238+
239+
@sa UpdateInstaller::installFailed, UpdateInstaller::restartApplication
240+
*/
241+
242+
/*!
243+
@fn QtAutoUpdater::UpdateInstaller::installFailed
244+
245+
@param errorMessage Specify whether the application should be restarted
246+
247+
Emit this from your custom installer on a failed installation. The errorMessage should be a
248+
localized string to describe what went wrong to the user. Do not include technical details there,
249+
only general information. Such details should be logged instead.
250+
251+
@sa UpdateInstaller::installSucceeded
252+
*/
253+
254+
/*!
255+
@fn QtAutoUpdater::UpdateInstaller::startInstallImpl
256+
257+
The actual method to start the installation. This should start whatever has to be done to perform
258+
the installation in a non-blocking manner.
259+
260+
@sa UpdateInstaller::startInstall, UpdateInstaller::installSucceeded,
261+
UpdateInstaller::installFailed, UpdateInstaller::updateGlobalProgress,
262+
UpdateInstaller::updateComponentProgress, UpdateInstaller::showEula
263+
*/
264+
265+
/*!
266+
@fn QtAutoUpdater::UpdateInstaller::setComponentEnabled
267+
268+
@param id The id of the component to be enabled or disabled
269+
@param enabled The new state of the component
270+
271+
Call this method from your custom componentModel to enable or disable components as done by the
272+
user. The id is the same as the UpdateInfo::identifier property of the UpdateInfo that represents
273+
that component. You can only enable/disable components that have been added to the installer via
274+
the components property.
275+
276+
@note Disabled components will disappear from the components property, but still be settable via
277+
this method. To completely remove the, write the property instead.
278+
279+
@sa UpdateInstaller::components, UpdateInstaller::componentModel
280+
*/

‎src/autoupdatercore/updateinstaller.cpp‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,11 @@ void UpdateInstaller::startInstall()
6060

6161
void UpdateInstaller::cancelInstall() {}
6262

63+
void UpdateInstaller::restartApplication()
64+
{
65+
qCWarning(logInstaller) << "Restarting is not supported by the current backend";
66+
}
67+
6368
void UpdateInstaller::setComponents(QList<UpdateInfo> components)
6469
{
6570
Q_D(UpdateInstaller);
@@ -78,11 +83,6 @@ void UpdateInstaller::setComponents(QList<UpdateInfo> components)
7883
d->componentModel->reset(d->components.values());
7984
}
8085

81-
void UpdateInstaller::restartApplication()
82-
{
83-
qCWarning(logInstaller) << "Restarting is not supported by the current backend";
84-
}
85-
8686
void UpdateInstaller::setComponentEnabled(const QVariant &id, bool enabled)
8787
{
8888
Q_D(UpdateInstaller);

‎src/autoupdatercore/updateinstaller.h‎

Lines changed: 31 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -13,56 +13,79 @@ namespace QtAutoUpdater {
1313
class ComponentModel;
1414

1515
class UpdateInstallerPrivate;
16+
//! An interface to implement and consume custom in-process installer
1617
class Q_AUTOUPDATERCORE_EXPORT UpdateInstaller : public QObject
1718
{
1819
Q_OBJECT
1920

21+
//! Holds the features this installer supports
2022
Q_PROPERTY(QtAutoUpdater::UpdateInstaller::Features features READ features CONSTANT)
23+
//! The components to be installed
2124
Q_PROPERTY(QList<QtAutoUpdater::UpdateInfo> components READ components WRITE setComponents NOTIFY componentsChanged)
25+
//! An item model to let the user interactively select components to be installed
2226
Q_PROPERTY(QAbstractItemModel* componentModel READ componentModel CONSTANT)
27+
//! An item model showing the progress and status of each update component being installed
2328
Q_PROPERTY(QAbstractItemModel* progressModel READ progressModel CONSTANT)
2429

2530
public:
31+
//! Various features an installer may or may not support
2632
enum class Feature {
27-
None = 0x00,
28-
SelectComponents = 0x01,
29-
DetailedProgress = 0x02,
30-
CanCancel = 0x04
33+
None = 0x00, //!< The installer does not support any of the optional features
34+
SelectComponents = 0x01, //!< The installer allows the user to interactively select components
35+
DetailedProgress = 0x02, //!< The installer provides progress information for each component beeing installed.
36+
CanCancel = 0x04 //!< The installation can be canceled
3137
};
3238
Q_DECLARE_FLAGS(Features, Feature)
3339
Q_FLAG(Features)
3440

41+
//! @readAcFn{UpdateInstaller::features}
3542
virtual Features features() const = 0;
36-
43+
//! @readAcFn{UpdateInstaller::components}
3744
virtual QList<UpdateInfo> components() const;
38-
45+
//! @readAcFn{UpdateInstaller::componentModel}
3946
virtual QAbstractItemModel *componentModel() const;
47+
//! @readAcFn{UpdateInstaller::progressModel}
4048
virtual QAbstractItemModel *progressModel() const;
4149

4250
public Q_SLOTS:
51+
//! Is called to start the actual installation with the current components
4352
virtual void startInstall();
53+
//! Is called to cancel an ongoing installation
4454
virtual void cancelInstall();
55+
//! Is called to report the result of a user accepting or rejecting a required EULA
4556
virtual void eulaHandled(const QVariant &id, bool accepted) = 0;
4657

47-
virtual void setComponents(QList<QtAutoUpdater::UpdateInfo> components);
48-
58+
//! Is called to restart the application
4959
virtual void restartApplication();
5060

61+
//! @writeAcFn{UpdateInstaller::components}
62+
virtual void setComponents(QList<QtAutoUpdater::UpdateInfo> components);
63+
5164
Q_SIGNALS:
65+
//! Is emitted to report the global, overall progress and status of the installation
5266
void updateGlobalProgress(double progress, const QString &status = {});
67+
//! Is emitted to report the progress and status of a single component beeing updated
5368
void updateComponentProgress(const QVariant &id, double progress, const QString &status = {});
69+
//! Is emitted if a EULA must be shown to the user
5470
void showEula(const QVariant &id, const QString &htmlText, bool required);
71+
//! Is emitted when the installation has succeeded
5572
void installSucceeded(bool shouldRestart);
73+
//! Is emitted when the installation has failed
5674
void installFailed(const QString &errorMessage);
5775

76+
//! @notifyAcFn{UpdateInstaller::components}
5877
void componentsChanged();
5978

6079
protected:
80+
//! Default constructor
6181
explicit UpdateInstaller(QObject *parent = nullptr);
82+
//! @private
6283
explicit UpdateInstaller(UpdateInstallerPrivate &dd, QObject *parent = nullptr);
6384

85+
//! Internal method to actually start the installation
6486
virtual void startInstallImpl() = 0;
6587

88+
//! Enables or disables a component for installation
6689
virtual void setComponentEnabled(const QVariant &id, bool enabled);
6790

6891
private:

0 commit comments

Comments
 (0)