aboutsummaryrefslogtreecommitdiff
path: root/Windows.md
diff options
context:
space:
mode:
authorItay Grudev <itay-grudev@users.noreply.github.com>2017-10-02 12:17:41 +0100
committerGitHub <noreply@github.com>2017-10-02 12:17:41 +0100
commit4f0365107283ce321da713baeab4d2aad0456baf (patch)
tree09caa4a6b735885355b47d1312375fccdd168d3d /Windows.md
parentFixed typo in the CHANGELOG.md (diff)
downloadsingleapplication-4f0365107283ce321da713baeab4d2aad0456baf.tar.xz
Primary PID support (#36)v3.0.9
* Added the ability to bring the primary application window to the foreground on Windows systems by adding an option flag. THis option can only be used in Windows development and in applications derived from QApplication with a QMainWindow object. Because the primary application needs to be instructed to go to the foreground, the option SecondaryNotification must also be set to use this functionality * Changed the ability to bring the primary application window to the front as discussed in itay-grudev/SingleApplication#31. Now the process ID of the primary application get stored and is accessible for other instances of the application. It is to the developer to bring the applications windows to the front. For convenience the accompanying readme now contains a paragraph with example of how to do this on Windows systems. * v3.0.9 Added SingleApplicationPrivate::primaryPid()
Diffstat (limited to 'Windows.md')
-rw-r--r--Windows.md46
1 files changed, 46 insertions, 0 deletions
diff --git a/Windows.md b/Windows.md
new file mode 100644
index 0000000..48b0748
--- /dev/null
+++ b/Windows.md
@@ -0,0 +1,46 @@
+Windows Specific Implementations
+================================
+
+Setting the foreground window
+-----------------------------
+
+In the `instanceStarted()` example in the `README` we demonstrated how an
+application can bring it's primary instance window whenever a second copy
+of the application is started.
+
+On Windows the ability to bring the application windows to the foreground is
+restricted, see [`AllowSetForegroundWindow()`][AllowSetForegroundWindow] for more
+details.
+
+The background process (the primary instance) can bring its windows to the
+foreground if it is allowed by the current foreground process (the secondary
+instance). To bypass this `SingleApplication` must be initialized with the
+`allowSecondary` parameter set to `true` and the `options` parameter must
+include `Mode::SecondaryNotification`, See `SingleApplication::Mode` for more
+details.
+
+Here is an example:
+
+```cpp
+if( app.isSecondary() ) {
+ // This API requires LIBS += User32.lib to be added to the project
+ AllowSetForegroundWindow( DWORD( app.getPrimaryPid() ) );
+}
+
+if( app.isPrimary() ) {
+ QObject::connect(
+ &app,
+ &SingleApplication::instanceStarted,
+ this,
+ &App::instanceStarted
+ );
+}
+```
+
+```cpp
+void App::instanceStarted() {
+ QApplication::setActiveWindow( [window/widget to set to the foreground] );
+}
+```
+
+[AllowSetForegroundWindow]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms632668.aspx