kdecore/kernel/kautostart.h

   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 = 0,
  83             /**
  84              * an executable that is checked for existence by name
  85              */
  86             CheckCommand = 1
  87         };
  88         Q_DECLARE_FLAGS(Conditions, Condition)
  89
  90         /**
  91          * Enumerates the various autostart phases that occur during start-up.
  92          */
  93         enum StartPhase
  94         {
  95             /**
  96              * the essential desktop services such as panels and window managers
  97              */
  98             BaseDesktop = 0,
  99             /**
 100              * services that should be available before most interactive
 101              * applications start but that aren't part of the base desktop.
 102              * This would include things such as clipboard managers and
 103              * mouse gesture tools.
 104              */
 105             DesktopServices = 1,
 106             /**
 107              * everything else that doesn't belong in the above two categories,
 108              * including most system tray applications, system monitors and
 109              * interactive applications
 110              */
 111             Applications = 2
 112         };
 113
 114         /**
 115          * Sets the given exec to start automatically at login
 116          * @param autostart will register with the autostart facility when true
 117          *        and deregister when false
 118          * @see autostarts()
 119          */
 120         void setAutostarts(bool autostart);
 121
 122         /**
 123          * Returns whether or not the service represented by entryName in the
 124          * autostart system is set to autostart at login or not
 125          * @param environment if provided the check will be performed as if
 126          *        being loaded in that environment
 127          * @param check autostart conditions to check for (see commandToCheck())
 128          * @see setAutostarts()
 129          */
 130         bool autostarts(const QString& environment = QString(),
 131                         Conditions check = NoConditions) const;
 132
 133         /**
 134          * Returns the associated command for this autostart service
 135          * @see setCommand()
 136          */
 137         QString command() const;
 138         /**
 139          * Set the associated command for this autostart service
 140          * @see command()
 141          */
 142         void setCommand(const QString& command);
 143
 144         /**
 145          * Returns the user-visible name this autostart service is registered as
 146          * @see setVisibleName(), setEntryName()
 147          */
 148         QString visibleName() const;
 149         /**
 150          * Sets the user-visible name for this autostart service.
 151          * @see visibleName()
 152          */
 153         void setVisibleName(const QString& entryName);
 154
 155         /**
 156          * Checks whether or not a service by the given name @p entryName is registered
 157          * with the autostart system. Does not check whether or not it is
 158          * set to actually autostart or not.
 159          * @param entryName the name of the service to check for
 160          */
 161         static bool isServiceRegistered(const QString& entryName);
 162
 163         /**
 164          * Returns the executable to check for when attempting to autostart
 165          * this service. If the executable is not found in the user's
 166          * environment, it will not autostart.
 167          * @see setCommandToCheck()
 168          */
 169         QString commandToCheck() const;
 170         /**
 171          * Sets the executable to check for the existence of when
 172          * autostarting this service
 173          * @see commandToCheck()
 174          */
 175         void setCommandToCheck(const QString& exec);
 176
 177         /**
 178          * Returns the autostart phase this service is started in.
 179          *
 180          * Note that this is KDE specific and may not work in other
 181          * environments.
 182          *
 183          * @see StartPhase, setStartPhase()
 184          */
 185         StartPhase startPhase() const;
 186         /**
 187          * Sets the service (by name) this service should be started after.
 188          *
 189          * Note that this is KDE specific and may not work in other
 190          * environments.
 191          *
 192          * @see StartPhase, startPhase()
 193          */
 194         void setStartPhase(StartPhase phase);
 195
 196         /**
 197          * Returns the list of environments (e.g. "KDE") this service is allowed
 198          * to start in.
 199          *
 200          * This does not take other autostart conditions
 201          * into account. If any environment is added to the allowed environments
 202          * list, then only those environments will be allowed to
 203          * autoload the service. If an environment is marked as both allowed
 204          * and excluded, it will be excluded.
 205          * @see setAllowedEnvironments()
 206          */
 207         QStringList allowedEnvironments() const;
 208         /**
 209          * Sets the environments this service is allowed to start in
 210          * @see allowedEnvironments(), addToAllowedEnvironments()
 211          */
 212         void setAllowedEnvironments(const QStringList& environments);
 213         /**
 214          * Adds an environment to the list of environments this service may
 215          * start in.
 216          * @see setAllowedEnvironments(), removeFromAllowedEnvironments()
 217          */
 218         void addToAllowedEnvironments(const QString& environment);
 219         /**
 220          * Removes an environment to the list of environments this service may
 221          * start in.
 222          * @see addToAllowedEnvironments()
 223          */
 224         void removeFromAllowedEnvironments(const QString& environment);
 225
 226         /**
 227          * Returns the list of environments this service is explicitly not
 228          * allowed to start in.
 229          *
 230          * This does not take other autostart conditions
 231          * such as into account. If the same environment is also marked as
 232          * allowed, it will still be excluded.
 233          * @see setExcludedEnvironments()
 234          */
 235         QStringList excludedEnvironments() const;
 236         /**
 237          * Sets the environments this service is not allowed to start in
 238          * @see excludedEnvironments(), addToExcludedEnvironments()
 239          */
 240         void setExcludedEnvironments(const QStringList& environments);
 241         /**
 242          * Adds an environment to the list of environments this service may
 243          * not be autostarted in
 244          * @see removeFromExcludedEnvironments()
 245          */
 246         void addToExcludedEnvironments(const QString& environment);
 247         /**
 248          * Removes an environment to the list of environments this service may
 249          * not be autostarted in
 250          * @see addToExcludedEnvironments()
 251          */
 252         void removeFromExcludedEnvironments(const QString& environment);
 253
 254     private:
 255         class Private;
 256         Private* const d;
 257 };
 258
 259 Q_DECLARE_OPERATORS_FOR_FLAGS(KAutostart::Conditions)
 260 #endif