The background process application. The main class of QtBackgroundProcess. More...

#include <app.h>

Inheritance diagram for QtBackgroundProcess::App:

Public Slots
void	createDefaultInstanceID (bool overwrite=true)
	RESET accessor for App::instanceID. More...

void	setInstanceID (QString instanceID, bool useAsSeed=true)
	WRITE accessor for App::instanceID. More...

void	setForwardMasterLog (bool forwardMasterLog)
	WRITE accessor for App::forwardMasterLog.

void	setAutoStartMaster (bool autoStartMaster)
	WRITE accessor for App::autoStartMaster.

void	setIgnoreMultiStarts (bool ignoreMultiStarts)
	WRITE accessor for App::ignoreMultiStarts.

void	setAutoDeleteTerminals (bool autoDeleteTerminals, bool changeCurrent=false)
	WRITE accessor for App::autoDeleteTerminals.

void	setAutoKillTerminals (bool autoKillTerminals, bool killCurrent=false)
	WRITE accessor for App::autoKillTerminals.

Signals
void	newTerminalConnected (QtBackgroundProcess::Terminal *terminal, QPrivateSignal)
	Will be emitted when a new terminal has connected to the master.

void	commandReceived (QSharedPointer< QCommandLineParser > parser, bool isStarter, QPrivateSignal)
	Will be emitted when a new terminal sent arguments to the master. More...

void	connectedTerminalsChanged (QList< Terminal *> connectedTerminals, QPrivateSignal)
	NOTIFY accessor for App::connectedTerminals.

Public Member Functions
	App (int &argc, char **argv, int flags=ApplicationFlags)
	Creates a new app with it's arguments.

	~App ()
	Destructor.

QString	instanceID () const
	READ accessor for App::instanceID.

bool	forwardMasterLog () const
	READ accessor for App::forwardMasterLog.

bool	autoStartMaster () const
	READ accessor for App::autoStartMaster.

bool	ignoreMultiStarts () const
	READ accessor for App::ignoreMultiStarts.

bool	autoDeleteTerminals () const
	READ accessor for App::autoDeleteTerminals.

bool	autoKillTerminals () const
	READ accessor for App::autoKillTerminals.

void	setParserSetupFunction (const std::function< void(QCommandLineParser &)> &function)
	Sets the function to be called for the creation of the parser (Instead of overriding) More...

void	setStartupFunction (const std::function< int(const QCommandLineParser &)> &function)
	Sets the function to be called to startup the application (Instead of overriding) More...

void	setShutdownRequestFunction (const std::function< bool(const QCommandLineParser &, int &)> &function)
	Sets the function to be called to handle shutdown requests (Instead of overriding) More...

void	setShutdownRequestFunction (const std::function< bool(Terminal *, int &)> &function)
	Sets the function to be called to handle shutdown requests (Instead of overriding) More...

int	exec ()
	Executes the application event loop. More...

QList< Terminal * >	connectedTerminals () const
	READ accessor for App::connectedTerminals.

Public Member Functions inherited from QCoreApplication
	QCoreApplication (int &argc, char **argv)

virtual bool	notify (QObject receiver, QEvent event)

void	installNativeEventFilter (QAbstractNativeEventFilter *filterObj)

void	removeNativeEventFilter (QAbstractNativeEventFilter *filterObject)

void	aboutToQuit ()

Public Member Functions inherited from QObject
	QObject (QObject *parent)

virtual bool	eventFilter (QObject watched, QEvent event)

virtual const QMetaObject *	metaObject () const

QString	objectName () const

void	setObjectName (const QString &name)

bool	isWidgetType () const

bool	isWindowType () const

bool	signalsBlocked () const

bool	blockSignals (bool block)

QThread *	thread () const

void	moveToThread (QThread *targetThread)

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)

void	killTimer (int id)

T	findChild (const QString &name, Qt::FindChildOptions options) const

QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const

QList< T >	findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const

const QObjectList &	children () const

void	setParent (QObject *parent)

void	installEventFilter (QObject *filterObj)

void	removeEventFilter (QObject *obj)

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const

bool	disconnect (const char signal, const QObject receiver, const char *method) const

bool	disconnect (const QObject receiver, const char method) const

void	dumpObjectTree ()

void	dumpObjectInfo ()

void	dumpObjectTree () const

void	dumpObjectInfo () const

bool	setProperty (const char *name, const QVariant &value)

QVariant	property (const char *name) const

QList< QByteArray >	dynamicPropertyNames () const

void	destroyed (QObject *obj)

void	objectNameChanged (const QString &objectName)

QObject *	parent () const

bool	inherits (const char *className) const

void	deleteLater ()

Protected Member Functions
virtual void	setupParser (QCommandLineParser &parser, bool useShortOptions=true)
	Sets up the parser to parse commands and arguments. More...

virtual int	startupApp (const QCommandLineParser &parser)
	Is called as initialization function of the master process. More...

virtual bool	requestAppShutdown (Terminal *terminal, int &exitCode)
	Gets called when a terminal requests a shutdown of the master. More...

Protected Member Functions inherited from QCoreApplication
virtual bool	event (QEvent *e)

Protected Member Functions inherited from QObject
QObject *	sender () const

int	senderSignalIndex () const

int	receivers (const char *signal) const

bool	isSignalConnected (const QMetaMethod &signal) const

virtual void	timerEvent (QTimerEvent *event)

virtual void	childEvent (QChildEvent *event)

virtual void	customEvent (QEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	disconnectNotify (const QMetaMethod &signal)

Properties
QString	instanceID
	The current id of the singleton instance of the master process. More...

bool	forwardMasterLog
	Specifies, whether the master should forward debug output to all terminals. More...

bool	autoStartMaster
	If true, the master process will always be started, not only with "start". More...

bool	ignoreMultiStarts
	If true, "start" commands will be ignored, if the master is already running. More...

bool	autoDeleteTerminals
	If true, the master process will automatically delete terminals that have been disconnected. More...

bool	autoKillTerminals
	If true, the master process will automatically close terminals after it received the parameters. More...

QList< Terminal * >	connectedTerminals
	Holds a list of all currently connected terminals. More...

Properties inherited from QCoreApplication
	applicationName

	applicationVersion

	organizationName

	organizationDomain

	quitLockEnabled

Properties inherited from QObject
	objectName

Additional Inherited Members
Static Public Member Functions inherited from QCoreApplication
QStringList	arguments ()

void	setAttribute (Qt::ApplicationAttribute attribute, bool on)

bool	testAttribute (Qt::ApplicationAttribute attribute)

void	setOrganizationDomain (const QString &orgDomain)

QString	organizationDomain ()

void	setOrganizationName (const QString &orgName)

QString	organizationName ()

void	setApplicationName (const QString &application)

QString	applicationName ()

void	setApplicationVersion (const QString &version)

QString	applicationVersion ()

void	setSetuidAllowed (bool allow)

bool	isSetuidAllowed ()

QCoreApplication *	instance ()

int	exec ()

void	processEvents (QEventLoop::ProcessEventsFlags flags)

void	processEvents (QEventLoop::ProcessEventsFlags flags, int maxtime)

void	exit (int returnCode)

bool	sendEvent (QObject receiver, QEvent event)

void	postEvent (QObject receiver, QEvent event, int priority)

void	sendPostedEvents (QObject *receiver, int event_type)

void	removePostedEvents (QObject *receiver, int eventType)

bool	hasPendingEvents ()

QAbstractEventDispatcher *	eventDispatcher ()

void	setEventDispatcher (QAbstractEventDispatcher *eventDispatcher)

bool	startingUp ()

bool	closingDown ()

QString	applicationDirPath ()

QString	applicationFilePath ()

qint64	applicationPid ()

void	setLibraryPaths (const QStringList &paths)

QStringList	libraryPaths ()

void	addLibraryPath (const QString &path)

void	removeLibraryPath (const QString &path)

bool	installTranslator (QTranslator *translationFile)

bool	removeTranslator (QTranslator *translationFile)

QString	translate (const char context, const char sourceText, const char *disambiguation, int n)

QString	translate (const char context, const char key, const char *disambiguation, Encoding encoding, int n)

void	flush ()

bool	isQuitLockEnabled ()

void	setQuitLockEnabled (bool enabled)

void	quit ()

Static Public Member Functions inherited from QObject
QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

Detailed Description

The background process application. The main class of QtBackgroundProcess.

Use this class instead of QCoreApplication to create a background process. You will either have to override the startup/shutdown functions or set them with function objects.

See also: App::setupParser, App::startupApp, App::requestAppShutdown

Definition at line 34 of file app.h.

Member Function Documentation

◆ commandReceived

QtBackgroundProcess::App::commandReceived	(	QSharedPointer< QCommandLineParser >	parser,
		bool	isStarter,
		QPrivateSignal
	)

signal

Will be emitted when a new terminal sent arguments to the master.

Parameters

parser	A command line parser, holding the arguments that have been sent to the master
isStarter	If this arguments are the same that have been passed to App::startupApp, this parameter will be `true`

See also: App::newTerminalConnected, Terminal::parser, Terminal::starter

◆ createDefaultInstanceID

QtBackgroundProcess::App::createDefaultInstanceID ( bool overwrite = true )

slot

RESET accessor for App::instanceID.

Parameters

overwrite If set to false no id will be generated, if one already exists

Exceptions

NotAllowedInRunningStateException Will be thrown if you try to change the instanceID after the application has already been started

See also: App::exec

◆ exec()

QtBackgroundProcess::App::exec ( )

Executes the application event loop.

Inherits QCoreApplication::exec

Returns: The applications exit code

A reimplementation of exec, to perform the neccesary steps to start the execution.

Attention: It is very important you call this function, and not QCoreApplication::exec. If you don't, the background process won't properly start

See also: App::startupApp

◆ requestAppShutdown()

QtBackgroundProcess::App::requestAppShutdown	(	Terminal *	terminal,
		int &	exitCode
	)

protectedvirtual

Gets called when a terminal requests a shutdown of the master.

Parameters

terminal	The terminal that requested the shutdown
exitCode	A reference to the exit code. Set this code if another value than `EXIT_SUCCESS` should be returned by the app. Ignored if not returning `true`

Returns: true if the shutdown request should be accepted, false if not

You can override this function to decide whether your application should accept the stop command and shut down (return true) or ignore it (return false). The default implementation calls the handler set by App::setStartupFunction, if available, or simply returns true, if no handler has been set.

See also: App::setStartupFunction

◆ setInstanceID

QtBackgroundProcess::App::setInstanceID	(	QString	instanceID,
		bool	useAsSeed = `true`
	)

slot

WRITE accessor for App::instanceID.

Parameters

instanceID	The instance id or the seed for the id
useAsSeed	If set to yes, the instanceID will be used as a seed, and not set directly

Exceptions

NotAllowedInRunningStateException Will be thrown if you try to change the instanceID after the application has already been started

If useAsSeed is false, whatever you pass as instanceID is used as the new id. If set to true, the id will be generated as usual, but with instanceID as seed to modify it. This has the advantage of maintaining the uniqueness of the default instanceID, without beeing limit to a single one.

◆ setParserSetupFunction()

QtBackgroundProcess::App::setParserSetupFunction ( const std::function< void(QCommandLineParser &)> & function )

Sets the function to be called for the creation of the parser (Instead of overriding)

Parameters

function The function to be called by App::setupParser

The handlers parameter are:

the command line parser to be set up (QCommandLineParser &)

Note: The parsers passed to this function are already set up with the options and arguments required for the app itself. You can simply add your own ones.

See also: App::setupParser

◆ setShutdownRequestFunction() [1/2]

QtBackgroundProcess::App::setShutdownRequestFunction ( const std::function< bool(const QCommandLineParser &, int &)> & function )

Sets the function to be called to handle shutdown requests (Instead of overriding)

Parameters

function The function to be called by App::requestAppShutdown

The handlers parameter are:

a command line parser holding the stop arguments (QCommandLineParser)
a reference to the exit code. Set this code if another value than EXIT_SUCCESS should be returned by the app (int &)
returns: true if the shutdown request should be accepted, false if not

See also: App::requestAppShutdown

◆ setShutdownRequestFunction() [2/2]

QtBackgroundProcess::App::setShutdownRequestFunction ( const std::function< bool(Terminal *, int &)> & function )

Sets the function to be called to handle shutdown requests (Instead of overriding)

Parameters

function The function to be called by App::requestAppShutdown

See App::requestAppShutdown for the handlers arguments.

See also: App::requestAppShutdown

◆ setStartupFunction()

QtBackgroundProcess::App::setStartupFunction ( const std::function< int(const QCommandLineParser &)> & function )

Sets the function to be called to startup the application (Instead of overriding)

Parameters

function The function to be called by App::startupApp

See App::startupApp for the handlers arguments.

See also: App::startupApp

◆ setupParser()

QtBackgroundProcess::App::setupParser	(	QCommandLineParser &	parser,
		bool	useShortOptions = `true`
	)

protectedvirtual

Sets up the parser to parse commands and arguments.

Parameters

parser	The command line parser to be set up
useShortOptions	Specify if short options should be enabled

You can override this function to add additional options and arguments to the apps command line parser. The default implementation performs a basic setup and calls the handler set by App::setParserSetupFunction, if available. setup.

Attention: In order to do the setup required by the app, you will have to call this implementation in your override! The useShortOptions parameter will always be true. If you don't want short options, pass a different value to the base implementation

Sample:

void MyApp::setupParser(...)
{
    QtBackgroundProcess::App::setupParser(parser, useShortOptions);// or (parser, false)
    parser.addOption(...);
}

See also: App::setParserSetupFunction

◆ startupApp()

QtBackgroundProcess::App::startupApp ( const QCommandLineParser & parser )

protectedvirtual

Is called as initialization function of the master process.

Parameters

parser a command line parser holding the startup arguments

Returns: The start exit code. Pass EXIT_SUCCESS to continue execution. Anything else will induce an error and stop the master with the given code

You can override this function to add the code that should be run to startup the master process. The default implementation calls the handler set by App::setStartupFunction, if available.

See also: App::setStartupFunction

Property Documentation

◆ autoDeleteTerminals

QtBackgroundProcess::App::autoDeleteTerminals

readwrite

If true, the master process will automatically delete terminals that have been disconnected.

Default: true

If a terminal gets disconnected, the master can automatically delete it. Each terminal has it's own property to enable/disable auto deletion. By setting this property, you can set the default for newly created terminals. Disable it, if you handle terminals by yourself.

Note: To change the Terminal::autoDelete for all already connected terminals, pass true as second parameter to the set accessor

Accessors
READ	autoDeleteTerminals()
WRITE	setAutoDeleteTerminals()

See also: App::autoKillTerminals, Terminal::autoDelete

Definition at line 48 of file app.h.

◆ autoKillTerminals

QtBackgroundProcess::App::autoKillTerminals

readwrite

If true, the master process will automatically close terminals after it received the parameters.

Default: false

If you don't want terminals to be able to attach to the master, and only want to use them to receive new commands, you can enable this property. After receiving the command, the master automatically disconnects the terminal and deletes it.

Note: Setting this to true will prevent terminals from beeing added to the terminal list, and will not emit newTerminalConnected() anymore. However, commandReceived() with the command of the terminal is still beeing used.; To kill all already connected terminals, pass true as second parameter to the set accessor

Accessors
READ	autoKillTerminals()
WRITE	setAutoKillTerminals()

See also: App::autoDeleteTerminals, App::commandReceived

Definition at line 50 of file app.h.

◆ autoStartMaster

QtBackgroundProcess::App::autoStartMaster

readwrite

If true, the master process will always be started, not only with "start".

Default: false

By default, you need to explicitly pass start as parameter to start the master process. If you want this to happen automatically, set this property to true in terminal scope! Do it before calling exec() in your main.

Note: If the master is already running, this property has no effect

Accessors
READ	autoStartMaster()
WRITE	setAutoStartMaster()

See also: App::ignoreMultiStarts, App::exec

Definition at line 44 of file app.h.

◆ connectedTerminals

QtBackgroundProcess::App::connectedTerminals

read

Holds a list of all currently connected terminals.

Default: []

Every time a terminal was connected or disconnect, this property changes. This does not include terminals that connect with the --detached option, as well as automatically killed terminals.

Accessors
READ	connectedTerminals()
NOTIFY	connectedTerminalsChanged()
NOTIFY	newTerminalConnected() (implicit)

See also: App::autoKillTerminals, App::commandReceived

Definition at line 52 of file app.h.

◆ forwardMasterLog

QtBackgroundProcess::App::forwardMasterLog

readwrite

Specifies, whether the master should forward debug output to all terminals.

Default: false

If enabled, the master process will forward everything it writes to the logfile to all connected terminals as well. This includes all qDebug, qWarning, etc. kinds of messages. If you want this to work for all master messages, even before the startup function was called, set this true in terminal scope, i.e. the main function. This property has no effect on terminals.

Accessors
READ	forwardMasterLog()
WRITE	setForwardMasterLog()

See also: GlobalTerminal, Terminal, App::startupApp

Definition at line 42 of file app.h.

◆ ignoreMultiStarts

QtBackgroundProcess::App::ignoreMultiStarts

readwrite

If true, "start" commands will be ignored, if the master is already running.

Default: false

By default, start commands will be passed to the master as is, if it is already running. If you don't want this to happen, because you treat starts differently, set this property to true. This will cause terminals that try to call start on a running master to discard all arguments and connect with an empty arguments list.

Note: This property only prevents explicit start calls. It does not interfere with the App::autoStartMaster property.

Accessors
READ	ignoreMultiStarts()
WRITE	setIgnoreMultiStarts()

See also: App::autoStartMaster, App::startupApp

Definition at line 46 of file app.h.

◆ instanceID

QtBackgroundProcess::App::instanceID

readwrite

The current id of the singleton instance of the master process.

Default: empty, until exec() is called

The instance ID is an id that is generated for an application to identify it on runtime. It is the same for multiple instances of an application run by the same user/session, but unique for every "application". It is used internally for the singleton instance and to connecte the terminals to the correct master. Unless you need to run multiple master instances of the same application, there is typically no need to modify this variable.

The id will be generated automatically as soon as you call App::exec. If you need the id before that, you can generate it using App::createDefaultInstanceID.

Note: The instance id is generated by using various information about the application. This includes properties that can be set in the main, like QCoreApplication::setOrganizationName. In order to include those, the generation is lazy. If you need to generate it on your own, make shure to do so after those initializations.

Accessors
READ	instanceID()
WRITE	setInstanceID()
RESET	createDefaultInstanceID()

See also: App::exec

Definition at line 40 of file app.h.

The documentation for this class was generated from the following files:

app.h
app.dox

Public Slots

Signals

Public Member Functions

Protected Member Functions

Properties

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ commandReceived

◆ createDefaultInstanceID

◆ exec()

◆ requestAppShutdown()

◆ setInstanceID

◆ setParserSetupFunction()

◆ setShutdownRequestFunction() [1/2]

◆ setShutdownRequestFunction() [2/2]

◆ setStartupFunction()

◆ setupParser()

◆ startupApp()

Property Documentation

◆ autoDeleteTerminals

◆ autoKillTerminals

◆ autoStartMaster

◆ connectedTerminals

◆ forwardMasterLog

◆ ignoreMultiStarts

◆ instanceID