KDELibs4Support

kuniqueapplication.h
1 /* This file is part of the KDE libraries
2  Copyright (c) 1999 Preston Brown <[email protected]>
3  Copyright (c) 2000-2001 Waldo Bastian <[email protected]>
4 
5  This library is free software; you can redistribute it and/or
6  modify it under the terms of the GNU Library General Public
7  License as published by the Free Software Foundation; either
8  version 2 of the License, or (at your option) any later version.
9 
10  This library is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13  Library General Public License for more details.
14 
15  You should have received a copy of the GNU Library General Public License
16  along with this library; see the file COPYING.LIB. If not, write to
17  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18  Boston, MA 02110-1301, USA.
19 */
20 
21 #ifndef KUNIQUEAPP_H
22 #define KUNIQUEAPP_H
23 
24 #include <kdelibs4support_export.h>
25 #include <kapplication.h>
26 
27 /**
28  * KUniqueApplication is a KApplication which only uses a single process. When
29  * a KUniqueApplication is started, it attempts to contact an existing copy
30  * of the application. If successful, the program asks the
31  * existing process to create a new instance by calling its newInstance() method
32  * and then exits. If there is no existing process then the program forks and
33  * calls the newInstance() method. When newInstance() is called, the application
34  * will typically create a new window or activate an existing one.
35  *
36  * Instances of KUniqueApplication can be made to behave like a normal application by passing
37  * the StartFlag::NonUniqueInstance flag to start().
38  *
39  * Please note that this supports only one process per KDE session. If
40  * your application can only be opened once per user or once per host, you
41  * need to ensure this independently of KUniqueApplication.
42  *
43  * The .desktop file for the application should state X-DBUS-StartupType=Unique,
44  * see ktoolinvocation.h
45  *
46  * If you use command line options before start() is called, you MUST call addCmdLineOptions()
47  * so that the KUniqueApplication-specific command-line options can still work.
48  *
49  * If your application is used to open files, it should also support the --tempfile
50  * option (see KCmdLineArgs::addTempFileOption()), to delete tempfiles after use.
51  * Add X-KDE-HasTempFileOption=true to the .desktop file to indicate this.
52  *
53  * @see KApplication
54  * @author Preston Brown <[email protected]>
55  */
56 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KUniqueApplication : public KApplication
57 {
58  Q_OBJECT
59 public:
60  /**
61  * Constructor. Takes command line arguments from KCmdLineArgs
62  *
63  * @param GUIenabled Set to false to disable all GUI stuff. This implies
64  * no styles either.
65  * @param configUnique If true, the uniqueness of the application will
66  * depend on the value of the "MultipleInstances"
67  * key in the "KDE" group of the application config file.
68  */
69  KDELIBS4SUPPORT_DEPRECATED explicit KUniqueApplication(bool GUIenabled = true,
70  bool configUnique = false);
71 
72  /**
73  * Adds command line options specific for KUniqueApplication.
74  *
75  * Should be called before calling KUniqueApplication constructor
76  * and / or start().
77  */
78  static void addCmdLineOptions();
79 
80  /**
81  * These flags can be used to specify how new instances of
82  * unique applications are created.
83  */
84  enum StartFlag {
85  /**
86  * Create a new instance of the application in a new process and
87  * do not attempt to re-use an existing process.
88  *
89  * With this flag set, the new instance of the application will
90  * behave as if it were a plain KApplication rather than a KUniqueApplication.
91  *
92  * This is useful if you have an application where all instances are typically run
93  * in a single process but under certain circumstances new instances may require
94  * their own process.
95  */
96  NonUniqueInstance = 0x1
97  };
98  Q_DECLARE_FLAGS(StartFlags, StartFlag)
99 
100  /**
101  * Forks and registers with D-Bus.
102  *
103  * The command line arguments are being sent via D-Bus to newInstance()
104  * and will be received once the application enters the event loop.
105  *
106  * Typically this is used like:
107  * \code
108  * int main(int argc, char **argv) {
109  * KAboutData about("myappname", 0, ki18n("myAppName"), .....);
110  * KCmdLineArgs::init(argc, argv, &about);
111  * KCmdLineArgs::addCmdLineOptions( myCmdOptions );
112  * KUniqueApplication::addCmdLineOptions();
113  *
114  * if (!KUniqueApplication::start()) {
115  * fprintf(stderr, "myAppName is already running!\n");
116  * return 0;
117  * }
118  * KUniqueApplication a;
119  * return a.exec();
120  * }
121  * \endcode
122  * Note that it's not necessary to call start() explicitly. It will be
123  * called automatically before creating KUniqueApplication if it hasn't
124  * been called yet, without any performance impact.
125  *
126  * Also note that you MUST call KUniqueApplication::addCmdLineOptions(),
127  * if you use command line options before start() is called.
128  *
129  * @param flags Optional flags which control how a new instance
130  * of the application is started.
131  * @return true if registration is successful.
132  * false if another process was already running.
133  */
134  static bool start(StartFlags flags);
135  // BIC: merge with start(StartFlags flags = StartFlags())
136  static bool start();
137 
138  /**
139  * Destructor
140  */
141  ~KUniqueApplication() override;
142 
143  /**
144  * Creates a new "instance" of the application.
145  *
146  * Usually this will involve making some calls into the GUI portion of your
147  * application asking for a new window to be created, possibly with
148  * some data already loaded based on the arguments received.
149  *
150  * Command line arguments have been passed to KCmdLineArgs before this
151  * function is called and can be checked in the usual way.
152  *
153  * The default implementation ensures the mainwindow of the already
154  * running instance is shown and activated if necessary. If your
155  * application has only one mainwindow, you should call this default
156  * implementation and only add your special handling if needed.
157  *
158  * Note that newInstance() is called also in the first started
159  * application process.
160  *
161  * For applications that share one process for several mainwindows,
162  * the reimplementation could be:
163  * \code
164  int MyApp::newInstance()
165  {
166  KCmdLineArgs::setCwd(QDir::currentPath().toUtf8());
167  KCmdLineArgs* args = KCmdLineArgs::parsedArgs();
168  static bool first = true;
169  if (args->count() > 0) {
170  for (int i = 0; i < args->count(); ++i) {
171  openWindow(args->url(i));
172  }
173  } else if( !first || !isSessionRestored()) {
174  openWindow(KUrl()); // create a new window
175  }
176  first = false;
177  args->clear();
178  return 0;
179  }
180  * \endcode
181  *
182  * @return An exit value. The calling process will exit with this value.
183  */
184  virtual int newInstance();
185 
186  /**
187  * Returns whether newInstance() is being called while session
188  * restoration is in progress.
189  */
190  bool restoringSession();
191 
192  /**
193  * @internal
194  */
195 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED
196  KDELIBS4SUPPORT_DEPRECATED static void setHandleAutoStarted();
197 #endif
198 
199 private:
200  friend class KUniqueApplicationAdaptor;
201  class Private;
202  Private *const d;
203 
204  Q_PRIVATE_SLOT(d, void _k_newInstanceNoFork())
205 };
206 Q_DECLARE_OPERATORS_FOR_FLAGS(KUniqueApplication::StartFlags)
207 
208 #endif
Controls and provides information to all KDE applications.
Definition: kapplication.h:76
StartFlag
These flags can be used to specify how new instances of unique applications are created.
KUniqueApplication is a KApplication which only uses a single process.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Jul 29 2021 22:58:57 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.