Update SingleApplication

3rdparty/singleapplication/README.md

@@ -1,7 +1,8 @@
 SingleApplication
 =================
+[![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`.
+This is a replacement of the QtSingleApplication for `Qt5` and `Qt6`.
 
 Keeps the Primary Instance of your Application and kills each subsequent
 instances. It can (if enabled) spawn secondary (non-related to the primary)
@@ -15,18 +16,6 @@ class you specify via the `QAPPLICATION_CLASS` macro (`QCoreApplication` is the
 default). Further usage is similar to the use of the `Q[Core|Gui]Application`
 classes.
 
-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
-shared memory block exists and if not it will start a `QLocalServer` and listen
-for connections. Each subsequent instance of your application would check if the
-shared memory block exists and if it does, it will connect to the QLocalServer
-to notify the primary instance that a new instance had been started, after which
-it would terminate with status code `0`. In the Primary Instance
-`SingleApplication` would emit the `instanceStarted()` signal upon detecting
-that a new instance had been started.
-
-The library uses `stdlib` to terminate the program with the `exit()` function.
-
 You can use the library as if you use any other `QCoreApplication` derived
 class:
 
@@ -43,24 +32,49 @@ int main( int argc, char* argv[] )
 ```
 
 To include the library files I would recommend that you add it as a git
-submodule to your project and include it's contents with a `.pri` file. Here is
-how:
+submodule to your project. Here is how:
 
 ```bash
-git submodule add git@github.com:itay-grudev/SingleApplication.git singleapplication
+git submodule add https://github.com/itay-grudev/SingleApplication.git singleapplication
 ```
 
-Then include the `singleapplication.pri` file in your `.pro` project file. Also
-don't forget to specify which `QCoreApplication` class your app is using if it
-is not `QCoreApplication`.
+**Qmake:**
+
+Then include the `singleapplication.pri` file in your `.pro` project file.
 
 ```qmake
 include(singleapplication/singleapplication.pri)
 DEFINES += QAPPLICATION_CLASS=QApplication
 ```
 
+**CMake:**
+
+Then include the subdirectory in your `CMakeLists.txt` project file.
+
+```cmake
+set(QAPPLICATION_CLASS QApplication CACHE STRING "Inheritance class for SingleApplication")
+add_subdirectory(src/third-party/singleapplication)
+target_link_libraries(${PROJECT_NAME} SingleApplication::SingleApplication)
+```
+
+
+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
+shared memory block exists and if not it will start a `QLocalServer` and listen
+for connections. Each subsequent instance of your application would check if the
+shared memory block exists and if it does, it will connect to the QLocalServer
+to notify the primary instance that a new instance had been started, after which
+it would terminate with status code `0`. In the Primary Instance
+`SingleApplication` would emit the `instanceStarted()` signal upon detecting
+that a new instance had been started.
+
+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
+is not `QCoreApplication` as in examples above.
+
 The `Instance Started` signal
-------------------------
+-----------------------------
 
 The SingleApplication class implements a `instanceStarted()` signal. You can
 bind to that signal to raise your application's window when a new instance had
@@ -125,13 +139,22 @@ app.isSecondary();
 *__Note:__ If your Primary Instance is terminated a newly launched instance
 will replace the Primary one even if the Secondary flag has been set.*
 
+Examples
+--------
+
+There are three examples provided in this repository:
+
+* Basic example that prevents a secondary instance from starting [`examples/basic`](https://github.com/itay-grudev/SingleApplication/tree/master/examples/basic)
+* 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)
+
 API
 ---
 
 ### Members
 
 ```cpp
-SingleApplication::SingleApplication( int &argc, char *argv[], bool allowSecondary = false, Options options = Mode::User, int timeout = 100 )
+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
@@ -140,7 +163,7 @@ 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.
+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.*
@@ -159,7 +182,8 @@ 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
+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`.
 
 ---
 
@@ -192,6 +216,22 @@ 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