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 | |
27 | class 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 | */ |
49 | class 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 | |
287 | Q_DECLARE_OPERATORS_FOR_FLAGS(KAutostart::Conditions) |
288 | #endif |
289 | |