1
0
mirror of https://github.com/itay-grudev/SingleApplication.git synced 2025-04-21 04:24:43 +08:00

Switch to Doxygen to avoid documentation duplication

I also had to fix syntax a little in markdown and the header file.
Now checked on CI.
This commit is contained in:
Hennadii Chernyshchyk 2022-04-06 00:04:31 +03:00
parent 4a9a480094
commit efdfa507dd
No known key found for this signature in database
GPG Key ID: 24623302B8395825
6 changed files with 143 additions and 271 deletions

View File

@ -11,7 +11,25 @@ on:
- "**.md" - "**.md"
jobs: jobs:
doxygen:
name: Doxygen
runs-on: ubuntu-20.04
steps:
- name: Clone repo
uses: actions/checkout@v2.3.4
- name: Install apt packages
run: |
sudo apt-get update
sudo apt-get install doxygen qtbase5-dev
- name: Generate documentation
run: |
cmake -B build -D DOXYGEN_WARN_AS_ERROR=YES
cmake --build build --target SingleApplicationDocumentation
build: build:
name: Build
strategy: strategy:
matrix: matrix:
qt_version: [5.12.6, 5.15.0, 6.0.0, 6.2.0] qt_version: [5.12.6, 5.15.0, 6.0.0, 6.2.0]

View File

@ -1,36 +1,29 @@
Changelog # Changelog
=========
If by accident I have forgotten to credit someone in the CHANGELOG, email me and I will fix it. If by accident I have forgotten to credit someone in the CHANGELOG, email me and I will fix it.
__3.3.4__ ## 3.3.4
---------
* Fix compilation under Qt 6.2+ and stricter Qt compile settings. - _Christoph Cullmann_ * Fix compilation under Qt 6.2+ and stricter Qt compile settings. - _Christoph Cullmann_
* Provide API for blocking sendMessage. - _Christoph Cullmann_ * Provide API for blocking sendMessage. - _Christoph Cullmann_
__3.3.3__ ## 3.3.3
---------
* Support for Qt 6.3+ - Fixed deprecated `QCryptographicHash::addData()` that will only support `QByteArrayView` going further. - _Moody Liu_ * Support for Qt 6.3+ - Fixed deprecated `QCryptographicHash::addData()` that will only support `QByteArrayView` going further. - _Moody Liu_
__3.3.2__ ## 3.3.2
---------
* Fixed crash caused by sending a `writeAck` on a removed connection. - _Nicolas Werner_ * Fixed crash caused by sending a `writeAck` on a removed connection. - _Nicolas Werner_
__3.3.1__ ## 3.3.1
---------
* Added support for _AppImage_ dynamic executable paths. - _Michael Klein_ * Added support for _AppImage_ dynamic executable paths. - _Michael Klein_
__3.3.0__ ## 3.3.0
---------
* Fixed message fragmentation issue causing crashes and incorrectly / inconsistently received messages. - _Nils Jeisecke_ * Fixed message fragmentation issue causing crashes and incorrectly / inconsistently received messages. - _Nils Jeisecke_
__3.2.0__ ## 3.2.0
---------
* Added support for Qt 6 - _Jonas Kvinge_ * Added support for Qt 6 - _Jonas Kvinge_
* Fixed warning in `Qt 5.9` with `min`/`max` functions on Windows - _Nick Korotysh_ * Fixed warning in `Qt 5.9` with `min`/`max` functions on Windows - _Nick Korotysh_
@ -38,55 +31,47 @@ __3.2.0__
* Fix build issue with MinGW GCC pedantic mode - _Iakov Kirilenko_ * Fix build issue with MinGW GCC pedantic mode - _Iakov Kirilenko_
* Fixed conversion from `int` to `quint32` and Clang Tidy warnings - _Hennadii Chernyshchyk_ * Fixed conversion from `int` to `quint32` and Clang Tidy warnings - _Hennadii Chernyshchyk_
__3.1.5__ ## 3.1.5
---------
* Improved library stability in edge cases and very rapid process initialisation * Improved library stability in edge cases and very rapid process initialisation
* Fixed Bug where the shared memory block may have been modified without a lock * Fixed Bug where the shared memory block may have been modified without a lock
* Fixed Bug causing `instanceStarted()` to not get emitted when a second instance * Fixed Bug causing `instanceStarted()` to not get emitted when a second instance
has been started before the primary has initiated it's `QLocalServer`. has been started before the primary has initiated it's `QLocalServer`.
__3.1.4__ ## 3.1.4
---------
* Officially supporting and build-testing against Qt 5.15 * Officially supporting and build-testing against Qt 5.15
* Fixed an MSVC C4996 warning that suggests using `strncpy_s`. * Fixed an MSVC C4996 warning that suggests using `strncpy_s`.
_Hennadii Chernyshchyk_ _Hennadii Chernyshchyk_
__3.1.3.1__ ## 3.1.3.1
---------
* CMake build system improvements * CMake build system improvements
* Fixed Clang Tidy warnings * Fixed Clang Tidy warnings
_Hennadii Chernyshchyk_ _Hennadii Chernyshchyk_
__3.1.3__ ## 3.1.3
---------
* Improved `CMakeLists.txt` * Improved `CMakeLists.txt`
_Hennadii Chernyshchyk_ _Hennadii Chernyshchyk_
__3.1.2__ ## 3.1.2
---------
* Fix a crash when exiting an application on Android and iOS * Fix a crash when exiting an application on Android and iOS
_Emeric Grange_ _Emeric Grange_
__3.1.1a__ ## 3.1.1a
----------
* Added currentUser() method that returns the user the current instance is running as. * Added currentUser() method that returns the user the current instance is running as.
_Leander Schulten_ _Leander Schulten_
__3.1.0a__ ## 3.1.0a
----------
* Added primaryUser() method that returns the user the primary instance is running as. * Added primaryUser() method that returns the user the primary instance is running as.
__3.0.19__ ## 3.0.19
----------
* Fixed code warning for depricated functions in Qt 5.10 related to `QTime` and `qrand()`. * Fixed code warning for depricated functions in Qt 5.10 related to `QTime` and `qrand()`.
@ -94,8 +79,7 @@ __3.0.19__
_Anton Filimonov_ _Anton Filimonov_
_Jonas Kvinge_ _Jonas Kvinge_
__3.0.18__ ## 3.0.18
----------
* Fallback to standard QApplication class on iOS and Android systems where * Fallback to standard QApplication class on iOS and Android systems where
the library is not supported. the library is not supported.
@ -104,8 +88,7 @@ __3.0.18__
_Anton Filimonov_ _Anton Filimonov_
__3.0.17__ ## 3.0.17
----------
* Fixed compilation warning/error caused by `geteuid()` on unix based systems. * Fixed compilation warning/error caused by `geteuid()` on unix based systems.
@ -115,40 +98,34 @@ __3.0.17__
_Hennadii Chernyshchyk_ _Hennadii Chernyshchyk_
__3.0.16__ ## 3.0.16
----------
* Use geteuid and getpwuid to get username on Unix, fallback to environment variable. * Use geteuid and getpwuid to get username on Unix, fallback to environment variable.
_Jonas Kvinge_ _Jonas Kvinge_
__3.0.15__ ## 3.0.15
----------
* Bug Fix: sendMessage() might return false even though data was actually written. * Bug Fix: sendMessage() might return false even though data was actually written.
_Jonas Kvinge_ _Jonas Kvinge_
__3.0.14__ ## 3.0.14
----------
* Fixed uninitialised variables in the `SingleApplicationPrivate` constructor. * Fixed uninitialised variables in the `SingleApplicationPrivate` constructor.
__3.0.13a__ ## 3.0.13a
----------
* Process socket events asynchronously * Process socket events asynchronously
* Fix undefined variable error on Windows * Fix undefined variable error on Windows
_Francis Giraldeau_ _Francis Giraldeau_
__3.0.12a__ ## 3.0.12a
----------
* Removed signal handling. * Removed signal handling.
__3.0.11a__ ## 3.0.11a
----------
* Fixed bug where the message sent by the second process was not received * Fixed bug where the message sent by the second process was not received
correctly when the message is sent immediately following a connection. correctly when the message is sent immediately following a connection.
@ -160,8 +137,7 @@ __3.0.11a__
* Explicit `qWarning` and `qCritical` when the library is unable to initialise * Explicit `qWarning` and `qCritical` when the library is unable to initialise
correctly. correctly.
__3.0.10__ ## 3.0.10
----------
* Removed C style casts and eliminated all clang warnings. Fixed `instanceId` * Removed C style casts and eliminated all clang warnings. Fixed `instanceId`
reading from only one byte in the message deserialization. Cleaned up reading from only one byte in the message deserialization. Cleaned up
@ -172,8 +148,7 @@ __3.0.10__
_Jedidiah Buck McCready_ _Jedidiah Buck McCready_
__3.0.9__ ## 3.0.9
---------
* Added SingleApplicationPrivate::primaryPid() as a solution to allow * Added SingleApplicationPrivate::primaryPid() as a solution to allow
bringing the primary window of an application to the foreground on bringing the primary window of an application to the foreground on
@ -181,23 +156,20 @@ __3.0.9__
_Eelco van Dam from Peacs BV_ _Eelco van Dam from Peacs BV_
__3.0.8__ ## 3.0.8
---------
* Bug fix - changed QApplication::instance() to QCoreApplication::instance() * Bug fix - changed QApplication::instance() to QCoreApplication::instance()
_Evgeniy Bazhenov_ _Evgeniy Bazhenov_
__3.0.7a__ ## 3.0.7a
----------
* Fixed compilation error with Mingw32 in MXE thanks to Vitaly Tonkacheyev. * Fixed compilation error with Mingw32 in MXE thanks to Vitaly Tonkacheyev.
* Removed QMutex used for thread safe behaviour. The implementation now uses * Removed QMutex used for thread safe behaviour. The implementation now uses
QCoreApplication::instance() to get an instance to SingleApplication for QCoreApplication::instance() to get an instance to SingleApplication for
memory deallocation. memory deallocation.
__3.0.6a__ ## 3.0.6a
----------
* Reverted GetUserName API usage on Windows. Fixed bug with missing library. * Reverted GetUserName API usage on Windows. Fixed bug with missing library.
* Fixed bug in the Calculator example, preventing it's window to be raised * Fixed bug in the Calculator example, preventing it's window to be raised
@ -205,22 +177,19 @@ __3.0.6a__
Special thanks to Charles Gunawan. Special thanks to Charles Gunawan.
__3.0.5a__ ## 3.0.5a
----------
* Fixed a memory leak in the SingleApplicationPrivate destructor. * Fixed a memory leak in the SingleApplicationPrivate destructor.
_Sergei Moiseev_ _Sergei Moiseev_
__3.0.4a__ ## 3.0.4a
----------
* Fixed shadow and uninitialised variable warnings. * Fixed shadow and uninitialised variable warnings.
_Paul Walmsley_ _Paul Walmsley_
__3.0.3a__ ## 3.0.3a
----------
* Removed Microsoft Windows specific code for getting username due to * Removed Microsoft Windows specific code for getting username due to
multiple problems and compiler differences on Windows platforms. On multiple problems and compiler differences on Windows platforms. On
@ -230,16 +199,14 @@ __3.0.3a__
* Explicitly getting absolute path of the user's home directory as on Unix * Explicitly getting absolute path of the user's home directory as on Unix
a relative path (`~`) may be returned. a relative path (`~`) may be returned.
__3.0.2a__ ## 3.0.2a
----------
* Fixed bug on Windows when username containing wide characters causes the * Fixed bug on Windows when username containing wide characters causes the
library to crash. library to crash.
_Le Liu_ _Le Liu_
__3.0.1a__ ## 3.0.1a
----------
* Allows the application path and version to be excluded from the server name * Allows the application path and version to be excluded from the server name
hash. The following flags were added for this purpose: hash. The following flags were added for this purpose:
@ -251,8 +218,7 @@ __3.0.1a__
_Le Liu_ _Le Liu_
__v3.0a__ ## v3.0a
---------
* Deprecated secondary instances count. * Deprecated secondary instances count.
* Added a sendMessage() method to send a message to the primary instance. * Added a sendMessage() method to send a message to the primary instance.
@ -281,37 +247,32 @@ __v3.0a__
secondary instance started. When called from the primary instance will secondary instance started. When called from the primary instance will
return `0`. return `0`.
__v2.4__ ## v2.4
--------
* Stability improvements * Stability improvements
* Support for secondary instances. * Support for secondary instances.
* The library now recovers safely after the primary process has crashed * The library now recovers safely after the primary process has crashed
and the shared memory had not been deleted. and the shared memory had not been deleted.
__v2.3__ ## v2.3
--------
* Improved pimpl design and inheritance safety. * Improved pimpl design and inheritance safety.
_Vladislav Pyatnichenko_ _Vladislav Pyatnichenko_
__v2.2__ ## v2.2
--------
* The `QAPPLICATION_CLASS` macro can now be defined in the file including the * The `QAPPLICATION_CLASS` macro can now be defined in the file including the
Single Application header or with a `DEFINES+=` statement in the project file. Single Application header or with a `DEFINES+=` statement in the project file.
__v2.1__ ## v2.1
--------
* A race condition can no longer occur when starting two processes nearly * A race condition can no longer occur when starting two processes nearly
simultaneously. simultaneously.
Fix issue [#3](https://github.com/itay-grudev/SingleApplication/issues/3) Fix issue [#3](https://github.com/itay-grudev/SingleApplication/issues/3)
__v2.0__ ## v2.0
--------
* SingleApplication is now being passed a reference to `argc` instead of a * SingleApplication is now being passed a reference to `argc` instead of a
copy. copy.

View File

@ -29,6 +29,7 @@ else()
endif() endif()
find_package(Qt${QT_DEFAULT_MAJOR_VERSION} COMPONENTS ${QT_COMPONENTS} REQUIRED) find_package(Qt${QT_DEFAULT_MAJOR_VERSION} COMPONENTS ${QT_COMPONENTS} REQUIRED)
find_package(Doxygen)
target_link_libraries(${PROJECT_NAME} PUBLIC ${QT_LIBRARIES}) target_link_libraries(${PROJECT_NAME} PUBLIC ${QT_LIBRARIES})
@ -48,3 +49,14 @@ target_compile_definitions(${PROJECT_NAME} PRIVATE
QT_NO_KEYWORDS QT_NO_KEYWORDS
QT_NO_FOREACH QT_NO_FOREACH
) )
if(DOXYGEN_FOUND)
set(DOXYGEN_USE_MDFILE_AS_MAINPAGE README.md)
doxygen_add_docs(${PROJECT_NAME}Documentation
singleapplication.h
CHANGELOG.md
Windows.md
README.md
)
endif()

170
README.md
View File

@ -1,5 +1,5 @@
SingleApplication # SingleApplication
=================
[![CI](https://github.com/itay-grudev/SingleApplication/workflows/CI:%20Build%20Test/badge.svg)](https://github.com/itay-grudev/SingleApplication/actions) [![CI](https://github.com/itay-grudev/SingleApplication/workflows/CI:%20Build%20Test/badge.svg)](https://github.com/itay-grudev/SingleApplication/actions)
This is a replacement of the QtSingleApplication for `Qt5` and `Qt6`. This is a replacement of the QtSingleApplication for `Qt5` and `Qt6`.
@ -8,8 +8,7 @@ Keeps the Primary Instance of your Application and kills each subsequent
instances. It can (if enabled) spawn secondary (non-related to the primary) instances. It can (if enabled) spawn secondary (non-related to the primary)
instances and can send data to the primary instance from secondary instances. instances and can send data to the primary instance from secondary instances.
Usage ## Usage
-----
The `SingleApplication` class inherits from whatever `Q[Core|Gui]Application` The `SingleApplication` class inherits from whatever `Q[Core|Gui]Application`
class you specify via the `QAPPLICATION_CLASS` macro (`QCoreApplication` is the class you specify via the `QAPPLICATION_CLASS` macro (`QCoreApplication` is the
@ -57,7 +56,6 @@ add_subdirectory(src/third-party/singleapplication)
target_link_libraries(${PROJECT_NAME} SingleApplication::SingleApplication) target_link_libraries(${PROJECT_NAME} SingleApplication::SingleApplication)
``` ```
The library sets up a `QLocalServer` and a `QSharedMemory` block. The first The library sets up a `QLocalServer` and a `QSharedMemory` block. The first
instance of your Application is your Primary Instance. It would check if the instance of your Application is your Primary Instance. It would check if the
shared memory block exists and if not it will start a `QLocalServer` and listen shared memory block exists and if not it will start a `QLocalServer` and listen
@ -73,10 +71,9 @@ The library uses `stdlib` to terminate the program with the `exit()` function.
Also don't forget to specify which `QCoreApplication` class your app is using if it Also don't forget to specify which `QCoreApplication` class your app is using if it
is not `QCoreApplication` as in examples above. is not `QCoreApplication` as in examples above.
The `Instance Started` signal ## Instance started signal
-----------------------------
The SingleApplication class implements a `instanceStarted()` signal. You can The `SingleApplication` class implements a `instanceStarted()` signal. You can
bind to that signal to raise your application's window when a new instance had bind to that signal to raise your application's window when a new instance had
been started, for example. been started, for example.
@ -94,13 +91,12 @@ Using `SingleApplication::instance()` is a neat way to get the
`SingleApplication` instance for binding to it's signals anywhere in your `SingleApplication` instance for binding to it's signals anywhere in your
program. program.
__Note:__ On Windows the ability to bring the application windows to the _Note:_ On Windows the ability to bring the application windows to the
foreground is restricted. See [Windows specific implementations](Windows.md) foreground is restricted. See [Windows specific implementations](Windows.md)
for a workaround and an example implementation. for a workaround and an example implementation.
Secondary Instances ## Secondary Instances
-------------------
If you want to be able to launch additional Secondary Instances (not related to If you want to be able to launch additional Secondary Instances (not related to
your Primary Instance) you have to enable that with the third parameter of the your Primary Instance) you have to enable that with the third parameter of the
@ -123,7 +119,7 @@ int main(int argc, char *argv[])
} }
``` ```
*__Note:__ A secondary instance won't cause the emission of the _Note:_ A secondary instance won't cause the emission of the
`instanceStarted()` signal by default. See `SingleApplication::Mode` for more `instanceStarted()` signal by default. See `SingleApplication::Mode` for more
details.* details.*
@ -136,11 +132,10 @@ app.isPrimary();
app.isSecondary(); app.isSecondary();
``` ```
*__Note:__ If your Primary Instance is terminated a newly launched instance _Note:_ If your Primary Instance is terminated a newly launched instance
will replace the Primary one even if the Secondary flag has been set.* will replace the Primary one even if the Secondary flag has been set.*
Examples ## Examples
--------
There are three examples provided in this repository: There are three examples provided in this repository:
@ -148,149 +143,18 @@ There are three examples provided in this repository:
* An example of a graphical application raising it's parent window [`examples/calculator`](https://github.com/itay-grudev/SingleApplication/tree/master/examples/calculator) * An example of a graphical application raising it's parent window [`examples/calculator`](https://github.com/itay-grudev/SingleApplication/tree/master/examples/calculator)
* A console application sending the primary instance it's command line parameters [`examples/sending_arguments`](https://github.com/itay-grudev/SingleApplication/tree/master/examples/sending_arguments) * A console application sending the primary instance it's command line parameters [`examples/sending_arguments`](https://github.com/itay-grudev/SingleApplication/tree/master/examples/sending_arguments)
API ## Versioning
---
### Members
```cpp
SingleApplication::SingleApplication( int &argc, char *argv[], bool allowSecondary = false, Options options = Mode::User, int timeout = 100, QString userData = QString() )
```
Depending on whether `allowSecondary` is set, this constructor may terminate
your app if there is already a primary instance running. Additional `Options`
can be specified to set whether the SingleApplication block should work
user-wide or system-wide. Additionally the `Mode::SecondaryNotification` may be
used to notify the primary instance whenever a secondary instance had been
started (disabled by default). `timeout` specifies the maximum time in
milliseconds to wait for blocking operations. Setting `userData` provides additional data that will isolate this instance from other instances that do not have the same (or any) user data set.
*__Note:__ `argc` and `argv` may be changed as Qt removes arguments that it
recognizes.*
*__Note:__ `Mode::SecondaryNotification` only works if set on both the primary
and the secondary instance.*
*__Note:__ Operating system can restrict the shared memory blocks to the same
user, in which case the User/System modes will have no effect and the block will
be user wide.*
---
```cpp
bool SingleApplication::sendMessage( QByteArray message, int timeout = 100 )
```
Sends `message` to the Primary Instance. Uses `timeout` as a the maximum timeout
in milliseconds for blocking functions. Returns `true` if the message has been sent
successfully. If the message can't be sent or the function timeouts - returns `false`.
---
```cpp
bool SingleApplication::isPrimary()
```
Returns if the instance is the primary instance.
---
```cpp
bool SingleApplication::isSecondary()
```
Returns if the instance is a secondary instance.
---
```cpp
quint32 SingleApplication::instanceId()
```
Returns a unique identifier for the current instance.
---
```cpp
qint64 SingleApplication::primaryPid()
```
Returns the process ID (PID) of the primary instance.
---
```cpp
QString SingleApplication::primaryUser()
```
Returns the username the primary instance is running as.
---
```cpp
QString SingleApplication::currentUser()
```
Returns the username the current instance is running as.
### Signals
```cpp
void SingleApplication::instanceStarted()
```
Triggered whenever a new instance had been started, except for secondary
instances if the `Mode::SecondaryNotification` flag is not specified.
---
```cpp
void SingleApplication::receivedMessage( quint32 instanceId, QByteArray message )
```
Triggered whenever there is a message received from a secondary instance.
---
### Flags
```cpp
enum SingleApplication::Mode
```
* `Mode::User` - The SingleApplication block should apply user wide. This adds
user specific data to the key used for the shared memory and server name.
This is the default functionality.
* `Mode::System` The SingleApplication block applies system-wide.
* `Mode::SecondaryNotification` Whether to trigger `instanceStarted()` even
whenever secondary instances are started.
* `Mode::ExcludeAppPath` Excludes the application path from the server name
(and memory block) hash.
* `Mode::ExcludeAppVersion` Excludes the application version from the server
name (and memory block) hash.
*__Note:__ `Mode::SecondaryNotification` only works if set on both the primary
and the secondary instance.*
*__Note:__ Operating system can restrict the shared memory blocks to the same
user, in which case the User/System modes will have no effect and the block will
be user wide.*
---
Versioning
----------
Each major version introduces either very significant changes or is not Each major version introduces either very significant changes or is not
backwards compatible with the previous version. Minor versions only add backwards compatible with the previous version. Minor versions only add
additional features, bug fixes or performance improvements and are backwards additional features, bug fixes or performance improvements and are backwards
compatible with the previous release. See [`CHANGELOG.md`](CHANGELOG.md) for compatible with the previous release. See [CHANGELOG.md](CHANGELOG.md) for
more details. more details.
Implementation ## Implementation
--------------
The library is implemented with a QSharedMemory block which is thread safe and The library is implemented with a `QSharedMemory` block which is thread safe and
guarantees a race condition will not occur. It also uses a QLocalSocket to guarantees a race condition will not occur. It also uses a `QLocalSocket` to
notify the main process that a new instance had been spawned and thus invoke the notify the main process that a new instance had been spawned and thus invoke the
`instanceStarted()` signal and for messaging the primary instance. `instanceStarted()` signal and for messaging the primary instance.
@ -298,8 +162,8 @@ Additionally the library can recover from being forcefully killed on *nix
systems and will reset the memory block given that there are no other systems and will reset the memory block given that there are no other
instances running. instances running.
License ## License
-------
This library and it's supporting documentation are released under This library and it's supporting documentation are released under
`The MIT License (MIT)` with the exception of the Qt calculator examples which `The MIT License (MIT)` with the exception of the Qt calculator examples which
is distributed under the BSD license. is distributed under the BSD license.

View File

@ -1,15 +1,13 @@
Windows Specific Implementations # Windows Specific Implementations
================================
Setting the foreground window ## Setting the foreground window
-----------------------------
In the `instanceStarted()` example in the `README` we demonstrated how an In the `instanceStarted()` example in the `README` we demonstrated how an
application can bring it's primary instance window whenever a second copy application can bring it's primary instance window whenever a second copy
of the application is started. of the application is started.
On Windows the ability to bring the application windows to the foreground is On Windows the ability to bring the application windows to the foreground is
restricted, see [`AllowSetForegroundWindow()`][AllowSetForegroundWindow] for more restricted, see [AllowSetForegroundWindow()][https://msdn.microsoft.com/en-us/library/windows/desktop/ms632668.aspx] for more
details. details.
The background process (the primary instance) can bring its windows to the The background process (the primary instance) can bring its windows to the
@ -42,5 +40,3 @@ void App::instanceStarted() {
QApplication::setActiveWindow( [window/widget to set to the foreground] ); QApplication::setActiveWindow( [window/widget to set to the foreground] );
} }
``` ```
[AllowSetForegroundWindow]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms632668.aspx

View File

@ -35,7 +35,7 @@
class SingleApplicationPrivate; class SingleApplicationPrivate;
/** /**
* @brief The SingleApplication class handles multiple instances of the same * @brief Handles multiple instances of the same
* Application * Application
* @see QCoreApplication * @see QCoreApplication
*/ */
@ -47,86 +47,99 @@ class SingleApplication : public QAPPLICATION_CLASS
public: public:
/** /**
* @brief Mode of operation of SingleApplication. * @brief Mode of operation of `SingleApplication`.
* Whether the block should be user-wide or system-wide and whether the * Whether the block should be user-wide or system-wide and whether the
* primary instance should be notified when a secondary instance had been * primary instance should be notified when a secondary instance had been
* started. * started.
* @note Operating system can restrict the shared memory blocks to the same * @note Operating system can restrict the shared memory blocks to the same
* user, in which case the User/System modes will have no effect and the * user, in which case the User/System modes will have no effect and the
* block will be user wide. * block will be user wide.
* @enum
*/ */
enum Mode { enum Mode {
User = 1 << 0, /** The `SingleApplication` block should apply user wide
System = 1 << 1, * (this adds user specific data to the key used for the shared memory and server name)
SecondaryNotification = 1 << 2, * */
ExcludeAppVersion = 1 << 3, User = 1 << 0,
ExcludeAppPath = 1 << 4 /**
* The `SingleApplication` block applies system-wide.
*/
System = 1 << 1,
/**
* Whether to trigger `instanceStarted()` even whenever secondary instances are started
*/
SecondaryNotification = 1 << 2,
/**
* Excludes the application version from the server name (and memory block) hash
*/
ExcludeAppVersion = 1 << 3,
/**
* Excludes the application path from the server name (and memory block) hash
*/
ExcludeAppPath = 1 << 4
}; };
Q_DECLARE_FLAGS(Options, Mode) Q_DECLARE_FLAGS(Options, Mode)
/** /**
* @brief Intitializes a SingleApplication instance with argc command line * @brief Intitializes a `SingleApplication` instance with argc command line
* arguments in argv * arguments in argv
* @arg {int &} argc - Number of arguments in argv * @arg argc - Number of arguments in argv
* @arg {const char *[]} argv - Supplied command line arguments * @arg argv - Supplied command line arguments
* @arg {bool} allowSecondary - Whether to start the instance as secondary * @arg allowSecondary - Whether to start the instance as secondary
* if there is already a primary instance. * if there is already a primary instance.
* @arg {Mode} mode - Whether for the SingleApplication block to be applied * @arg mode - Whether for the `SingleApplication` block to be applied
* User wide or System wide. * User wide or System wide.
* @arg {int} timeout - Timeout to wait in milliseconds. * @arg timeout - Timeout to wait in milliseconds.
* @note argc and argv may be changed as Qt removes arguments that it * @note argc and argv may be changed as Qt removes arguments that it
* recognizes * recognizes
* @note Mode::SecondaryNotification only works if set on both the primary * @note `Mode::SecondaryNotification` only works if set on both the primary
* instance and the secondary instance. * instance and the secondary instance.
* @note The timeout is just a hint for the maximum time of blocking * @note The timeout is just a hint for the maximum time of blocking
* operations. It does not guarantee that the SingleApplication * operations. It does not guarantee that the `SingleApplication`
* initialisation will be completed in given time, though is a good hint. * initialisation will be completed in given time, though is a good hint.
* Usually 4*timeout would be the worst case (fail) scenario. * Usually 4*timeout would be the worst case (fail) scenario.
* @see See the corresponding QAPPLICATION_CLASS constructor for reference * @see See the corresponding `QAPPLICATION_CLASS` constructor for reference
*/ */
explicit SingleApplication( int &argc, char *argv[], bool allowSecondary = false, Options options = Mode::User, int timeout = 1000, const QString &userData = {} ); explicit SingleApplication( int &argc, char *argv[], bool allowSecondary = false, Options options = Mode::User, int timeout = 1000, const QString &userData = {} );
~SingleApplication() override; ~SingleApplication() override;
/** /**
* @brief Returns if the instance is the primary instance * @brief Checks if the instance is primary instance
* @returns {bool} * @returns `true` if the instance is primary
*/ */
bool isPrimary() const; bool isPrimary() const;
/** /**
* @brief Returns if the instance is a secondary instance * @brief Checks if the instance is a secondary instance
* @returns {bool} * @returns `true` if the instance is secondary
*/ */
bool isSecondary() const; bool isSecondary() const;
/** /**
* @brief Returns a unique identifier for the current instance * @brief Returns a unique identifier for the current instance
* @returns {qint32} * @returns instance id
*/ */
quint32 instanceId() const; quint32 instanceId() const;
/** /**
* @brief Returns the process ID (PID) of the primary instance * @brief Returns the process ID (PID) of the primary instance
* @returns {qint64} * @returns pid
*/ */
qint64 primaryPid() const; qint64 primaryPid() const;
/** /**
* @brief Returns the username of the user running the primary instance * @brief Returns the username of the user running the primary instance
* @returns {QString} * @returns user name
*/ */
QString primaryUser() const; QString primaryUser() const;
/** /**
* @brief Returns the username of the current user * @brief Returns the username of the current user
* @returns {QString} * @returns user name
*/ */
QString currentUser() const; QString currentUser() const;
/** /**
* @brief Mode of operation of sendMessage. * @brief Mode of operation of sendMessage.
* @enum
*/ */
enum SendMode { enum SendMode {
NonBlocking, /** Do not wait for the primary instance termination and return immediately */ NonBlocking, /** Do not wait for the primary instance termination and return immediately */
@ -134,23 +147,31 @@ public:
}; };
/** /**
* @brief Sends a message to the primary instance. Returns true on success. * @brief Sends a message to the primary instance
* @param {int} timeout - Timeout for connecting * @param message data to send
* @param {SendMode} sendMode - Mode of operation. * @param timeout timeout for connecting
* @returns {bool} * @param sendMode - Mode of operation
* @note sendMessage() will return false if invoked from the primary * @returns `true` on success
* instance. * @note sendMessage() will return false if invoked from the primary instance
*/ */
bool sendMessage( const QByteArray &message, int timeout = 100, SendMode sendMode = NonBlocking ); bool sendMessage( const QByteArray &message, int timeout = 100, SendMode sendMode = NonBlocking );
/** /**
* @brief Get the set user data. * @brief Get the set user data.
* @returns {QStringList} * @returns user data
*/ */
QStringList userData() const; QStringList userData() const;
Q_SIGNALS: Q_SIGNALS:
/**
* @brief Triggered whenever a new instance had been started,
* except for secondary instances if the `Mode::SecondaryNotification` flag is not specified
*/
void instanceStarted(); void instanceStarted();
/**
* @brief Triggered whenever there is a message received from a secondary instance
*/
void receivedMessage( quint32 instanceId, QByteArray message ); void receivedMessage( quint32 instanceId, QByteArray message );
private: private: