SingleApplication v3.0a

1 files changed, 46 insertions, 38 deletions

diff --git a/README.md b/README.md
index b018022..abe4171 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,8 @@ SingleApplication
 This is a replacement of the QSingleApplication for `Qt5`.
 
 Keeps the Primary Instance of your Application and kills each subsequent
-instances. It can (if enabled) spawn a certain number of secondary instances
-(with the `--secondary` command line argument).
+instances. It can (if enabled) spawn secondary (non-related to the primary)
+instances and can send data to the primary instance from secondary instances.
 
 Usage
 -----
@@ -15,32 +15,26 @@ 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 uses your `Organization Name` and `Application Name` to set 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 then listen for connections
-on it. 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 it that a new instance had been started, after which it would terminate
- with status code `0`. The Primary Instance, `SingleApplication` would emit the
- `showUp()` signal upon detecting that a new instance had been started.
+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 then
+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 it that a new instance had been started, after which it
+would terminate with status code `0`. 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.
 
-Here is an example usage of the library:
-
-In your main you need to set the the `applicationName` and `organizationName` of
-the `QCoreApplication` class like so:
+You can use the library as if you use any other `QCoreApplication` class:
 
 ```cpp
 #include <QApplication>
-#include "singleapplication.h"
+#include <SingleApplication.h>
 
 int main( int argc, char* argv[] )
 {
-    QApplication::setApplicationName("{Your App Name}");
-    QApplication::setOrganizationName("{Your Organization Name}");
-
     SingleApplication app( argc, argv );
 
     return app.exec();
@@ -55,24 +49,28 @@ how:
 git submodule add git@github.com:itay-grudev/SingleApplication.git singleapplication
 ```
 
-And include the `singleapplication.pri` file in your `.pro` project file:
+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
 include(singleapplication/singleapplication.pri)
+DEFINES += QAPPLICATION_CLASS=QApplication
 ```
 
-The `Show Up` signal
+The `Instance Started` signal
 ------------------------
 
-The SingleApplication class implements a `showUp()` signal. You can bind to that
-signal to raise your application's window when a new instance had been started.
+The SingleApplication class implements a `instanceStarted()` signal. You can
+bind to that signal to raise your application's window when a new instance had
+been started.
 
 ```cpp
 // window is a QWindow instance
-QObject::connect( &app, &SingleApplication::showUp, window, &QWindow::raise );
+QObject::connect( &app, &SingleApplication::instanceStarted, window, &QWindow::raise );
 ```
 
-Using `QCoreApplication::instance()` is a neat way to get the
+Using `SingleApplication::instance()` is a neat way to get the
 `SingleApplication` instance for binding to it's signals anywhere in your
 program.
 
@@ -81,15 +79,27 @@ Secondary Instances
 
 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
-`SingleApplication` constructor. The default is `0` meaning no Secondary
-Instances. Here is an example allowing spawning up to `2` Secondary Instances.
+`SingleApplication` constructor. The default is `false` meaning no Secondary
+Instances. Here is an example of how you would start a Secondary Instance send
+a message with the command line arguments to the primary instance and then shut
+down.
 
 ```cpp
-SingleApplication app( argc, argv, 2 );
+int main(int argc, char *argv[])
+{
+    SingleApplication app( argc, argv, true );
+
+    if( app.isSecondary() ) {
+        app.sendMessage(  app.arguments().join(' ')).toUtf8() );
+        app.exit( 0 );
+    }
+
+    return app.exec();
+}
 ```
 
-After which just call your program with the `--secondary` argument to launch a
-secondary instance.
+___Note:__ A secondary instance won't cause the emission of the
+`instanceStarted()` signal.
 
 You can check whether your instance is a primary or secondary with the following
 methods:
@@ -100,20 +110,18 @@ app.isPrimary();
 app.isSecondary();
 ```
 
-__*Note:*__ If your Primary Instance is terminated upon launch of a new one it
-will replace it as Primary even if the `--secondary` argument has been set.
-
-*P.S. If you think this behavior could be improved create an issue and explain
-why.*
+__*Note:*__ If your Primary Instance is terminated a newly launched instance
+will replace the Primary one even if the Secondary flag has been set.
 
 Versioning
 ----------
 
-The current library versions is `2.4`.
+The current library versions is `3.0a`.
+
 Each major version introduces either very significant changes or is not
 backwards compatible with the previous version. Minor versions only add
 additional features, bug fixes or performance improvements and are backwards
-compatible with the previous release.
+compatible with the previous release. See `CHANGELOG.md` for more details.
 
 Implementation
 --------------
@@ -121,7 +129,7 @@ Implementation
 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
 notify the main process that a new instance had been spawned and thus invoke the
-`showUp()` signal.
+`instanceStarted()` signal.
 
 To handle an issue on `*nix` systems, where the operating system owns the shared
 memory block and if the program crashes the memory remains untouched, the