1/* This file is part of the KDE libraries
2 Copyright (C) 2006 Aaron Seigo <aseigo@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KDELIBS_KAUTOSTART_H
21#define KDELIBS_KAUTOSTART_H
22
23#include <kdecore_export.h>
24
25#include <QtCore/QObject>
26
27class QStringList;
28
29/**
30 * KAutostart provides a programmatic means to control the state of
31 * autostart services on a per-user basis. This is useful for applications
32 * that wish to offer a configurable means to allow the application to be
33 * autostarted.
34 *
35 * By using this class you future-proof your applications against potential
36 * future or platform-specific changes to the autostart mechanism(s).
37 *
38 * Typical usage might look like:
39 *
40 * @code
41 * KAutostart autostart; // without an entryName arg, gets name from KAboutData
42 * autostart.setAutostarts(true); // will now start up when the user logs in
43 *
44 * // set the value in our configuration settings to reflect whether or not
45 * // we will actually start up on log in
46 * config.setAutoStart(autostart.autoStarts());
47 * @endcode
48 */
49class KDECORE_EXPORT KAutostart : public QObject
50{
51 Q_OBJECT
52
53 public:
54 /**
55 * Creates a new KAutostart object that represents the autostart
56 * service "entryName". If the service already exists in the system
57 * then the values associated with that service, such as the executable
58 * command, will be loaded as well.
59 *
60 * Note that unless this service is explicitly set to autostart,
61 * simply creating a KAutostart object will not result in the
62 * service being autostarted on next log in.
63 *
64 * If no such service is already registered and the command to be
65 * executed on startup is not the same as entryName, then you will want
66 * to set the associated command with setExec(const QString&)
67 * @see setExec
68 * @param entryName the name used to identify the service. If none is
69 * provided then it uses the name registered with KAboutData.
70 * @param parent QObject
71 */
72 explicit KAutostart(const QString& entryName = QString(),
73 QObject* parent = 0);
74 ~KAutostart();
75
76 /**
77 * Flags for each of the conditions that may affect whether or not
78 * a service actually autostarted on login
79 */
80 enum Condition
81 {
82 NoConditions = 0x0,
83 /**
84 * an executable that is checked for existence by name
85 */
86 CheckCommand = 0x1,
87 /**
88 * autostart condition will be checked too (KDE-specific)
89 * @since 4.3
90 */
91 CheckCondition = 0x2,
92 /**
93 * all necessary conditions will be checked
94 * @since 4.3
95 */
96 CheckAll = 0xff
97 };
98 Q_DECLARE_FLAGS(Conditions, Condition)
99
100 /**
101 * Enumerates the various autostart phases that occur during start-up.
102 */
103 enum StartPhase
104 {
105 /**
106 * the essential desktop services such as panels and window managers
107 */
108 BaseDesktop = 0,
109 /**
110 * services that should be available before most interactive
111 * applications start but that aren't part of the base desktop.
112 * This would include things such as clipboard managers and
113 * mouse gesture tools.
114 */
115 DesktopServices = 1,
116 /**
117 * everything else that doesn't belong in the above two categories,
118 * including most system tray applications, system monitors and
119 * interactive applications
120 */
121 Applications = 2
122 };
123
124 /**
125 * Sets the given exec to start automatically at login
126 * @param autostart will register with the autostart facility when true
127 * and deregister when false
128 * @see autostarts()
129 */
130 void setAutostarts(bool autostart);
131
132 /**
133 * Returns whether or not the service represented by entryName in the
134 * autostart system is set to autostart at login or not
135 * @param environment if provided the check will be performed as if
136 * being loaded in that environment
137 * @param check autostart conditions to check for (see commandToCheck())
138 * @see setAutostarts()
139 */
140 bool autostarts(const QString& environment = QString(),
141 Conditions check = NoConditions) const;
142
143 /**
144 * Returns the associated command for this autostart service
145 * @see setCommand()
146 */
147 QString command() const;
148 /**
149 * Set the associated command for this autostart service
150 * @see command()
151 */
152 void setCommand(const QString& command);
153
154 /**
155 * Returns the user-visible name this autostart service is registered as
156 * @see setVisibleName(), setEntryName()
157 */
158 QString visibleName() const;
159 /**
160 * Sets the user-visible name for this autostart service.
161 * @see visibleName()
162 */
163 void setVisibleName(const QString& entryName);
164
165 /**
166 * Checks whether or not a service by the given name @p entryName is registered
167 * with the autostart system. Does not check whether or not it is
168 * set to actually autostart or not.
169 * @param entryName the name of the service to check for
170 */
171 static bool isServiceRegistered(const QString& entryName);
172
173 /**
174 * Returns the executable to check for when attempting to autostart
175 * this service. If the executable is not found in the user's
176 * environment, it will not autostart.
177 * @see setCommandToCheck()
178 */
179 QString commandToCheck() const;
180 /**
181 * Sets the executable to check for the existence of when
182 * autostarting this service
183 * @see commandToCheck()
184 */
185 void setCommandToCheck(const QString& exec);
186
187 /**
188 * Returns the autostart phase this service is started in.
189 *
190 * Note that this is KDE specific and may not work in other
191 * environments.
192 *
193 * @see StartPhase, setStartPhase()
194 */
195 StartPhase startPhase() const;
196 /**
197 * Sets the service (by name) this service should be started after.
198 *
199 * Note that this is KDE specific and may not work in other
200 * environments.
201 *
202 * @see StartPhase, startPhase()
203 */
204 void setStartPhase(StartPhase phase);
205
206 /**
207 * Returns the list of environments (e.g. "KDE") this service is allowed
208 * to start in. Use checkAllowedEnvironment() or autostarts() for actual
209 * checks.
210 *
211 * This does not take other autostart conditions
212 * into account. If any environment is added to the allowed environments
213 * list, then only those environments will be allowed to
214 * autoload the service. It is not allowed to specify both allowed and excluded
215 * environments at the same time.
216 * @see setAllowedEnvironments()
217 */
218 QStringList allowedEnvironments() const;
219 /**
220 * Sets the environments this service is allowed to start in
221 * @see allowedEnvironments(), addToAllowedEnvironments()
222 */
223 void setAllowedEnvironments(const QStringList& environments);
224 /**
225 * Adds an environment to the list of environments this service may
226 * start in.
227 * @see setAllowedEnvironments(), removeFromAllowedEnvironments()
228 */
229 void addToAllowedEnvironments(const QString& environment);
230 /**
231 * Removes an environment to the list of environments this service may
232 * start in.
233 * @see addToAllowedEnvironments()
234 */
235 void removeFromAllowedEnvironments(const QString& environment);
236
237 /**
238 * Returns the list of environments this service is explicitly not
239 * allowed to start in. Use checkAllowedEnvironment() or autostarts() for actual
240 * checks.
241 *
242 * This does not take other autostart conditions
243 * such as into account. It is not allowed to specify both allowed and excluded
244 * environments at the same time.
245 * @see setExcludedEnvironments()
246 */
247 QStringList excludedEnvironments() const;
248 /**
249 * Sets the environments this service is not allowed to start in
250 * @see excludedEnvironments(), addToExcludedEnvironments()
251 */
252 void setExcludedEnvironments(const QStringList& environments);
253 /**
254 * Adds an environment to the list of environments this service may
255 * not be autostarted in
256 * @see removeFromExcludedEnvironments()
257 */
258 void addToExcludedEnvironments(const QString& environment);
259 /**
260 * Removes an environment to the list of environments this service may
261 * not be autostarted in
262 * @see addToExcludedEnvironments()
263 */
264 void removeFromExcludedEnvironments(const QString& environment);
265
266 /**
267 * Returns the name of another service that should be autostarted
268 * before this one (if that service would be autostarted).
269 * @internal
270 * @since 4.3
271 */
272 QString startAfter() const;
273
274 /**
275 * Checks whether autostart is allowed in the given environment,
276 * depending on allowedEnvironments() and excludedEnvironments().
277 * @since 4.3
278 */
279 bool checkAllowedEnvironment( const QString& environment ) const;
280
281 private:
282 bool checkStartCondition() const;
283 class Private;
284 Private* const d;
285};
286
287Q_DECLARE_OPERATORS_FOR_FLAGS(KAutostart::Conditions)
288#endif
289