WIP controller doc

Author: Skycoder42

AutoUpdater/updater.dox

@@ -156,7 +156,7 @@ See Updater::maintenanceToolPath for more details.
 @fn QtAutoUpdater::Updater::Updater(const QString &, QObject *)
 
 @overload
-@param maintenanceToolPath The path to the maintenancetool executable
+@param maintenanceToolPath The path to the maintenancetool
 @param parent The object parent for QObject
 
 The maintenancetool path will be set to the given one (and cannot be changed).

AutoUpdaterWidgets/updatecontroller.cpp

@@ -19,19 +19,19 @@ UpdateController::UpdateController(QObject *parent) :
 	d_ptr(new UpdateControllerPrivate(this, NULL))
 {}
 
-UpdateController::UpdateController(QWidget *parentWindow) :
-	QObject(parentWindow),
-	d_ptr(new UpdateControllerPrivate(this, parentWindow))
+UpdateController::UpdateController(QWidget *parentWidget) :
+	QObject(parentWidget),
+	d_ptr(new UpdateControllerPrivate(this, parentWidget))
 {}
 
 UpdateController::UpdateController(const QString &maintenanceToolPath, QObject *parent) :
 	QObject(parent),
 	d_ptr(new UpdateControllerPrivate(this, maintenanceToolPath, NULL))
 {}
 
-UpdateController::UpdateController(const QString &maintenanceToolPath, QWidget *parentWindow) :
-	QObject(parentWindow),
-	d_ptr(new UpdateControllerPrivate(this, maintenanceToolPath, parentWindow))
+UpdateController::UpdateController(const QString &maintenanceToolPath, QWidget *parentWidget) :
+	QObject(parentWidget),
+	d_ptr(new UpdateControllerPrivate(this, maintenanceToolPath, parentWidget))
 {}
 
 UpdateController::~UpdateController()
@@ -81,6 +81,7 @@ void UpdateController::setRunAsAdmin(bool runAsAdmin, bool userEditable)
 		d->runAdmin = runAsAdmin;
 		if(d->mainUpdater->willRunOnExit())
 			d->mainUpdater->runUpdaterOnExit(d->runAdmin ? new AdminAuthorization() : NULL);
+		emit runAsAdminChanged(runAsAdmin);
 	}
 	d->adminUserEdit = userEditable;
 }
@@ -222,7 +223,14 @@ void UpdateController::checkUpdatesDone(bool hasUpdates, bool hasError)
 		if(hasUpdates) {
 			if(d->displayLevel >= InfoLevel) {
 				bool shouldShutDown = false;
-				switch(d->infoDialog->showUpdateInfo(d->mainUpdater->updateInfo(), d->runAdmin, d->adminUserEdit)) {
+				bool oldRunAdmin = d->runAdmin;
+				UpdateInfoDialog::DialogResult res = d->infoDialog->showUpdateInfo(d->mainUpdater->updateInfo(),
+																				   d->runAdmin,
+																				   d->adminUserEdit);
+				if(d->runAdmin != oldRunAdmin)
+					emit runAsAdminChanged(d->runAdmin);
+
+				switch(res) {
 				case UpdateInfoDialog::InstallNow:
 					shouldShutDown = true;
 				case UpdateInfoDialog::InstallLater:

AutoUpdaterWidgets/updatecontroller.dox

@@ -118,6 +118,17 @@ int main(int argc, char *argv[])
 @endcode
 */
 
+/*!
+@enum QtAutoUpdater::UpdateController::DisplayLevel
+
+The display level controlls the kind of dialogs shown to the user. Levels are ranked from
+the lowest (`AutomaticLevel = 0`) to the highest (`AskLevel = 5`). Each Level includes all
+levels with a smaller value, i.e. using the `AskLevel` will add the ask dialog to everything
+shown with `ProgressLevel`, but not less.
+
+@sa @ref image_page "Image Page"
+*/
+
 /*!
 @property QtAutoUpdater::UpdateController::maintenanceToolPath
 
@@ -136,7 +147,7 @@ documentation of that property for more details.
 */
 
 /*!
-@property QtAutoUpdater::Updater::running
+@property QtAutoUpdater::UpdateController::running
 
 @default{`false`}
 
@@ -154,7 +165,7 @@ property of the attached updater can return `false` while this one returns `true
 */
 
 /*!
-@property QtAutoUpdater::Updater::runAsAdmin
+@property QtAutoUpdater::UpdateController::runAsAdmin
 
 @default{`true`}
 
@@ -169,7 +180,177 @@ the write accessor function of this property.
 @accessors{
 	@readAc{runAsAdmin()}
 	@writeAc{setRunAsAdmin()}
+	@notifyAc{runAsAdminChanged()}
 }
 
-@sa UpdateController::getUpdater, UpdateController::start, UpdateController::cancelUpdate
+@sa UpdateController::setRunAsAdmin, UpdateController::updateRunArgs
+*/
+
+/*!
+@property QtAutoUpdater::UpdateController::updateRunArgs
+
+@default{`{"--updater"}`}
+
+These arguments will be used to invoke the updater with it on exit (if updates are
+available). See Updater::runUpdaterOnExit(AdminAuthoriser *) for more details about
+"running on exit". If UpdateController::runAsAdmin is set to `true`, the maintenancetool
+will be run with elevated rights.
+
+@accessors{
+	@readAc{updateRunArgs()}
+	@writeAc{setUpdateRunArgs()}
+	@resetAc{resetUpdateRunArgs()}
+}
+
+@sa UpdateController::runAsAdmin, Updater::runUpdaterOnExit(AdminAuthoriser *)
+*/
+
+/*!
+@fn QtAutoUpdater::UpdateController::UpdateController(QObject *)
+
+@overload
+@param parent The parent object. Will serve as parent for the controller
+
+The created controller will not be bound to a specific window. Instead, all it's dialogs
+will be top-level windows without a parent and application modal.
+
+@note If you set `parent` to anything but `NULL`, make shure the parent object lives long
+enough for the controller to receive the QCoreApplication::aboutToQuit signal, since thats
+required for the updater to show the maintenancetool as updater.
+
+@overloads{
+	@povElem{UpdateController(QObject *)}
+	@povElem{UpdateController(QWidget *)}
+	@ovElem{UpdateController(const QString &, QObject *)}
+	@ovElem{UpdateController(const QString &, QWidget *)}
+}
+
+@sa QObject::parent, UpdateController::setParent(QObject *)
+*/
+
+/*!
+@fn QtAutoUpdater::UpdateController::UpdateController(QWidget *)
+
+@overload
+@param parentWidget The parent widget. Will serve as parent for the controller and windows
+
+The created controller will be bound to the widget. This means all dialogs will be child
+windows of the widgets window. On Mac, dialogs will be shown as "Sheets" of the parent
+window.
+
+@note If you set `parent` to anything but `NULL`, make shure the parent object lives long
+enough for the controller to receive the QCoreApplication::aboutToQuit signal, since thats
+required for the updater to show the maintenancetool as updater.
+
+@overloads{
+	@povElem{UpdateController(QObject *)}
+	@povElem{UpdateController(QWidget *)}
+	@ovElem{UpdateController(const QString &, QObject *)}
+	@ovElem{UpdateController(const QString &, QWidget *)}
+}
+
+@sa UpdateController::parentWidget, UpdateController::setParent(QWidget *)
+*/
+
+/*!
+@fn QtAutoUpdater::UpdateController::UpdateController(const QString &, QObject *)
+
+@overload
+@param maintenanceToolPath The path to the maintenancetool
+@param parent The parent object. Will serve as parent for the controller
+
+The maintenancetool path will be set to the given one (and cannot be changed). See
+UpdateController::maintenanceToolPath for more details.
+
+@overloads{
+	@povElem{UpdateController(QObject *)}
+	@povElem{UpdateController(QWidget *)}
+	@ovElem{UpdateController(const QString &, QObject *)}
+	@ovElem{UpdateController(const QString &, QWidget *)}
+}
+
+@sa QObject::parent, UpdateController::setParent(QObject *), UpdateController::maintenanceToolPath
+*/
+
+/*!
+@fn QtAutoUpdater::UpdateController::UpdateController(const QString &, QWidget *)
+
+@overload
+@param maintenanceToolPath The path to the maintenancetool
+@param parentWidget The parent widget. Will serve as parent for the controller and windows
+
+The maintenancetool path will be set to the given one (and cannot be changed). See
+UpdateController::maintenanceToolPath for more details.
+
+@overloads{
+	@povElem{UpdateController(QObject *)}
+	@povElem{UpdateController(QWidget *)}
+	@ovElem{UpdateController(const QString &, QObject *)}
+	@ovElem{UpdateController(const QString &, QWidget *)}
+}
+
+@sa UpdateController::parentWidget, UpdateController::setParent(QWidget *), UpdateController::maintenanceToolPath
+*/
+
+/*!
+@fn QtAutoUpdater::UpdateController::getUpdateAction
+
+@returns The action associated with this controller
+
+The action will automatically start the controller with the display-level
+`UpdateController::ProgressLevel`. In addition to that, the action will be automatically
+disabled if the controller is already running. For images check the
+@ref image_page "Image Page".
+
+The action has a text, an icon and a tooltip. The icon is set to be only visibile in a
+toolbar, not in a menu. On Mac, the action will be place in the Applications menu if
+added to the Menubar.
+
+@attention This function will always return the same QAction object for each controller.
+Thus, you may never delete the action. It will be deleted on destruction of the the
+controller. Take in mind that any change you make to this action (for example change the
+icon) will thus be that way for *all* components that use this action.
+
+@sa UpdateController::createUpdatePanel, @ref image_page "Image Page"
+*/
+
+/*!
+@fn QtAutoUpdater::UpdateController::createUpdatePanel
+
+@param parentWidget The parent widget of the update panel widget
+@returns The action associated with this controller
+
+The UpdatePanel is a ready-made "button" to check for updates. It is connected to this
+controller and thus will automatically start checking for updates with the level
+`UpdateController::ExtendedInfoLevel`. Since the panel itself shows a progress, no progress
+dialog is needed here. For images check the @ref image_page "Image Page".
+
+The panel will represent the controllers state and automatically enable/disable itself to
+avoid start beeing called twice. In addition to that, the whole panel widget will be disabled
+if the controller gets deleted while the panel is still existings. (Even if it wasn't,
+it will not crash if the button is clicked).
+
+@note The UpdatePanel class itself is an internal class. Reason: It directly derives from
+QWidget and does not add any new public accessible functions. Thus, even if the class would
+be returned, there would be no difference to a QWidget except of the pointer type.
+
+@sa UpdateController::getUpdateAction, @ref image_page "Image Page"
+*/
+
+/*!
+@fn QtAutoUpdater::UpdateController::setRunAsAdmin
+
+<b>Property: UpdateController::runAsAdmin</b>
+
+@param runAsAdmin `true`, if the maintenancetool should be run as admin/root, `false` to
+run it with the rights of the current user
+@param userEditable If set to `true`, the user can change this value in the info dialog.
+If set to `false`, he will not be able to do so
+
+The second parameter allows you to disable the change of this property by the user. If
+`userEditable` is true, the user can check/uncheck a checkbox in the info dialog. If
+`false`, this checkbox will be disabled. (The user can see the required rights, but not
+change them)
+
+@sa UpdateController::runAsAdmin
 */

AutoUpdaterWidgets/updatecontroller.h

@@ -21,30 +21,32 @@ namespace QtAutoUpdater
 		//! Specifies whether the controller is currently active or not
 		Q_PROPERTY(bool running READ isRunning NOTIFY runningChanged)
 		//! Specifies whether the controller should run the updater as admin or not
-		Q_PROPERTY(bool runAsAdmin READ runAsAdmin WRITE setRunAsAdmin)
+		Q_PROPERTY(bool runAsAdmin READ runAsAdmin WRITE setRunAsAdmin NOTIFY runAsAdminChanged)
 		//! Holds the arguments to invoke the updater with
 		Q_PROPERTY(QStringList updateRunArgs READ updateRunArgs WRITE setUpdateRunArgs RESET resetUpdateRunArgs)
 
 	public:
 		//! Defines the different display-levels of the dialog
 		enum DisplayLevel {
 			AutomaticLevel = 0,//!< The lowest level. Nothing will be displayed at all.
-			ExitLevel = 1,//!< The whole updating works completly automatically. Only a notification that updates are ready to install will be shown.
-			InfoLevel = 2,//!< Will show information about updates if available, nothing otherwise
-			ExtendedInfoLevel = 3,//!< Will shwo information about the update result, for both cases, updates and no updates
-			ProgressLevel = 4,//!< Shows a (modal) progress dialog while checking for updates
-			AskLevel = 5//!< The highest level. Will ask the user if he wants to check for updates before actually checking
+			ExitLevel = 1,/*!< The whole updating works completly automatically without displaying anything. Only
+						   *   a notification that updates are ready to install will be shown if updates are available.
+						   */
+			InfoLevel = 2,//!< Will show information about updates if available, nothing otherwise.
+			ExtendedInfoLevel = 3,//!< Will show information about the update result, for both cases, updates and no updates.
+			ProgressLevel = 4,//!< Shows a (modal) progress dialog while checking for updates.
+			AskLevel = 5//!< The highest level. Will ask the user if he wants to check for updates before actually checking.
 		};
 		Q_ENUM(DisplayLevel)
 
 		//! Constructs a new controller with a parent. Will be application modal
 		explicit UpdateController(QObject *parent = NULL);
 		//! Constructs a new controller with a parent. Will modal to the parent window
-		explicit UpdateController(QWidget *parentWindow);
+		explicit UpdateController(QWidget *parentWidget);
 		//! Constructs a new controller with an explicitly set path and a parent. Will modal to the parent window
 		explicit UpdateController(const QString &maintenanceToolPath, QObject *parent = NULL);
 		//! Constructs a new controller with an explicitly set path and a parent. Will be application modal
-		explicit UpdateController(const QString &maintenanceToolPath, QWidget *parentWindow);
+		explicit UpdateController(const QString &maintenanceToolPath, QWidget *parentWidget);
 		//! Destructor
 		~UpdateController();
 
@@ -102,6 +104,8 @@ namespace QtAutoUpdater
 	signals:
 		//! NOTIFY-Accessor for UpdateController::running
 		void runningChanged(bool running);
+		//! NOTIFY-Accessor for UpdateController::runAsAdmin
+		void runAsAdminChanged(bool runAsAdmin);
 
 	private slots:
 		void checkUpdatesDone(bool hasUpdates, bool hasError);

AutoUpdaterWidgets/updateinfodialog.h

@@ -26,6 +26,7 @@ namespace QtAutoUpdater
 
 		void setNewParent(QWidget *parent);
 
+		//TODO make static
 		DialogResult showUpdateInfo(QList<Updater::UpdateInfo> updates, bool &runAsAdmin, bool editable);
 
 	private slots:

AutoUpdaterWidgets/updatepanel.cpp

@@ -26,6 +26,10 @@ UpdatePanel::UpdatePanel(UpdateController *controller, QWidget *parent) :
 			this, &UpdatePanel::changeUpdaterState);
 	connect(this->controller->getUpdater(), &Updater::checkUpdatesDone,
 			this, &UpdatePanel::updatesReady);
+	connect(this->controller, &UpdateController::destroyed,
+			this, [this](){
+		this->setDisabled(true);
+	});
 }
 
 UpdatePanel::~UpdatePanel()
@@ -35,7 +39,8 @@ UpdatePanel::~UpdatePanel()
 
 void UpdatePanel::startUpdate()
 {
-	this->controller->start(UpdateController::ExtendedInfoLevel);
+	if(!this->controller.isNull())
+		this->controller->start(UpdateController::ExtendedInfoLevel);
 }
 
 void UpdatePanel::changeUpdaterState(bool isRunning)

AutoUpdaterWidgets/updatepanel.h

@@ -2,6 +2,7 @@
 #define UPDATEPANEL_H
 
 #include <QWidget>
+#include <QPointer>
 #include <QMovie>
 
 namespace Ui {
@@ -25,7 +26,7 @@ namespace QtAutoUpdater
 		void updatesReady(bool hasUpdate, bool);
 
 	private:
-		UpdateController *controller;
+		QPointer<UpdateController> controller;
 		Ui::UpdatePanel *ui;
 		QMovie *loadingGif;
 	};