KUniqueApplication Class Reference

#include <kuniqueapplication.h>

Inheritance diagram for KUniqueApplication:

Public Types
enum	StartFlag { NonUniqueInstance = 0x1 }
typedef QFlags< StartFlag >	StartFlags
Public Types inherited from QApplication
enum	ColorSpec
Public Types inherited from QCoreApplication
enum	Encoding

Public Member Functions
	KUniqueApplication (bool GUIenabled=true, bool configUnique=false)
	~KUniqueApplication () override
virtual int	newInstance ()
bool	restoringSession ()
Public Member Functions inherited from KApplication
	KApplication (bool GUIenabled=true)
void	clearStartupId ()
void	disableSessionManagement ()
void	enableSessionManagement ()
void	installX11EventFilter (QWidget *filter)
void	removeX11EventFilter (const QWidget *filter)
KConfig *	sessionConfig ()
bool	sessionSaving () const
void	setStartupId (const QByteArray &startup_id)
void	setTopWidget (QWidget *topWidget)
QByteArray	startupId () const
void	updateRemoteUserTimestamp (const QString &service, int time=0)
unsigned long	userTimestamp () const
Public Member Functions inherited from QApplication
	QApplication (int &argc, char **argv)
bool	autoSipEnabled () const const
void	focusChanged (QWidget *old, QWidget *now)
virtual bool	notify (QObject *receiver, QEvent *e) override
	qApp qApp
void	setAutoSipEnabled (const bool enabled)
void	setStyleSheet (const QString &sheet)
QString	styleSheet () const const
Public Member Functions inherited from QGuiApplication
	QGuiApplication (int &argc, char **argv)
void	applicationDisplayNameChanged ()
void	applicationStateChanged (Qt::ApplicationState state)
void	commitDataRequest (QSessionManager &manager)
qreal	devicePixelRatio () const const
void	focusObjectChanged (QObject *focusObject)
void	focusWindowChanged (QWindow *focusWindow)
void	fontChanged (const QFont &font)
void	fontDatabaseChanged ()
bool	isSavingSession () const const
bool	isSessionRestored () const const
void	lastWindowClosed ()
void	layoutDirectionChanged (Qt::LayoutDirection direction)
void	paletteChanged (const QPalette &palette)
void	primaryScreenChanged (QScreen *screen)
	qGuiApp qGuiApp
void	saveStateRequest (QSessionManager &manager)
void	screenAdded (QScreen *screen)
void	screenRemoved (QScreen *screen)
QString	sessionId () const const
QString	sessionKey () const const
Public Member Functions inherited from QCoreApplication
	QCoreApplication (int &argc, char **argv)
void	aboutToQuit ()
void	applicationNameChanged ()
void	applicationVersionChanged ()
void	installNativeEventFilter (QAbstractNativeEventFilter *filterObj)
void	organizationDomainChanged ()
void	organizationNameChanged ()
	Q_COREAPP_STARTUP_FUNCTION (ptr)
	Q_DECLARE_TR_FUNCTIONS (context)
void	qAddPostRoutine (QtCleanUpFunction ptr)
void	qRemovePostRoutine (QtCleanUpFunction ptr)
void	removeNativeEventFilter (QAbstractNativeEventFilter *filterObject)
Public Member Functions inherited from QObject
	QObject (QObject *parent)
bool	blockSignals (bool block)
const QObjectList &	children () const const
QMetaObject::Connection	connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
void	deleteLater ()
void	destroyed (QObject *obj)
bool	disconnect (const char *signal, const QObject *receiver, const char *method) const const
bool	disconnect (const QObject *receiver, const char *method) const const
void	dumpObjectInfo ()
void	dumpObjectInfo () const const
void	dumpObjectTree ()
void	dumpObjectTree () const const
QList< QByteArray >	dynamicPropertyNames () const const
virtual bool	eventFilter (QObject *watched, QEvent *event)
T	findChild (const QString &name, Qt::FindChildOptions options) const const
QList< T >	findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const
bool	inherits (const char *className) const const
void	installEventFilter (QObject *filterObj)
bool	isWidgetType () const const
bool	isWindowType () const const
void	killTimer (int id)
virtual const QMetaObject *	metaObject () const const
void	moveToThread (QThread *targetThread)
QString	objectName () const const
void	objectNameChanged (const QString &objectName)
QObject *	parent () const const
QVariant	property (const char *name) const const
	Q_CLASSINFO (Name, Value)
	Q_DISABLE_COPY (Class)
	Q_DISABLE_COPY_MOVE (Class)
	Q_DISABLE_MOVE (Class)
	Q_EMIT Q_EMIT
	Q_ENUM (...)
	Q_ENUM_NS (...)
	Q_ENUMS (...)
	Q_FLAG (...)
	Q_FLAG_NS (...)
	Q_FLAGS (...)
	Q_GADGET Q_GADGET
	Q_INTERFACES (...)
	Q_INVOKABLE Q_INVOKABLE
	Q_NAMESPACE Q_NAMESPACE
	Q_NAMESPACE_EXPORT (EXPORT_MACRO)
	Q_OBJECT Q_OBJECT
	Q_PROPERTY (...)
	Q_REVISION Q_REVISION
	Q_SET_OBJECT_NAME (Object)
	Q_SIGNAL Q_SIGNAL
	Q_SIGNALS Q_SIGNALS
	Q_SLOT Q_SLOT
	Q_SLOTS Q_SLOTS
T	qFindChild (const QObject *obj, const QString &name)
QList< T >	qFindChildren (const QObject *obj, const QRegExp &regExp)
QList< T >	qFindChildren (const QObject *obj, const QString &name)
T	qobject_cast (const QObject *object)
T	qobject_cast (QObject *object)
	QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
void	removeEventFilter (QObject *obj)
void	setObjectName (const QString &name)
void	setParent (QObject *parent)
bool	setProperty (const char *name, const QVariant &value)
bool	signalsBlocked () const const
int	startTimer (int interval, Qt::TimerType timerType)
int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)
QThread *	thread () const const

Static Public Member Functions
static void	addCmdLineOptions ()
static void	setHandleAutoStarted ()
static bool	start ()
static bool	start (StartFlags flags)
Static Public Member Functions inherited from KApplication
static QString	checkRecoverFile (const QString &pFilename, bool &bRecover)
static KApplication *	kApplication ()
static QString	tempSaveName (const QString &pFilename)
Static Public Member Functions inherited from QApplication
void	aboutQt ()
QWidget *	activeModalWidget ()
QWidget *	activePopupWidget ()
QWidget *	activeWindow ()
void	alert (QWidget *widget, int msec)
QWidgetList	allWidgets ()
void	beep ()
void	closeAllWindows ()
int	colorSpec ()
int	cursorFlashTime ()
QDesktopWidget *	desktop ()
int	doubleClickInterval ()
int	exec ()
QWidget *	focusWidget ()
QFont	font ()
QFont	font (const char *className)
QFont	font (const QWidget *widget)
QFontMetrics	fontMetrics ()
QSize	globalStrut ()
bool	isEffectEnabled (Qt::UIEffect effect)
int	keyboardInputInterval ()
bool	keypadNavigationEnabled ()
Qt::NavigationMode	navigationMode ()
QPalette	palette (const char *className)
QPalette	palette (const QWidget *widget)
void	setActiveWindow (QWidget *active)
void	setColorSpec (int spec)
void	setCursorFlashTime (int)
void	setDoubleClickInterval (int)
void	setEffectEnabled (Qt::UIEffect effect, bool enable)
void	setFont (const QFont &font, const char *className)
void	setGlobalStrut (const QSize &)
void	setKeyboardInputInterval (int)
void	setKeypadNavigationEnabled (bool enable)
void	setNavigationMode (Qt::NavigationMode mode)
void	setPalette (const QPalette &palette, const char *className)
void	setStartDragDistance (int l)
void	setStartDragTime (int ms)
QStyle *	setStyle (const QString &style)
void	setStyle (QStyle *style)
void	setWheelScrollLines (int)
void	setWindowIcon (const QIcon &icon)
int	startDragDistance ()
int	startDragTime ()
QStyle *	style ()
QWidget *	topLevelAt (const QPoint &point)
QWidget *	topLevelAt (int x, int y)
QWidgetList	topLevelWidgets ()
int	wheelScrollLines ()
QWidget *	widgetAt (const QPoint &point)
QWidget *	widgetAt (int x, int y)
QIcon	windowIcon ()
Static Public Member Functions inherited from QGuiApplication
QWindowList	allWindows ()
QString	applicationDisplayName ()
Qt::ApplicationState	applicationState ()
void	changeOverrideCursor (const QCursor &cursor)
QClipboard *	clipboard ()
QString	desktopFileName ()
bool	desktopSettingsAware ()
int	exec ()
QObject *	focusObject ()
QWindow *	focusWindow ()
QFont	font ()
Qt::HighDpiScaleFactorRoundingPolicy	highDpiScaleFactorRoundingPolicy ()
QInputMethod *	inputMethod ()
bool	isFallbackSessionManagementEnabled ()
bool	isLeftToRight ()
bool	isRightToLeft ()
Qt::KeyboardModifiers	keyboardModifiers ()
Qt::LayoutDirection	layoutDirection ()
QWindow *	modalWindow ()
Qt::MouseButtons	mouseButtons ()
QCursor *	overrideCursor ()
QPalette	palette ()
QFunctionPointer	platformFunction (const QByteArray &function)
QString	platformName ()
QPlatformNativeInterface *	platformNativeInterface ()
QScreen *	primaryScreen ()
Qt::KeyboardModifiers	queryKeyboardModifiers ()
bool	quitOnLastWindowClosed ()
void	restoreOverrideCursor ()
QScreen *	screenAt (const QPoint &point)
QList< QScreen * >	screens ()
void	setApplicationDisplayName (const QString &name)
void	setDesktopFileName (const QString &name)
void	setDesktopSettingsAware (bool on)
void	setFallbackSessionManagementEnabled (bool enabled)
void	setFont (const QFont &font)
void	setHighDpiScaleFactorRoundingPolicy (Qt::HighDpiScaleFactorRoundingPolicy policy)
void	setLayoutDirection (Qt::LayoutDirection direction)
void	setOverrideCursor (const QCursor &cursor)
void	setPalette (const QPalette &pal)
void	setQuitOnLastWindowClosed (bool quit)
void	setWindowIcon (const QIcon &icon)
QStyleHints *	styleHints ()
void	sync ()
QWindow *	topLevelAt (const QPoint &pos)
QWindowList	topLevelWindows ()
QIcon	windowIcon ()
Static Public Member Functions inherited from QCoreApplication
void	addLibraryPath (const QString &path)
QString	applicationDirPath ()
QString	applicationFilePath ()
QString	applicationName ()
qint64	applicationPid ()
QString	applicationVersion ()
QStringList	arguments ()
bool	closingDown ()
QAbstractEventDispatcher *	eventDispatcher ()
int	exec ()
void	exit (int returnCode)
void	flush ()
bool	hasPendingEvents ()
bool	installTranslator (QTranslator *translationFile)
QCoreApplication *	instance ()
bool	isQuitLockEnabled ()
bool	isSetuidAllowed ()
QStringList	libraryPaths ()
QString	organizationDomain ()
QString	organizationName ()
void	postEvent (QObject *receiver, QEvent *event, int priority)
void	processEvents (QEventLoop::ProcessEventsFlags flags)
void	processEvents (QEventLoop::ProcessEventsFlags flags, int ms)
void	quit ()
void	removeLibraryPath (const QString &path)
void	removePostedEvents (QObject *receiver, int eventType)
bool	removeTranslator (QTranslator *translationFile)
bool	sendEvent (QObject *receiver, QEvent *event)
void	sendPostedEvents (QObject *receiver, int event_type)
void	setApplicationName (const QString &application)
void	setApplicationVersion (const QString &version)
void	setAttribute (Qt::ApplicationAttribute attribute, bool on)
void	setEventDispatcher (QAbstractEventDispatcher *eventDispatcher)
void	setLibraryPaths (const QStringList &paths)
void	setOrganizationDomain (const QString &orgDomain)
void	setOrganizationName (const QString &orgName)
void	setQuitLockEnabled (bool enabled)
void	setSetuidAllowed (bool allow)
bool	startingUp ()
bool	testAttribute (Qt::ApplicationAttribute attribute)
QString	translate (const char *context, const char *key, const char *disambiguation, QCoreApplication::Encoding encoding, int n)
QString	translate (const char *context, const char *sourceText, const char *disambiguation, int n)
Static Public Member Functions inherited from QObject
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 *context, Functor functor, 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)
bool	disconnect (const QMetaObject::Connection &connection)
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 QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
QString	tr (const char *sourceText, const char *disambiguation, int n)
QString	trUtf8 (const char *sourceText, const char *disambiguation, int n)

Additional Inherited Members
Properties inherited from QApplication
	autoSipEnabled
	cursorFlashTime
	doubleClickInterval
	globalStrut
	keyboardInputInterval
	startDragDistance
	startDragTime
	styleSheet
	wheelScrollLines
	windowIcon
Properties inherited from QGuiApplication
	applicationDisplayName
	desktopFileName
	layoutDirection
	platformName
	primaryScreen
	quitOnLastWindowClosed
	windowIcon
Properties inherited from QCoreApplication
	applicationName
	applicationVersion
	organizationDomain
	organizationName
	quitLockEnabled
Properties inherited from QObject
	objectName
Signals inherited from KApplication
void	saveYourself ()
Public Slots inherited from KApplication
void	commitData (QSessionManager &sm)
Q_SCRIPTABLE void	quit ()
Q_SCRIPTABLE void	reparseConfiguration ()
void	saveState (QSessionManager &sm)
Q_SCRIPTABLE void	updateUserTimestamp (int time=0)
Public Attributes inherited from QApplication
	CustomColor
	ManyColor
	NormalColor
Public Attributes inherited from QCoreApplication
	CodecForTr
	DefaultCodec
	Latin1
	UnicodeUTF8
Public Attributes inherited from QObject
typedef	QObjectList
Protected Member Functions inherited from KApplication
	KApplication (bool GUIenabled, const KComponentData &cData)
Protected Member Functions inherited from QApplication
virtual bool	event (QEvent *e) override
Protected Member Functions inherited from QObject
virtual void	childEvent (QChildEvent *event)
virtual void	connectNotify (const QMetaMethod &signal)
virtual void	customEvent (QEvent *event)
virtual void	disconnectNotify (const QMetaMethod &signal)
bool	isSignalConnected (const QMetaMethod &signal) const const
int	receivers (const char *signal) const const
QObject *	sender () const const
int	senderSignalIndex () const const
virtual void	timerEvent (QTimerEvent *event)
Static Protected Attributes inherited from KApplication
static KApplication *	KApp = nullptr

Detailed Description

KUniqueApplication is a KApplication which only uses a single process.

When a KUniqueApplication is started, it attempts to contact an existing copy of the application. If successful, the program asks the existing process to create a new instance by calling its newInstance() method and then exits. If there is no existing process then the program forks and calls the newInstance() method. When newInstance() is called, the application will typically create a new window or activate an existing one.

Instances of KUniqueApplication can be made to behave like a normal application by passing the StartFlag::NonUniqueInstance flag to start().

Please note that this supports only one process per KDE session. If your application can only be opened once per user or once per host, you need to ensure this independently of KUniqueApplication.

The .desktop file for the application should state X-DBUS-StartupType=Unique, see ktoolinvocation.h

If you use command line options before start() is called, you MUST call addCmdLineOptions() so that the KUniqueApplication-specific command-line options can still work.

If your application is used to open files, it should also support the –tempfile option (see KCmdLineArgs::addTempFileOption()), to delete tempfiles after use. Add X-KDE-HasTempFileOption=true to the .desktop file to indicate this.

See also

KApplication

Author

Preston Brown pbrow[email protected][email protected][email protected]e.org

Definition at line 56 of file kuniqueapplication.h.

Member Enumeration Documentation

StartFlag

enum KUniqueApplication::StartFlag

These flags can be used to specify how new instances of unique applications are created.

Enumerator

NonUniqueInstance

Create a new instance of the application in a new process and do not attempt to re-use an existing process. With this flag set, the new instance of the application will behave as if it were a plain KApplication rather than a KUniqueApplication. This is useful if you have an application where all instances are typically run in a single process but under certain circumstances new instances may require their own process.

Definition at line 84 of file kuniqueapplication.h.

Constructor & Destructor Documentation

KUniqueApplication()

KUniqueApplication::KUniqueApplication ( bool  GUIenabled = true, bool  configUnique = false  )

explicit

Constructor.

Takes command line arguments from KCmdLineArgs

Parameters

GUIenabled	Set to false to disable all GUI stuff. This implies no styles either.
configUnique	If true, the uniqueness of the application will depend on the value of the "MultipleInstances" key in the "KDE" group of the application config file.

Definition at line 307 of file kuniqueapplication.cpp.

~KUniqueApplication()

KUniqueApplication::~KUniqueApplication ( )

override

Destructor.

Definition at line 324 of file kuniqueapplication.cpp.

Member Function Documentation

addCmdLineOptions()

void KUniqueApplication::addCmdLineOptions ( )

static

Adds command line options specific for KUniqueApplication.

Should be called before calling KUniqueApplication constructor and / or start().

Definition at line 76 of file kuniqueapplication.cpp.

newInstance()

int KUniqueApplication::newInstance ( )

virtual

Creates a new "instance" of the application.

Usually this will involve making some calls into the GUI portion of your application asking for a new window to be created, possibly with some data already loaded based on the arguments received.

Command line arguments have been passed to KCmdLineArgs before this function is called and can be checked in the usual way.

The default implementation ensures the mainwindow of the already running instance is shown and activated if necessary. If your application has only one mainwindow, you should call this default implementation and only add your special handling if needed.

Note that newInstance() is called also in the first started application process.

For applications that share one process for several mainwindows, the reimplementation could be:

int MyApp::newInstance()
{
KCmdLineArgs::setCwd(QDir::currentPath().toUtf8());
KCmdLineArgs* args = KCmdLineArgs::parsedArgs();
static bool first = true;
if (args->count() > 0) {
    for (int i = 0; i < args->count(); ++i) {
        openWindow(args->url(i));
    }
} else if( !first || !isSessionRestored()) {
    openWindow(KUrl()); // create a new window
}
first = false;
args->clear();
return 0;
}

Returns

An exit value. The calling process will exit with this value.

Definition at line 356 of file kuniqueapplication.cpp.

restoringSession()

bool KUniqueApplication::restoringSession

(

)

Returns whether newInstance() is being called while session restoration is in progress.

Definition at line 351 of file kuniqueapplication.cpp.

setHandleAutoStarted()

void KUniqueApplication::setHandleAutoStarted ( )

static

Definition at line 385 of file kuniqueapplication.cpp.

start()

bool KUniqueApplication::start ( StartFlags  flags )

static

Forks and registers with D-Bus.

The command line arguments are being sent via D-Bus to newInstance() and will be received once the application enters the event loop.

Typically this is used like:

int main(int argc, char **argv) {
   KAboutData about("myappname", 0, ki18n("myAppName"), .....);
   KCmdLineArgs::init(argc, argv, &about);
   KCmdLineArgs::addCmdLineOptions( myCmdOptions );
   KUniqueApplication::addCmdLineOptions();
 
   if (!KUniqueApplication::start()) {
      fprintf(stderr, "myAppName is already running!\n");
      return 0;
   }
   KUniqueApplication a;
   return a.exec();
}

Note that it's not necessary to call start() explicitly. It will be called automatically before creating KUniqueApplication if it hasn't been called yet, without any performance impact.

Also note that you MUST call KUniqueApplication::addCmdLineOptions(), if you use command line options before start() is called.

Parameters

flags

Optional flags which control how a new instance of the application is started.

Returns

true if registration is successful. false if another process was already running.

Definition at line 104 of file kuniqueapplication.cpp.

---

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

• kuniqueapplication.h
• kuniqueapplication.cpp