KUniqueApplication

#include <kuniqueapplication.h>

Inheritance diagram for KUniqueApplication:

Public Types

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

Public Member Functions

 KUniqueApplication (bool GUIenabled=true, bool configUnique=false)
 
virtual ~KUniqueApplication ()
 
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)
 
KConfigsessionConfig ()
 
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 QObjectListchildren () 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< QByteArraydynamicPropertyNames () const const
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (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
 
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 QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () 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
 
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)
 
qobject_cast (QObject *object)
 
qobject_cast (const 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)
 
QThreadthread () const const
 

Static Public Member Functions

static void addCmdLineOptions ()
 
static void setHandleAutoStarted ()
 
static bool start (StartFlags flags)
 
static bool start ()
 
- Static Public Member Functions inherited from KApplication
static QString checkRecoverFile (const QString &pFilename, bool &bRecover)
 
static KApplicationkApplication ()
 
static QString tempSaveName (const QString &pFilename)
 
- Static Public Member Functions inherited from QApplication
void aboutQt ()
 
QWidgetactiveModalWidget ()
 
QWidgetactivePopupWidget ()
 
QWidgetactiveWindow ()
 
void alert (QWidget *widget, int msec)
 
QWidgetList allWidgets ()
 
void beep ()
 
void closeAllWindows ()
 
int colorSpec ()
 
int cursorFlashTime ()
 
QDesktopWidgetdesktop ()
 
int doubleClickInterval ()
 
int exec ()
 
QWidgetfocusWidget ()
 
QFont font ()
 
QFont font (const QWidget *widget)
 
QFont font (const char *className)
 
QFontMetrics fontMetrics ()
 
QSize globalStrut ()
 
bool isEffectEnabled (Qt::UIEffect effect)
 
int keyboardInputInterval ()
 
bool keypadNavigationEnabled ()
 
Qt::NavigationMode navigationMode ()
 
QPalette palette (const QWidget *widget)
 
QPalette palette (const char *className)
 
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)
 
void setStyle (QStyle *style)
 
QStylesetStyle (const QString &style)
 
void setWheelScrollLines (int)
 
void setWindowIcon (const QIcon &icon)
 
int startDragDistance ()
 
int startDragTime ()
 
QStylestyle ()
 
QWidgettopLevelAt (int x, int y)
 
QWidgettopLevelAt (const QPoint &point)
 
QWidgetList topLevelWidgets ()
 
int wheelScrollLines ()
 
QWidgetwidgetAt (int x, int y)
 
QWidgetwidgetAt (const QPoint &point)
 
QIcon windowIcon ()
 
- Static Public Member Functions inherited from QGuiApplication
QWindowList allWindows ()
 
QString applicationDisplayName ()
 
Qt::ApplicationState applicationState ()
 
void changeOverrideCursor (const QCursor &cursor)
 
QClipboardclipboard ()
 
QString desktopFileName ()
 
bool desktopSettingsAware ()
 
int exec ()
 
QObjectfocusObject ()
 
QWindowfocusWindow ()
 
QFont font ()
 
Qt::HighDpiScaleFactorRoundingPolicy highDpiScaleFactorRoundingPolicy ()
 
QInputMethodinputMethod ()
 
bool isFallbackSessionManagementEnabled ()
 
bool isLeftToRight ()
 
bool isRightToLeft ()
 
Qt::KeyboardModifiers keyboardModifiers ()
 
Qt::LayoutDirection layoutDirection ()
 
QWindowmodalWindow ()
 
Qt::MouseButtons mouseButtons ()
 
QCursoroverrideCursor ()
 
QPalette palette ()
 
QFunctionPointer platformFunction (const QByteArray &function)
 
QString platformName ()
 
QPlatformNativeInterface * platformNativeInterface ()
 
QScreenprimaryScreen ()
 
Qt::KeyboardModifiers queryKeyboardModifiers ()
 
bool quitOnLastWindowClosed ()
 
void restoreOverrideCursor ()
 
QScreenscreenAt (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)
 
QStyleHintsstyleHints ()
 
void sync ()
 
QWindowtopLevelAt (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 ()
 
QAbstractEventDispatchereventDispatcher ()
 
int exec ()
 
void exit (int returnCode)
 
void flush ()
 
bool hasPendingEvents ()
 
bool installTranslator (QTranslator *translationFile)
 
QCoreApplicationinstance ()
 
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 *sourceText, const char *disambiguation, int n)
 
QString translate (const char *context, const char *key, const char *disambiguation, QCoreApplication::Encoding encoding, 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 *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 QMetaObject::Connection &connection)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &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
 
QObjectsender () const const
 
int senderSignalIndex () const const
 
virtual void timerEvent (QTimerEvent *event)
 
- Static Protected Attributes inherited from KApplication
static KApplicationKApp = 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

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 ( bool  GUIenabled = true,
bool  configUnique = false 
)
explicit

Constructor.

Takes command line arguments from KCmdLineArgs

Parameters
GUIenabledSet to false to disable all GUI stuff. This implies no styles either.
configUniqueIf 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 ( )
virtual

Destructor.

Definition at line 324 of file kuniqueapplication.cpp.

Member Function Documentation

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.

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()
{
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.

bool KUniqueApplication::restoringSession ( )

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

Definition at line 351 of file kuniqueapplication.cpp.

void KUniqueApplication::setHandleAutoStarted ( )
static

Definition at line 385 of file kuniqueapplication.cpp.

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);
if (!KUniqueApplication::start()) {
fprintf(stderr, "myAppName is already running!\n");
return 0;
}
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
flagsOptional 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:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Thu Aug 13 2020 22:58:33 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.