de.skycoder42.qctrlsignals

A library to catch and handle windows and unix signals, in a cross platform manner

version 1.1.2

To install:

❯ qpm install de.skycoder42.qctrlsignals

QCtrlSignals

A library to catch and handle windows and unix signals, in a cross platform manner.

With this class, you can easily register for the Operation system signals (like CTRL_C_EVENT on windows and SIGINT on unix/linux) and use them just like normal Qt signals.

Features

  • Register for common signals via a Cross-Platform enum
  • You can register native signals as well
  • Asynchronous signal handling. The class emits a Qt signal, and you can connect to this one just like to any other Qt signal
  • Automated Quit:
    • The QCtrlSignalHandler automatically registers for typical "quit" signals (like SIGINT, SIGTERN, ...)
    • It automatically handles those and then calles qApp->quit();
    • Windows: Can handle the CTRL_CLOSE_EVENT, which cannot be catched with the handler otherwise

Installation

The package is providet as qpm package, de.skycoder42.qctrlsignals. To install:

  1. Install qpm (See GitHub - Installing, for windows see below)
  2. In your projects root directory, run qpm install de.skycoder42.qctrlsignals
  3. Include qpm to your project by adding include(vendor/vendor.pri) to your .pro file

Check their GitHub - Usage for App Developers to learn more about qpm.

Important for Windows users: QPM Version 0.10.0 (the one you can download on the website) is currently broken on windows! It's already fixed in master, but not released yet. Until a newer versions gets released, you can download the latest dev build from here:

Usage

All you have to do is to get the signal handler instance via QCtrlSignalHandler::instance() and register your signals. See the example below

Example

The following exaple uses the handler to:

  1. Automatically quit the application (for example by using CTRL_BREAK_EVENT or SIGQUIT)
  2. Instead if quitting, SigInt (CTRL_C_EVENT, SIGINT) will print a message
#include <QCoreApplication>
#include <QCtrlSignals>
#include <QDebug>

int main(int argc, char *argv[])
{
	QCoreApplication a(argc, argv);

	auto handler = QCtrlSignalHandler::instance();

	QObject::connect(qApp, &QCoreApplication::aboutToQuit, qApp, [](){
		qDebug() << "App about to quit!";
	});
	handler->setAutoQuitActive(true);

	qDebug() << "SigInt" << handler->registerForSignal(QCtrlSignalHandler::SigInt);
	QObject::connect(handler, &QCtrlSignalHandler::sigInt, qApp, [](){
		qDebug() << "SigInt triggered, shutdown was overwritten for this one!";
	});

	return a.exec();
}

Logging

By default, QCtrlSignals prints some warning messages if something goes wrong (For example, a signal cannot be registered). All messages of QCtrlSignals are grouped into the QLoggingCategory "QCtrlSignals". If you want to simply disable the logging, call the folling function somewhere in your code:

QLoggingCategory::setFilterRules(QStringLiteral("QCtrlSignals.warning=false"));

For more information about all the things you can do with the logging categories, check the Qt-Documentation

Documentation

The documentation is available as release and on github pages.

The documentation was created using doxygen. It includes an HTML-documentation and Qt-Help files that can be included into QtCreator (QtAssistant) to show F1-Help (See Adding External Documentation for more details).

Known Limitations

  • Only such signals, that the operating system allows, can be registered. For example, SIGKILL on linux cannot be registered
  • On Windows, all signals are handeled in a second thread. Thus, the signals that require immediate handling, like CTRL_CLOSE_EVENT, cannot be registered
    • However, this signal is handeled for automatic shutdown
Author

Skycoder

Info
View on Github

License: BSD_3_CLAUSE

Installs
Today 13
This week 74
This month 127
This year 597
Total 597
Dependencies

None.

Versions