mirror of
https://github.com/itay-grudev/SingleApplication.git
synced 2024-11-15 12:15:43 +08:00
Itay Grudev
GitHub
commit
0c4a0d8e9f
38
.github/workflows/doxygen.yml
vendored
Normal file
38
.github/workflows/doxygen.yml
vendored
Normal file
@ -0,0 +1,38 @@
|
||||
name: "Documentation"
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- 'main'
|
||||
- 'master'
|
||||
|
||||
jobs:
|
||||
doxygen:
|
||||
name: Doxygen
|
||||
runs-on: ubuntu-22.04
|
||||
steps:
|
||||
- name: Clone repo
|
||||
uses: actions/checkout@v3
|
||||
|
||||
- name: Install doxygen and pre-requsites 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
|
||||
|
||||
- name: Deploy to GitHub pages
|
||||
on:
|
||||
branches:
|
||||
- master
|
||||
|
||||
uses: crazy-max/ghaction-github-pages@v3
|
||||
with:
|
||||
target_branch: gh-pages
|
||||
build_dir: build/html
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
@ -12,6 +12,7 @@ on:
|
||||
|
||||
jobs:
|
||||
build:
|
||||
name: Build
|
||||
strategy:
|
||||
matrix:
|
||||
qt_version: [5.12.6, 5.15.0, 6.0.0, 6.2.0]
|
||||
122
CHANGELOG.md
122
CHANGELOG.md
@ -1,35 +1,31 @@
|
||||
Changelog
|
||||
=========
|
||||
# Changelog
|
||||
|
||||
If by accident I have forgotten to credit someone in the CHANGELOG, email me and I will fix it.
|
||||
## 3.4.0
|
||||
|
||||
__3.3.4__
|
||||
---------
|
||||
* Provide API for blocking sendMessage. - _Christoph Cullmann_
|
||||
|
||||
|
||||
## 3.3.4
|
||||
|
||||
* Fix compilation under Qt 6.2+ and stricter Qt compile settings. - _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_
|
||||
|
||||
__3.3.2__
|
||||
---------
|
||||
## 3.3.2
|
||||
|
||||
* 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_
|
||||
|
||||
__3.3.0__
|
||||
---------
|
||||
## 3.3.0
|
||||
|
||||
* 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_
|
||||
* Fixed warning in `Qt 5.9` with `min`/`max` functions on Windows - _Nick Korotysh_
|
||||
@ -37,55 +33,47 @@ __3.2.0__
|
||||
* Fix build issue with MinGW GCC pedantic mode - _Iakov Kirilenko_
|
||||
* 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
|
||||
* 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
|
||||
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
|
||||
* Fixed an MSVC C4996 warning that suggests using `strncpy_s`.
|
||||
|
||||
_Hennadii Chernyshchyk_
|
||||
|
||||
__3.1.3.1__
|
||||
---------
|
||||
## 3.1.3.1
|
||||
* CMake build system improvements
|
||||
* Fixed Clang Tidy warnings
|
||||
|
||||
_Hennadii Chernyshchyk_
|
||||
|
||||
__3.1.3__
|
||||
---------
|
||||
## 3.1.3
|
||||
* Improved `CMakeLists.txt`
|
||||
|
||||
_Hennadii Chernyshchyk_
|
||||
|
||||
__3.1.2__
|
||||
---------
|
||||
## 3.1.2
|
||||
|
||||
* Fix a crash when exiting an application on Android and iOS
|
||||
|
||||
_Emeric Grange_
|
||||
|
||||
__3.1.1a__
|
||||
----------
|
||||
## 3.1.1a
|
||||
|
||||
* Added currentUser() method that returns the user the current instance is running as.
|
||||
|
||||
_Leander Schulten_
|
||||
|
||||
__3.1.0a__
|
||||
----------
|
||||
## 3.1.0a
|
||||
|
||||
* 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()`.
|
||||
|
||||
@ -93,8 +81,7 @@ __3.0.19__
|
||||
_Anton Filimonov_
|
||||
_Jonas Kvinge_
|
||||
|
||||
__3.0.18__
|
||||
----------
|
||||
## 3.0.18
|
||||
|
||||
* Fallback to standard QApplication class on iOS and Android systems where
|
||||
the library is not supported.
|
||||
@ -103,8 +90,7 @@ __3.0.18__
|
||||
|
||||
_Anton Filimonov_
|
||||
|
||||
__3.0.17__
|
||||
----------
|
||||
## 3.0.17
|
||||
|
||||
* Fixed compilation warning/error caused by `geteuid()` on unix based systems.
|
||||
|
||||
@ -114,40 +100,34 @@ __3.0.17__
|
||||
|
||||
_Hennadii Chernyshchyk_
|
||||
|
||||
__3.0.16__
|
||||
----------
|
||||
## 3.0.16
|
||||
|
||||
* Use geteuid and getpwuid to get username on Unix, fallback to environment variable.
|
||||
|
||||
_Jonas Kvinge_
|
||||
|
||||
__3.0.15__
|
||||
----------
|
||||
## 3.0.15
|
||||
|
||||
* Bug Fix: sendMessage() might return false even though data was actually written.
|
||||
|
||||
_Jonas Kvinge_
|
||||
|
||||
__3.0.14__
|
||||
----------
|
||||
## 3.0.14
|
||||
|
||||
* Fixed uninitialised variables in the `SingleApplicationPrivate` constructor.
|
||||
|
||||
__3.0.13a__
|
||||
----------
|
||||
## 3.0.13a
|
||||
|
||||
* Process socket events asynchronously
|
||||
* Fix undefined variable error on Windows
|
||||
|
||||
_Francis Giraldeau_
|
||||
|
||||
__3.0.12a__
|
||||
----------
|
||||
## 3.0.12a
|
||||
|
||||
* Removed signal handling.
|
||||
|
||||
__3.0.11a__
|
||||
----------
|
||||
## 3.0.11a
|
||||
|
||||
* Fixed bug where the message sent by the second process was not received
|
||||
correctly when the message is sent immediately following a connection.
|
||||
@ -159,8 +139,7 @@ __3.0.11a__
|
||||
* Explicit `qWarning` and `qCritical` when the library is unable to initialise
|
||||
correctly.
|
||||
|
||||
__3.0.10__
|
||||
----------
|
||||
## 3.0.10
|
||||
|
||||
* Removed C style casts and eliminated all clang warnings. Fixed `instanceId`
|
||||
reading from only one byte in the message deserialization. Cleaned up
|
||||
@ -171,8 +150,7 @@ __3.0.10__
|
||||
|
||||
_Jedidiah Buck McCready_
|
||||
|
||||
__3.0.9__
|
||||
---------
|
||||
## 3.0.9
|
||||
|
||||
* Added SingleApplicationPrivate::primaryPid() as a solution to allow
|
||||
bringing the primary window of an application to the foreground on
|
||||
@ -180,23 +158,20 @@ __3.0.9__
|
||||
|
||||
_Eelco van Dam from Peacs BV_
|
||||
|
||||
__3.0.8__
|
||||
---------
|
||||
## 3.0.8
|
||||
|
||||
* Bug fix - changed QApplication::instance() to QCoreApplication::instance()
|
||||
|
||||
_Evgeniy Bazhenov_
|
||||
|
||||
__3.0.7a__
|
||||
----------
|
||||
## 3.0.7a
|
||||
|
||||
* Fixed compilation error with Mingw32 in MXE thanks to Vitaly Tonkacheyev.
|
||||
* Removed QMutex used for thread safe behaviour. The implementation now uses
|
||||
QCoreApplication::instance() to get an instance to SingleApplication for
|
||||
memory deallocation.
|
||||
|
||||
__3.0.6a__
|
||||
----------
|
||||
## 3.0.6a
|
||||
|
||||
* Reverted GetUserName API usage on Windows. Fixed bug with missing library.
|
||||
* Fixed bug in the Calculator example, preventing it's window to be raised
|
||||
@ -204,22 +179,19 @@ __3.0.6a__
|
||||
|
||||
Special thanks to Charles Gunawan.
|
||||
|
||||
__3.0.5a__
|
||||
----------
|
||||
## 3.0.5a
|
||||
|
||||
* Fixed a memory leak in the SingleApplicationPrivate destructor.
|
||||
|
||||
_Sergei Moiseev_
|
||||
|
||||
__3.0.4a__
|
||||
----------
|
||||
## 3.0.4a
|
||||
|
||||
* Fixed shadow and uninitialised variable warnings.
|
||||
|
||||
_Paul Walmsley_
|
||||
|
||||
__3.0.3a__
|
||||
----------
|
||||
## 3.0.3a
|
||||
|
||||
* Removed Microsoft Windows specific code for getting username due to
|
||||
multiple problems and compiler differences on Windows platforms. On
|
||||
@ -229,16 +201,14 @@ __3.0.3a__
|
||||
* Explicitly getting absolute path of the user's home directory as on Unix
|
||||
a relative path (`~`) may be returned.
|
||||
|
||||
__3.0.2a__
|
||||
----------
|
||||
## 3.0.2a
|
||||
|
||||
* Fixed bug on Windows when username containing wide characters causes the
|
||||
library to crash.
|
||||
|
||||
_Le Liu_
|
||||
|
||||
__3.0.1a__
|
||||
----------
|
||||
## 3.0.1a
|
||||
|
||||
* Allows the application path and version to be excluded from the server name
|
||||
hash. The following flags were added for this purpose:
|
||||
@ -250,8 +220,7 @@ __3.0.1a__
|
||||
|
||||
_Le Liu_
|
||||
|
||||
__v3.0a__
|
||||
---------
|
||||
## v3.0a
|
||||
|
||||
* Deprecated secondary instances count.
|
||||
* Added a sendMessage() method to send a message to the primary instance.
|
||||
@ -280,37 +249,32 @@ __v3.0a__
|
||||
secondary instance started. When called from the primary instance will
|
||||
return `0`.
|
||||
|
||||
__v2.4__
|
||||
--------
|
||||
## v2.4
|
||||
|
||||
* Stability improvements
|
||||
* Support for secondary instances.
|
||||
* The library now recovers safely after the primary process has crashed
|
||||
and the shared memory had not been deleted.
|
||||
|
||||
__v2.3__
|
||||
--------
|
||||
## v2.3
|
||||
|
||||
* Improved pimpl design and inheritance safety.
|
||||
|
||||
_Vladislav Pyatnichenko_
|
||||
|
||||
__v2.2__
|
||||
--------
|
||||
## v2.2
|
||||
|
||||
* 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.
|
||||
|
||||
__v2.1__
|
||||
--------
|
||||
## v2.1
|
||||
|
||||
* A race condition can no longer occur when starting two processes nearly
|
||||
simultaneously.
|
||||
|
||||
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
|
||||
copy.
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
cmake_minimum_required(VERSION 3.12.0)
|
||||
|
||||
project(SingleApplication LANGUAGES CXX)
|
||||
project(SingleApplication LANGUAGES CXX DESCRIPTION "Replacement for QtSingleApplication")
|
||||
|
||||
set(CMAKE_AUTOMOC ON)
|
||||
|
||||
@ -29,6 +29,7 @@ else()
|
||||
endif()
|
||||
|
||||
find_package(Qt${QT_DEFAULT_MAJOR_VERSION} COMPONENTS ${QT_COMPONENTS} REQUIRED)
|
||||
find_package(Doxygen)
|
||||
|
||||
target_link_libraries(${PROJECT_NAME} PUBLIC ${QT_LIBRARIES})
|
||||
|
||||
@ -48,3 +49,31 @@ target_compile_definitions(${PROJECT_NAME} PRIVATE
|
||||
QT_NO_KEYWORDS
|
||||
QT_NO_FOREACH
|
||||
)
|
||||
|
||||
if(DOXYGEN_FOUND)
|
||||
# Doxygen theme
|
||||
include(FetchContent)
|
||||
FetchContent_Declare(DoxygenAwesome
|
||||
GIT_REPOSITORY https://github.com/jothepro/doxygen-awesome-css
|
||||
GIT_TAG 4cd62308d825fe0396d2f66ffbab45d0e247724c # 2.0.3
|
||||
)
|
||||
FetchContent_MakeAvailable(DoxygenAwesome)
|
||||
FetchContent_GetProperties(DoxygenAwesome SOURCE_DIR DoxygenAwesome_SOURCE_DIR)
|
||||
|
||||
set(DOXYGEN_USE_MDFILE_AS_MAINPAGE README.md)
|
||||
set(DOXYGEN_GENERATE_TREEVIEW YES)
|
||||
set(DOXYGEN_HTML_HEADER ${DoxygenAwesome_SOURCE_DIR}/doxygen-custom/header.html)
|
||||
set(DOXYGEN_HTML_EXTRA_STYLESHEET ${DoxygenAwesome_SOURCE_DIR}/doxygen-awesome.css)
|
||||
set(DOXYGEN_HTML_EXTRA_FILES
|
||||
${DoxygenAwesome_SOURCE_DIR}/doxygen-awesome-fragment-copy-button.js
|
||||
${DoxygenAwesome_SOURCE_DIR}/doxygen-awesome-paragraph-link.js
|
||||
${DoxygenAwesome_SOURCE_DIR}/doxygen-awesome-darkmode-toggle.js
|
||||
)
|
||||
|
||||
doxygen_add_docs(${PROJECT_NAME}Documentation
|
||||
singleapplication.h
|
||||
CHANGELOG.md
|
||||
Windows.md
|
||||
README.md
|
||||
)
|
||||
endif()
|
||||
|
||||
172
README.md
172
README.md
@ -1,5 +1,5 @@
|
||||
SingleApplication
|
||||
=================
|
||||
# SingleApplication
|
||||
|
||||
[](https://github.com/itay-grudev/SingleApplication/actions)
|
||||
|
||||
This is a replacement of the QtSingleApplication for `Qt5` and `Qt6`.
|
||||
@ -8,8 +8,9 @@ Keeps the Primary Instance of your Application and kills each subsequent
|
||||
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
|
||||
-----
|
||||
## [Documentation](https://itay-grudev.github.io/SingleApplication/)
|
||||
|
||||
## Usage
|
||||
|
||||
The `SingleApplication` class inherits from whatever `Q[Core|Gui]Application`
|
||||
class you specify via the `QAPPLICATION_CLASS` macro (`QCoreApplication` is the
|
||||
@ -57,7 +58,6 @@ 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
|
||||
@ -73,10 +73,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
|
||||
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
|
||||
been started, for example.
|
||||
|
||||
@ -94,13 +93,12 @@ Using `SingleApplication::instance()` is a neat way to get the
|
||||
`SingleApplication` instance for binding to it's signals anywhere in your
|
||||
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)
|
||||
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
|
||||
your Primary Instance) you have to enable that with the third parameter of the
|
||||
@ -123,7 +121,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
|
||||
details.*
|
||||
|
||||
@ -136,11 +134,10 @@ app.isPrimary();
|
||||
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.*
|
||||
|
||||
Examples
|
||||
--------
|
||||
## Examples
|
||||
|
||||
There are three examples provided in this repository:
|
||||
|
||||
@ -148,149 +145,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)
|
||||
* 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, 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
|
||||
----------
|
||||
## Versioning
|
||||
|
||||
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. See [`CHANGELOG.md`](CHANGELOG.md) for
|
||||
compatible with the previous release. See [CHANGELOG.md](CHANGELOG.md) for
|
||||
more details.
|
||||
|
||||
Implementation
|
||||
--------------
|
||||
## 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
|
||||
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
|
||||
`instanceStarted()` signal and for messaging the primary instance.
|
||||
|
||||
@ -298,8 +164,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
|
||||
instances running.
|
||||
|
||||
License
|
||||
-------
|
||||
## License
|
||||
|
||||
This library and it's supporting documentation are released under
|
||||
`The MIT License (MIT)` with the exception of the Qt calculator examples which
|
||||
is distributed under the BSD license.
|
||||
|
||||
10
Windows.md
10
Windows.md
@ -1,15 +1,13 @@
|
||||
Windows Specific Implementations
|
||||
================================
|
||||
# Windows Specifics
|
||||
|
||||
Setting the foreground window
|
||||
-----------------------------
|
||||
## 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
|
||||
restricted, see [AllowSetForegroundWindow()][https://msdn.microsoft.com/en-us/library/windows/desktop/ms632668.aspx] for more
|
||||
details.
|
||||
|
||||
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] );
|
||||
}
|
||||
```
|
||||
|
||||
[AllowSetForegroundWindow]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms632668.aspx
|
||||
|
||||
@ -35,7 +35,7 @@
|
||||
class SingleApplicationPrivate;
|
||||
|
||||
/**
|
||||
* @brief The SingleApplication class handles multiple instances of the same
|
||||
* @brief Handles multiple instances of the same
|
||||
* Application
|
||||
* @see QCoreApplication
|
||||
*/
|
||||
@ -47,86 +47,99 @@ class SingleApplication : public QAPPLICATION_CLASS
|
||||
|
||||
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
|
||||
* primary instance should be notified when a secondary instance had been
|
||||
* started.
|
||||
* @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.
|
||||
* @enum
|
||||
*/
|
||||
enum Mode {
|
||||
User = 1 << 0,
|
||||
System = 1 << 1,
|
||||
SecondaryNotification = 1 << 2,
|
||||
ExcludeAppVersion = 1 << 3,
|
||||
ExcludeAppPath = 1 << 4
|
||||
/** The `SingleApplication` block should apply user wide
|
||||
* (this adds user specific data to the key used for the shared memory and server name)
|
||||
* */
|
||||
User = 1 << 0,
|
||||
/**
|
||||
* 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)
|
||||
|
||||
/**
|
||||
* @brief Intitializes a SingleApplication instance with argc command line
|
||||
* @brief Intitializes a `SingleApplication` instance with argc command line
|
||||
* arguments in argv
|
||||
* @arg {int &} argc - Number of arguments in argv
|
||||
* @arg {const char *[]} argv - Supplied command line arguments
|
||||
* @arg {bool} allowSecondary - Whether to start the instance as secondary
|
||||
* @arg argc - Number of arguments in argv
|
||||
* @arg argv - Supplied command line arguments
|
||||
* @arg allowSecondary - Whether to start the instance as secondary
|
||||
* 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.
|
||||
* @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
|
||||
* 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.
|
||||
* @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.
|
||||
* 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 = {} );
|
||||
~SingleApplication() override;
|
||||
|
||||
/**
|
||||
* @brief Returns if the instance is the primary instance
|
||||
* @returns {bool}
|
||||
* @brief Checks if the instance is primary instance
|
||||
* @returns `true` if the instance is primary
|
||||
*/
|
||||
bool isPrimary() const;
|
||||
|
||||
/**
|
||||
* @brief Returns if the instance is a secondary instance
|
||||
* @returns {bool}
|
||||
* @brief Checks if the instance is a secondary instance
|
||||
* @returns `true` if the instance is secondary
|
||||
*/
|
||||
bool isSecondary() const;
|
||||
|
||||
/**
|
||||
* @brief Returns a unique identifier for the current instance
|
||||
* @returns {qint32}
|
||||
* @returns instance id
|
||||
*/
|
||||
quint32 instanceId() const;
|
||||
|
||||
/**
|
||||
* @brief Returns the process ID (PID) of the primary instance
|
||||
* @returns {qint64}
|
||||
* @returns pid
|
||||
*/
|
||||
qint64 primaryPid() const;
|
||||
|
||||
/**
|
||||
* @brief Returns the username of the user running the primary instance
|
||||
* @returns {QString}
|
||||
* @returns user name
|
||||
*/
|
||||
QString primaryUser() const;
|
||||
|
||||
/**
|
||||
* @brief Returns the username of the current user
|
||||
* @returns {QString}
|
||||
* @returns user name
|
||||
*/
|
||||
QString currentUser() const;
|
||||
|
||||
/**
|
||||
* @brief Mode of operation of sendMessage.
|
||||
* @enum
|
||||
*/
|
||||
enum SendMode {
|
||||
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.
|
||||
* @param {int} timeout - Timeout for connecting
|
||||
* @param {SendMode} sendMode - Mode of operation.
|
||||
* @returns {bool}
|
||||
* @note sendMessage() will return false if invoked from the primary
|
||||
* instance.
|
||||
* @brief Sends a message to the primary instance
|
||||
* @param message data to send
|
||||
* @param timeout timeout for connecting
|
||||
* @param sendMode - Mode of operation
|
||||
* @returns `true` on success
|
||||
* @note sendMessage() will return false if invoked from the primary instance
|
||||
*/
|
||||
bool sendMessage( const QByteArray &message, int timeout = 100, SendMode sendMode = NonBlocking );
|
||||
|
||||
/**
|
||||
* @brief Get the set user data.
|
||||
* @returns {QStringList}
|
||||
* @returns user data
|
||||
*/
|
||||
QStringList userData() const;
|
||||
|
||||
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();
|
||||
|
||||
/**
|
||||
* @brief Triggered whenever there is a message received from a secondary instance
|
||||
*/
|
||||
void receivedMessage( quint32 instanceId, QByteArray message );
|
||||
|
||||
private:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user