Skip to content

Commit 075da23

Browse files
Skycoder42Skycoder42
committed
start doc controller, added images win
1 parent bbc041d commit 075da23

16 files changed

+135
-54
lines changed

‎AutoUpdater/updater.dox‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ evalute the results of the tool and generate update information of it. In additi
3030
it can schedule the maintenancetool to run in updater mode as soon as the application
3131
finishes. (This requires the Updater instance to exist until QCoreApplication::quit is called).
3232

33-
### Example:
33+
## Example
3434
The following example shows the basic usage of the updater. It creates a new updater
3535
instance that is connected to the maintenancetool located at "./maintenancetool". As
3636
soon as the application starts, it will check for updates and print the update result.
@@ -80,21 +80,18 @@ int main(int argc, char *argv[])
8080
/*!
8181
@property QtAutoUpdater::Updater::maintenanceToolPath
8282

83-
@default{"./maintenancetool"}
83+
@default{"./maintenancetool" on Windows/X11, "../../maintenancetool" on mac}
8484

8585
The path of the maintenancetool has to be set inside of the constructor and cannot be
8686
changed later.<br>
8787
The path will be assumed relative to QCoreApplication::applicationDirPath(), the location
8888
of the currently running application.
8989

90-
@note On Mac, the current path will be the AppFolder, for example:
91-
<i>/Applications/MyApp.app</i> instead off <i>/Applications/MyApp.app/Contents/MacOS</i>
92-
9390
The updater will check whether or not the given path has a file-extension. If not, it
9491
will try to add the given extension. This will result into:
9592

9693
- **Windows**: "./maintenancetool.exe"
97-
- **Mac**: "./maintenancetool.app/Content/MacOS/maintenancetool"
94+
- **Mac**: "../../maintenancetool.app/Content/MacOS/maintenancetool"
9895
- **X11**: "./maintenancetool" (unchanged)
9996

10097
@accessors{

‎AutoUpdater/updater.h‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,6 @@ struct QVersionNumber : public QString {
2121

2222
namespace QtAutoUpdater
2323
{
24-
//! @internal Private implementation
2524
class UpdaterPrivate;
2625
//! The main updater. Can check for updates and run the updater
2726
class Updater : public QObject

‎AutoUpdaterWidgets/AutoUpdaterWidgets.pro‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,4 +41,5 @@ FORMS += \
4141
RESOURCES += \
4242
autoupdaterwidgets_resource.qrc
4343

44-
DISTFILES +=
44+
DISTFILES += \
45+
updatecontroller.dox

‎AutoUpdaterWidgets/updatecontroller.dox‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
/*!
2+
@class QtAutoUpdater::UpdateController
3+
4+
The update-controller is a helpful tool if you want to show a simple GUI to the users.
5+
It offers an automated update process, controlled by the user. All thats left for you
6+
to do is starting this controller. This can be done in 4 ways:
7+
- Call UpdateController::start somewhere in your code
8+
- Schedule an update using UpdateController::scheduleUpdate(UpdateTask *, DisplayLevel)
9+
- Add the QAction returned by UpdateController::getUpdateAction somewhere in your gui
10+
- Add the widget returned by UpdateController::createUpdatePanel somewhere in your gui
11+
12+
## Images
13+
<comming soon>
14+
15+
## Example
16+
This example will show you the full capability of the controller. Since there is no
17+
mainwindow in this example, you will only see the controller dialogs. Please not that
18+
you can control how much of that dialogset will be shown to the user. This example is
19+
reduced! for a full example with all parts of the controller, check the
20+
Tests/WidegtsTest application.
21+
22+
@attention Since this library requires the maintenancetool that is deployed with every
23+
Qt Installer Framework installation, the examples cannot be tested without a
24+
maintenancetool! If you intend to use this library, the maintenancetool will be
25+
available for your final application. For testing purpose or the examples, I set the
26+
path to the MaintenanceTool that is deployed with the installation of Qt (since you
27+
all should have at least that one). So make shure to adjust the path if you try to run
28+
the example.
29+
30+
@code{.cpp}
31+
#include <QApplication>
32+
#include <updatecontroller.h>
33+
34+
int main(int argc, char *argv[])
35+
{
36+
QApplication a(argc, argv);
37+
//Since there is no mainwindow, the various dialogs should not quit the app
38+
QApplication::setQuitOnLastWindowClosed(false);
39+
//create the update controller with the application as parent -> will live long enough start the tool on exit
40+
//since the parent is not a widget, all dialogs will be top-level windows
41+
//QtAutoUpdater::UpdateController *controller = new QtAutoUpdater::UpdateController(&a);
42+
QtAutoUpdater::UpdateController *controller = new QtAutoUpdater::UpdateController("C:/Qt/MaintenanceTool", &a);//.exe is automatically added
43+
44+
QObject::connect(updater, &QtAutoUpdater::UpdateController::runningChanged, [updater](bool running) {
45+
qDebug() << "Running changed:" << running;
46+
//quit the application as soon as the updating finished
47+
if(!running)
48+
qApp->quit();
49+
});
50+
51+
//start the update check -> AskLevel to give the user maximum control
52+
controller->start(QtAutoUpdater::UpdateController::AskLevel);
53+
return a.exec();
54+
}
55+
@endcode
56+
*/

‎AutoUpdaterWidgets/updatecontroller.h‎

Lines changed: 36 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,61 +9,91 @@
99
namespace QtAutoUpdater
1010
{
1111
class Updater;
12+
//! @internal Private implementation
1213
class UpdateControllerPrivate;
14+
//! A class to show a controlled update GUI to the user
1315
class UpdateController : public QObject
1416
{
1517
Q_OBJECT
1618

19+
//! Holds the path of the attached maintenancetool
1720
Q_PROPERTY(QString maintenanceToolPath READ maintenanceToolPath CONSTANT)
21+
//! Specifies whether the controller is currently active or not
1822
Q_PROPERTY(bool running READ isRunning NOTIFY runningChanged)
23+
//! Specifies whether the controller should run the updater as admin or not
1924
Q_PROPERTY(bool runAsAdmin READ runAsAdmin WRITE setRunAsAdmin)
25+
//! Holds the arguments to invoke the updater with
2026
Q_PROPERTY(QStringList updateRunArgs READ updateRunArgs WRITE setUpdateRunArgs RESET resetUpdateRunArgs)
2127

2228
public:
29+
//! Defines the different display-levels of the dialog
2330
enum DisplayLevel {
24-
AutomaticLevel = 0,
25-
ExitLevel = 1,
26-
InfoLevel = 2,
27-
ExtendedInfoLevel = 3,
28-
ProgressLevel = 4,
29-
AskLevel = 5
31+
AutomaticLevel = 0,//!< The lowest level. Nothing will be displayed at all.
32+
ExitLevel = 1,//!< The whole updating works completly automatically. Only a notification that updates are ready to install will be shown.
33+
InfoLevel = 2,//!< Will show information about updates if available, nothing otherwise
34+
ExtendedInfoLevel = 3,//!< Will shwo information about the update result, for both cases, updates and no updates
35+
ProgressLevel = 4,//!< Shows a (modal) progress dialog while checking for updates
36+
AskLevel = 5//!< The highest level. Will ask the user if he wants to check for updates before actually checking
3037
};
3138
Q_ENUM(DisplayLevel)
3239

40+
//! Constructs a new controller with a parent. Will be application modal
3341
explicit UpdateController(QObject *parent = NULL);
42+
//! Constructs a new controller with a parent. Will modal to the parent window
3443
explicit UpdateController(QWidget *parentWindow);
44+
//! Constructs a new controller with an explicitly set path and a parent. Will modal to the parent window
3545
explicit UpdateController(const QString &maintenanceToolPath, QObject *parent = NULL);
46+
//! Constructs a new controller with an explicitly set path and a parent. Will be application modal
3647
explicit UpdateController(const QString &maintenanceToolPath, QWidget *parentWindow);
48+
//! Destructor
3749
~UpdateController();
3850

51+
//! Returns an QAction to start this controller from
3952
QAction *getUpdateAction() const;
53+
//! Creates a new "UpdatePanel" widget to place in your GUI
4054
QWidget *createUpdatePanel(QWidget *parentWidget);
4155

56+
//! READ-Accessor for UpdateController::maintenanceToolPath
4257
QString maintenanceToolPath() const;
58+
//! READ-Accessor for UpdateController::currentDisplayLevel
4359
DisplayLevel currentDisplayLevel() const;
60+
//! READ-Accessor for UpdateController::running
4461
bool isRunning() const;
62+
//! READ-Accessor for UpdateController::runAsAdmin
4563
bool runAsAdmin() const;
64+
//! WRITE-Accessor for UpdateController::runAsAdmin
4665
void setRunAsAdmin(bool runAsAdmin, bool userEditable = true);
66+
//! READ-Accessor for UpdateController::updateRunArgs
4767
QStringList updateRunArgs() const;
68+
//! WRITE-Accessor for UpdateController::updateRunArgs
4869
void setUpdateRunArgs(QStringList updateRunArgs);
70+
//! RESET-Accessor for UpdateController::updateRunArgs
4971
void resetUpdateRunArgs();
5072

73+
//! Returns the Updater object used by the controller
5174
Updater *getUpdater() const;
5275

5376
public slots:
77+
//! Starts the controller with the specified level.
5478
bool start(DisplayLevel displayLevel = ProgressLevel);
79+
//! Tries to cancel the controllers update
5580
bool cancelUpdate(int maxDelay = 3000);
5681

82+
//! Schedules an update after a specific delay, optionally repeated
5783
inline int scheduleUpdate(qint64 delayMinutes, bool repeated = false, DisplayLevel displayLevel = InfoLevel) {
5884
return this->scheduleUpdate(new BasicLoopUpdateTask(TimeSpan(delayMinutes, TimeSpan::Minutes), repeated ? -1 : 1), displayLevel);
5985
}
86+
//! Schedules an update for a specific timepoint
6087
inline int scheduleUpdate(const QDateTime &when, DisplayLevel displayLevel = InfoLevel) {
6188
return this->scheduleUpdate(new TimePointUpdateTask(when), displayLevel);
6289
}
90+
//! Schedules an update using an UpdateTask
6391
int scheduleUpdate(UpdateTask *task, DisplayLevel displayLevel = InfoLevel);
92+
//! Cancels the update with taskId
6493
void cancelScheduledUpdate(int taskId);
6594

6695
signals:
96+
//! NOTIFY-Accessor for UpdateController::running
6797
void runningChanged(bool running);
6898

6999
private slots:

‎doc/QtAutoUpdater.doxy‎

Lines changed: 38 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -792,19 +792,17 @@ WARN_LOGFILE =
792792
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
793793
# Note: If this tag is empty the current directory is searched.
794794

795-
INPUT = ../AutoUpdater/adminauthoriser.h \
795+
INPUT = ../README.md \
796796
../AutoUpdater/updater.h \
797+
../AutoUpdater/updater.dox \
798+
../AutoUpdater/adminauthoriser.h \
799+
../AutoUpdater/adminauthoriser.dox \
797800
../AutoUpdater/updatetask.h \
798-
../AutoUpdaterWidgets/updatecontroller.h \
799-
../README.md \
800-
../AutoUpdater/adminauthoriser.dox \
801-
../AutoUpdater/adminauthoriser.h \
802-
../AutoUpdater/updater.dox \
803-
../AutoUpdater/adminauthoriser.h \
804-
../AutoUpdater/updatetask.dox \
805-
../AutoUpdater/updateschedulercontroller.h \
806-
../AutoUpdater/adminauthoriser.h \
807-
../AutoUpdater/updateschedulercontroller.dox
801+
../AutoUpdater/updatetask.dox \
802+
../AutoUpdater/updateschedulercontroller.h \
803+
../AutoUpdater/updateschedulercontroller.dox \
804+
../AutoUpdaterWidgets/updatecontroller.h \
805+
../AutoUpdaterWidgets/updatecontroller.dox
808806

809807
# This tag can be used to specify the character encoding of the source files
810808
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -2140,35 +2138,35 @@ SKIP_FUNCTION_MACROS = YES
21402138
# run, you must also specify the path to the tagfile here.
21412139

21422140
TAGFILES = C:/Qt/Docs/Qt-5.5/qtwebengine/qtwebengine.tags=http://doc.qt.io/qt-5 \
2143-
C:/Qt/Docs/Qt-5.5/qtgraphicaleffects/qtgraphicaleffects.tags=http://doc.qt.io/qt-5 \
2144-
C:/Qt/Docs/Qt-5.5/qt3dcollision/qt3dcollision.tags=http://doc.qt.io/qt-5 \
2145-
C:/Qt/Docs/Qt-5.5/qt3dlogic/qt3dlogic.tags=http://doc.qt.io/qt-5 \
2146-
C:/Qt/Docs/Qt-5.5/qt3dcore/qt3dcore.tags=http://doc.qt.io/qt-5 \
2147-
C:/Qt/Docs/Qt-5.5/qt3drenderer/qt3drenderer.tags=http://doc.qt.io/qt-5 \
2148-
C:/Qt/Docs/Qt-5.5/qtwebchannel/qtwebchannel.tags=http://doc.qt.io/qt-5 \
2149-
C:/Qt/Docs/Qt-5.5/qtwebsockets/qtwebsockets.tags=http://doc.qt.io/qt-5 \
2150-
C:/Qt/Docs/Qt-5.5/qtbluetooth/qtbluetooth.tags=http://doc.qt.io/qt-5 \
2151-
C:/Qt/Docs/Qt-5.5/qtnfc/qtnfc.tags=http://doc.qt.io/qt-5 \
2152-
C:/Qt/Docs/Qt-5.5/qtsensors/qtsensors.tags=http://doc.qt.io/qt-5 \
2153-
C:/Qt/Docs/Qt-5.5/qtlocation/qtlocation.tags=http://doc.qt.io/qt-5 \
2154-
C:/Qt/Docs/Qt-5.5/qtpositioning/qtpositioning.tags=http://doc.qt.io/qt-5 \
2155-
C:/Qt/Docs/Qt-5.5/activeqt/activeqt.tags=http://doc.qt.io/qt-5 \
2156-
C:/Qt/Docs/Qt-5.5/qtquickcontrols/qtquickcontrols.tags=http://doc.qt.io/qt-5 \
2157-
C:/Qt/Docs/Qt-5.5/qtqml/qtqml.tags=http://doc.qt.io/qt-5 \
2158-
C:/Qt/Docs/Qt-5.5/qtquick/qtquick.tags=http://doc.qt.io/qt-5 \
2159-
C:/Qt/Docs/Qt-5.5/qtxmlpatterns/qtxmlpatterns.tags=http://doc.qt.io/qt-5 \
2160-
C:/Qt/Docs/Qt-5.5/qtsvg/qtsvg.tags=http://doc.qt.io/qt-5 \
2161-
C:/Qt/Docs/Qt-5.5/qdoc/qdoc.tags=http://doc.qt.io/qt-5 \
2162-
C:/Qt/Docs/Qt-5.5/qtprintsupport/qtprintsupport.tags=http://doc.qt.io/qt-5 \
2163-
C:/Qt/Docs/Qt-5.5/qtconcurrent/qtconcurrent.tags=http://doc.qt.io/qt-5 \
2164-
C:/Qt/Docs/Qt-5.5/qtgui/qtgui.tags=http://doc.qt.io/qt-5 \
2165-
C:/Qt/Docs/Qt-5.5/qttestlib/qttestlib.tags=http://doc.qt.io/qt-5 \
2166-
C:/Qt/Docs/Qt-5.5/qtwidgets/qtwidgets.tags=http://doc.qt.io/qt-5 \
2167-
C:/Qt/Docs/Qt-5.5/qtcore/qtcore.tags=http://doc.qt.io/qt-5 \
2168-
C:/Qt/Docs/Qt-5.5/qtnetwork/qtnetwork.tags=http://doc.qt.io/qt-5 \
2169-
C:/Qt/Docs/Qt-5.5/qtsql/qtsql.tags=http://doc.qt.io/qt-5 \
2170-
C:/Qt/Docs/Qt-5.5/qtxml/qtxml.tags=http://doc.qt.io/qt-5 \
2171-
C:/Qt/Docs/Qt-5.5/qtwebenginewidgets/qtwebenginewidgets.tags=http://doc.qt.io/qt-5
2141+
C:/Qt/Docs/Qt-5.5/qtgraphicaleffects/qtgraphicaleffects.tags=http://doc.qt.io/qt-5 \
2142+
C:/Qt/Docs/Qt-5.5/qt3dcollision/qt3dcollision.tags=http://doc.qt.io/qt-5 \
2143+
C:/Qt/Docs/Qt-5.5/qt3dlogic/qt3dlogic.tags=http://doc.qt.io/qt-5 \
2144+
C:/Qt/Docs/Qt-5.5/qt3dcore/qt3dcore.tags=http://doc.qt.io/qt-5 \
2145+
C:/Qt/Docs/Qt-5.5/qt3drenderer/qt3drenderer.tags=http://doc.qt.io/qt-5 \
2146+
C:/Qt/Docs/Qt-5.5/qtwebchannel/qtwebchannel.tags=http://doc.qt.io/qt-5 \
2147+
C:/Qt/Docs/Qt-5.5/qtwebsockets/qtwebsockets.tags=http://doc.qt.io/qt-5 \
2148+
C:/Qt/Docs/Qt-5.5/qtbluetooth/qtbluetooth.tags=http://doc.qt.io/qt-5 \
2149+
C:/Qt/Docs/Qt-5.5/qtnfc/qtnfc.tags=http://doc.qt.io/qt-5 \
2150+
C:/Qt/Docs/Qt-5.5/qtsensors/qtsensors.tags=http://doc.qt.io/qt-5 \
2151+
C:/Qt/Docs/Qt-5.5/qtlocation/qtlocation.tags=http://doc.qt.io/qt-5 \
2152+
C:/Qt/Docs/Qt-5.5/qtpositioning/qtpositioning.tags=http://doc.qt.io/qt-5 \
2153+
C:/Qt/Docs/Qt-5.5/activeqt/activeqt.tags=http://doc.qt.io/qt-5 \
2154+
C:/Qt/Docs/Qt-5.5/qtquickcontrols/qtquickcontrols.tags=http://doc.qt.io/qt-5 \
2155+
C:/Qt/Docs/Qt-5.5/qtqml/qtqml.tags=http://doc.qt.io/qt-5 \
2156+
C:/Qt/Docs/Qt-5.5/qtquick/qtquick.tags=http://doc.qt.io/qt-5 \
2157+
C:/Qt/Docs/Qt-5.5/qtxmlpatterns/qtxmlpatterns.tags=http://doc.qt.io/qt-5 \
2158+
C:/Qt/Docs/Qt-5.5/qtsvg/qtsvg.tags=http://doc.qt.io/qt-5 \
2159+
C:/Qt/Docs/Qt-5.5/qdoc/qdoc.tags=http://doc.qt.io/qt-5 \
2160+
C:/Qt/Docs/Qt-5.5/qtprintsupport/qtprintsupport.tags=http://doc.qt.io/qt-5 \
2161+
C:/Qt/Docs/Qt-5.5/qtconcurrent/qtconcurrent.tags=http://doc.qt.io/qt-5 \
2162+
C:/Qt/Docs/Qt-5.5/qtgui/qtgui.tags=http://doc.qt.io/qt-5 \
2163+
C:/Qt/Docs/Qt-5.5/qttestlib/qttestlib.tags=http://doc.qt.io/qt-5 \
2164+
C:/Qt/Docs/Qt-5.5/qtwidgets/qtwidgets.tags=http://doc.qt.io/qt-5 \
2165+
C:/Qt/Docs/Qt-5.5/qtcore/qtcore.tags=http://doc.qt.io/qt-5 \
2166+
C:/Qt/Docs/Qt-5.5/qtnetwork/qtnetwork.tags=http://doc.qt.io/qt-5 \
2167+
C:/Qt/Docs/Qt-5.5/qtsql/qtsql.tags=http://doc.qt.io/qt-5 \
2168+
C:/Qt/Docs/Qt-5.5/qtxml/qtxml.tags=http://doc.qt.io/qt-5 \
2169+
C:/Qt/Docs/Qt-5.5/qtwebenginewidgets/qtwebenginewidgets.tags=http://doc.qt.io/qt-5
21722170

21732171
# When a file name is specified after GENERATE_TAGFILE, doxygen will create a
21742172
# tag file that is based on the input files it reads. See section "Linking to

‎doc/images/win/action.png‎

5.74 KB
Loading

‎doc/images/win/dialog_ask.png‎

5.83 KB
Loading

‎doc/images/win/dialog_exit.png‎

6.99 KB
Loading

‎doc/images/win/dialog_info.png‎

16.4 KB
Loading

0 commit comments

Comments
 (0)