An interface to implement and consume custom in-process installer. More...

#include <updateinstaller.h>

Inheritance diagram for QtAutoUpdater::UpdateInstaller:

Public Types
enum	Feature { Feature::None = 0x00, Feature::SelectComponents = 0x01, Feature::DetailedProgress = 0x02, Feature::CanCancel = 0x04 }
	Various features an installer may or may not support. More...

Public Slots
virtual void	startInstall ()
	Is called to start the actual installation with the current components. More...

virtual void	cancelInstall ()
	Is called to cancel an ongoing installation. More...

virtual void	eulaHandled (const QVariant &id, bool accepted)=0
	Is called to report the result of a user accepting or rejecting a required EULA. More...

virtual void	restartApplication ()
	Is called to restart the application. More...

virtual void	setComponents (QList< QtAutoUpdater::UpdateInfo > components)
	WRITE accessor for UpdateInstaller::components.

Signals
void	updateGlobalProgress (double progress, const QString &status={})
	Is emitted to report the global, overall progress and status of the installation. More...

void	updateComponentProgress (const QVariant &id, double progress, const QString &status={})
	Is emitted to report the progress and status of a single component beeing updated. More...

void	showEula (const QVariant &id, const QString &htmlText, bool required)
	Is emitted if a EULA must be shown to the user. More...

void	installSucceeded (bool shouldRestart)
	Is emitted when the installation has succeeded. More...

void	installFailed (const QString &errorMessage)
	Is emitted when the installation has failed. More...

void	componentsChanged ()
	NOTIFY accessor for UpdateInstaller::components.

Public Member Functions
virtual Features	features () const =0
	READ accessor for UpdateInstaller::features.

virtual QList< UpdateInfo >	components () const
	READ accessor for UpdateInstaller::components.

virtual QAbstractItemModel *	componentModel () const
	READ accessor for UpdateInstaller::componentModel.

virtual QAbstractItemModel *	progressModel () const
	READ accessor for UpdateInstaller::progressModel.

Public Member Functions inherited from QObject
virtual const QMetaObject *	metaObject () const const

	QObject (QObject *parent)

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

QString	objectName () const const

void	setObjectName (const QString &name)

bool	isWidgetType () const const

bool	isWindowType () const const

bool	signalsBlocked () const const

bool	blockSignals (bool block)

QThread *	thread () const const

void	moveToThread (QThread *targetThread)

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)

void	killTimer (int id)

T	findChild (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const

const QObjectList &	children () const const

void	setParent (QObject *parent)

void	installEventFilter (QObject *filterObj)

void	removeEventFilter (QObject *obj)

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const const

bool	disconnect (const char signal, const QObject receiver, const char *method) const const

bool	disconnect (const QObject receiver, const char method) const const

void	dumpObjectTree ()

void	dumpObjectInfo ()

void	dumpObjectTree () const const

void	dumpObjectInfo () const const

bool	setProperty (const char *name, const QVariant &value)

QVariant	property (const char *name) const const

QList< QByteArray >	dynamicPropertyNames () const const

void	destroyed (QObject *obj)

void	objectNameChanged (const QString &objectName)

QObject *	parent () const const

bool	inherits (const char *className) const const

void	deleteLater ()

	Q_DISABLE_COPY (Class)

	Q_DISABLE_MOVE (Class)

	Q_DISABLE_COPY_MOVE (Class)

T	qobject_cast (QObject *object)

T	qobject_cast (const QObject *object)

T	qFindChild (const QObject *obj, const QString &name)

QList< T >	qFindChildren (const QObject *obj, const QString &name)

QList< T >	qFindChildren (const QObject *obj, const QRegExp &regExp)

	Q_CLASSINFO (Name, Value)

	Q_INTERFACES (...)

	Q_PROPERTY (...)

	Q_ENUMS (...)

	Q_FLAGS (...)

	Q_ENUM (...)

	Q_FLAG (...)

	Q_ENUM_NS (...)

	Q_FLAG_NS (...)

	Q_OBJECT Q_OBJECT

	Q_GADGET Q_GADGET

	Q_NAMESPACE Q_NAMESPACE

	Q_SIGNALS Q_SIGNALS

	Q_SIGNAL Q_SIGNAL

	Q_SLOTS Q_SLOTS

	Q_SLOT Q_SLOT

	Q_EMIT Q_EMIT

	Q_INVOKABLE Q_INVOKABLE

	Q_REVISION Q_REVISION

	Q_SET_OBJECT_NAME (Object)

	QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT

Protected Member Functions
	UpdateInstaller (QObject *parent=nullptr)
	Default constructor.

virtual void	startInstallImpl ()=0
	Internal method to actually start the installation. More...

virtual void	setComponentEnabled (const QVariant &id, bool enabled)
	Enables or disables a component for installation. More...

Protected Member Functions inherited from QObject
QObject *	sender () const const

int	senderSignalIndex () const const

int	receivers (const char *signal) const const

bool	isSignalConnected (const QMetaMethod &signal) const const

virtual void	timerEvent (QTimerEvent *event)

virtual void	childEvent (QChildEvent *event)

virtual void	customEvent (QEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	disconnectNotify (const QMetaMethod &signal)

Properties
QtAutoUpdater::UpdateInstaller::Features	features
	Holds the features this installer supports. More...

QList< QtAutoUpdater::UpdateInfo >	components
	The components to be installed. More...

QAbstractItemModel	componentModel
	An item model to let the user interactively select components to be installed. More...

QAbstractItemModel	progressModel
	An item model showing the progress and status of each update component being installed. More...

Properties inherited from QObject
	objectName

Additional Inherited Members
Static Public Member Functions inherited from QObject
QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

Public Attributes inherited from QObject
typedef	QObjectList

Detailed Description

An interface to implement and consume custom in-process installer.

This class can be used to perform an update of the application from within the running process, without the need of an external installer. It can also be used if an external installer provides enough details about an installation for them to be presented via this class.

Instances of the installer are provided via Updater::showInstaller if such an installer was selected by Updater::runUpdater. You can then use the public API of the installer to select components to be installed and perform their installation.

When implementing a custom updater backend, you can use this as abstract base class for a custom installer.

Note: Using such an installer requires the UpdaterBackend to have the UpdaterBackend::Feature::PerformInstall flag set.

See also: Updater, Updater::showInstaller, UpdaterBackend

Definition at line 17 of file updateinstaller.h.

Member Enumeration Documentation

◆ Feature

enum QtAutoUpdater::UpdateInstaller::Feature

strong

Various features an installer may or may not support.

Enumerator
None	The installer does not support any of the optional features.
SelectComponents	The installer allows the user to interactively select components.
DetailedProgress	The installer provides progress information for each component beeing installed.
CanCancel	The installation can be canceled.

Definition at line 32 of file updateinstaller.h.

Member Function Documentation

◆ cancelInstall

QtAutoUpdater::UpdateInstaller::cancelInstall ( )

virtualslot

Is called to cancel an ongoing installation.

Call this to abort an ongoing installation.

Note: For this method to ever be called, the Feature::DetailedProgress must be set in UpdateInstaller::features

Warning: Even if this is supported by a backend, cancelling can always have fatal repercussions on an installation and possibly corrupt it into an unrepairable state! When allowing users to cancel, always make them aware of this fact.

See also: UpdateInstaller::startInstall, UpdateInstaller::Feature, UpdateInstaller::features

◆ eulaHandled

QtAutoUpdater::UpdateInstaller::eulaHandled	(	const QVariant &	id,
		bool	accepted
	)

pure virtualslot

Is called to report the result of a user accepting or rejecting a required EULA.

Parameters

id	The id of the EULA that was passed to it's show request
accepted	true, if the user accepted the EULA, false if not

Call this method from a GUI to notify the installer that a required EULA was accepted or rejected.

For the implementation of this method, a rejected EULA should always lead to a failed installation.

See also: UpdateInstaller::showEula

◆ installFailed

QtAutoUpdater::UpdateInstaller::installFailed ( const QString & errorMessage )

signal

Is emitted when the installation has failed.

Parameters

errorMessage Specify whether the application should be restarted

Emit this from your custom installer on a failed installation. The errorMessage should be a localized string to describe what went wrong to the user. Do not include technical details there, only general information. Such details should be logged instead.

See also: UpdateInstaller::installSucceeded

◆ installSucceeded

QtAutoUpdater::UpdateInstaller::installSucceeded ( bool shouldRestart )

signal

Is emitted when the installation has succeeded.

Parameters

shouldRestart Specify whether the application should be restarted

Emit this from your custom installer on a successfully completed installation. If you set the shouldRestart to true, the user will be asked if he wants to restart the application. If he accepts, restartApplication() will be called to do so. Otherwise, the user is not presented the option and nothing happens.

See also: UpdateInstaller::installFailed, UpdateInstaller::restartApplication

◆ restartApplication

QtAutoUpdater::UpdateInstaller::restartApplication ( )

virtualslot

Is called to restart the application.

Implement this method if you are going to emit installSucceeded(true). The method should quit the current application and restart it, using the updated version of your application.

See also: UpdateInstaller::installSucceeded

◆ setComponentEnabled()

QtAutoUpdater::UpdateInstaller::setComponentEnabled	(	const QVariant &	id,
		bool	enabled
	)

protectedvirtual

Enables or disables a component for installation.

Parameters

id	The id of the component to be enabled or disabled
enabled	The new state of the component

Call this method from your custom componentModel to enable or disable components as done by the user. The id is the same as the UpdateInfo::identifier property of the UpdateInfo that represents that component. You can only enable/disable components that have been added to the installer via the components property.

Note: Disabled components will disappear from the components property, but still be settable via this method. To completely remove the, write the property instead.

See also: UpdateInstaller::components, UpdateInstaller::componentModel

◆ showEula

QtAutoUpdater::UpdateInstaller::showEula	(	const QVariant &	id,
		const QString &	htmlText,
		bool	required
	)

signal

Is emitted if a EULA must be shown to the user.

Parameters

id	An internally used id to identify the EULA
htmlText	The EULAs text, formatted as HTML-text
required	Specifies whether the EULA must be accepted or not

Emit this signal to make the user accept an EULA. The id is used internally and only actually needed for required EULAs, as it is passed to eulaHandled() to report the result. The text is interpreted as HTML, but should only consist of the HTML-subset supported by styled QML Labels.

If required is false, the EULA should only be shown to the user, but he doesn't have to accept it. If set true however, the user must accept the EULA and the result must be reported via eulaHandled().

Required EULAs should block the installation until accepted and their rejection should fail an installation.

See also: UpdateInstaller::eulaHandled

◆ startInstall

QtAutoUpdater::UpdateInstaller::startInstall ( )

virtualslot

Is called to start the actual installation with the current components.

Call this to start an installation.

Attention: Do not reimplement this method yourself unless you have a custom progressModel!!! Instead, implement startInstallImpl(), as that method is called directly from this one.

See also: UpdateInstaller::startInstallImpl, UpdateInstaller::progressModel

◆ startInstallImpl()

QtAutoUpdater::UpdateInstaller::startInstallImpl ( )

protectedpure virtual

Internal method to actually start the installation.

The actual method to start the installation. This should start whatever has to be done to perform the installation in a non-blocking manner.

See also: UpdateInstaller::startInstall, UpdateInstaller::installSucceeded, UpdateInstaller::installFailed, UpdateInstaller::updateGlobalProgress, UpdateInstaller::updateComponentProgress, UpdateInstaller::showEula

◆ updateComponentProgress

QtAutoUpdater::UpdateInstaller::updateComponentProgress	(	const QVariant &	id,
		double	progress,
		const QString &	status = `{}`
	)

signal

Is emitted to report the progress and status of a single component beeing updated.

Parameters

id	The id of the component
progress	The progress of the full installation
status	The current status of the installation

Emit this signal to give the user some feedback on the current state of a certain component that is part of the installation. The semantics are the same as for updateGlobalProgress(). The id is the same as the UpdateInfo::identifier property of the UpdateInfo that represents that component.

This signal is typically consumed by the progressModel, which displays it.

Note: This signal is ignored unless the Feature::DetailedProgress was set in UpdateInstaller::features

See also: UpdateInstaller::updateGlobalProgress, UpdateInstaller::progressModel

◆ updateGlobalProgress

QtAutoUpdater::UpdateInstaller::updateGlobalProgress	(	double	progress,
		const QString &	status = `{}`
	)

signal

Is emitted to report the global, overall progress and status of the installation.

Parameters

progress	The progress of the full installation
status	The current status of the installation

Emit this signal to give the user some feedback on the current state of the installation. percent can either range from 0.0 to 1.0 to present an actual percentage, or be -1.0 to represent an indeterminate progress. Status can be left empty to be unchanged/unset. Emitting this signal is optional, but recommended.

See also: UpdateInstaller::updateComponentProgress

Property Documentation

◆ componentModel

QtAutoUpdater::UpdateInstaller::componentModel

read

An item model to let the user interactively select components to be installed.

Default: <instance>

By default, the model provides the following roles and columns. Strings represent those accessible from QML via role names, others are enum values for access via C++.

Column	role	UpdateInfo property: type	writable
0	Qt::DisplayRole	name: QString	false
0	Qt::ToolTipRole	name: QString	false
0	Qt::CheckStateRole	<enabled>: Qt::CheckState	true
0	"name"	name: QString	false
0	"version"	version: QString	false
0	"selected"	<enabled>: bool	true
0	"updateInfo"	<gadget>: UpdateInfo	false
1	Qt::DisplayRole	version: QString	false
1	Qt::ToolTipRole	version: QString	false

However, backends can decide to provide additional/different columns and roles as well. The model should always provide a way for the user to enable or disable components.

Note: This model is useless unless the Feature::SelectComponents was set in UpdateInstaller::features

Accessors
READ	componentModel()
CONSTANT

See also: UpdateInstaller::components, UpdateInstaller::setComponentEnabled, UpdateInstaller::Feature, UpdateInstaller::features

Definition at line 26 of file updateinstaller.h.

◆ components

QtAutoUpdater::UpdateInstaller::components

readwrite

The components to be installed.

Default: <empty>

This property only returns enabled components. If a component was disabled by the user, it is not visible via this property. You can thuse use this to figure out which components are actually installed. When setting this property, all components set are marked as enabled and thus are visible through this property.

Accessors
READ	components()
WRITE	setComponents()
NOTIFY	componentsChanged()

See also: UpdateInstaller::componentModel, UpdateInstaller::setComponentEnabled

Definition at line 24 of file updateinstaller.h.

◆ features

QtAutoUpdater::UpdateInstaller::features

read

Holds the features this installer supports.

Default: UpdateInstaller::Feature::None

The flags indicate which features are supported and which are not.

Accessors
READ	features()
CONSTANT

See also: UpdateInstaller::Feature, UpdaterBackend::features()

Definition at line 22 of file updateinstaller.h.

◆ progressModel

QtAutoUpdater::UpdateInstaller::progressModel

read

An item model showing the progress and status of each update component being installed.

Default: <instance>

By default, the model provides the following roles and columns. Strings represent those accessible from QML via role names, others are enum values for access via C++. None are writable. "progress" and "status" are special properties that can be set via updateComponentProgress()

Column	role	UpdateInfo property: type
0	Qt::DisplayRole	name: QString
0	Qt::ToolTipRole	name: QString
0	"name"	name: QString
0	"progress"	progress: double
0	"status"	status: QString
0	"updateInfo"	<gadget>: UpdateInfo
1	Qt::DisplayRole	status: QString
1	Qt::ToolTipRole	status: QString
2	Qt::DisplayRole	progress: double
2	Qt::ToolTipRole	progress: double

However, backends can decide to provide additional/different columns and roles as well. The model should connect to the updateComponentProgress() signal to be able to catch the progress of components and should always display those in some way via the model.

Note: This model is useless unless the Feature::DetailedProgress was set in UpdateInstaller::features

Accessors
READ	progressModel()
CONSTANT

See also: UpdateInstaller::updateComponentProgress, UpdateInstaller::Feature, UpdateInstaller::features

Definition at line 28 of file updateinstaller.h.

The documentation for this class was generated from the following files:

updateinstaller.h
updateinstaller.dox

Public Types

Public Slots

Signals

Public Member Functions

Protected Member Functions

Properties

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Feature

Member Function Documentation

◆ cancelInstall

◆ eulaHandled

◆ installFailed

◆ installSucceeded

◆ restartApplication

◆ setComponentEnabled()

◆ showEula

◆ startInstall

◆ startInstallImpl()

◆ updateComponentProgress

◆ updateGlobalProgress

Property Documentation

◆ componentModel

◆ components

◆ features

◆ progressModel