shell/profileengine.h

   1 /***************************************************************************
   2  *   Copyright 2004 Alexander Dymo <adymo@kdevelop.org>             *
   3  *                                                                         *
   4  *   This program is free software; you can redistribute it and/or modify  *
   5  *   it under the terms of the GNU Library General Public License as       *
   6  *   published by the Free Software Foundation; either version 2 of the    *
   7  *   License, or (at your option) any later version.                       *
   8  *                                                                         *
   9  *   This program 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         *
  12  *   GNU General Public License for more details.                          *
  13  *                                                                         *
  14  *   You should have received a copy of the GNU Library General Public     *
  15  *   License along with this program; if not, write to the                 *
  16  *   Free Software Foundation, Inc.,                                       *
  17  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.         *
  18  ***************************************************************************/
  19 #ifndef KDEVPROFILEENGINE_H
  20 #define KDEVPROFILEENGINE_H
  21
  22 #include <QtCore/QMap>
  23 #include <QtCore/QList>
  24 #include <kservicetypetrader.h>
  25 #include "profile.h"
  26 #include "plugincontroller.h"
  27
  28 namespace KDevelop
  29 {
  30
  31 /**
  32 Profile listing operation.
  33 Used to get a plain list of profiles
  34 and store it in the QMap<QString, Profile*>.
  35 */
  36 class KDEVPLATFORMSHELL_EXPORT ProfileListing{ //krazy:exclude=dpointer,inline
  37 public:
  38     void operator() (Profile *profile)
  39     {
  40         profiles[profile->name()] = profile;
  41     }
  42
  43     QMap<QString, Profile*> profiles;
  44 };
  45
  46 /**Profile resource listing operation.
  47 Used to get a list of urls to the profile resources.
  48
  49 Resource urls can be filtered by an @p filter parameter
  50 passed to the constructor. Filter can have values
  51 as described in @ref QDir::setNameFilter function documentation.*/
  52 class KDEVPLATFORMSHELL_EXPORT ProfileListingEx { //krazy:exclude=dpointer,inline
  53 public:
  54     ProfileListingEx(const QString &filter): m_filter(filter) {}
  55     void operator() (Profile *profile)
  56     {
  57         resourceList += profile->resources(m_filter);
  58     }
  59
  60     KUrl::List resourceList;
  61     QString m_filter;
  62 };
  63
  64 /**
  65 Profile engine.
  66
  67 - Uses KDevelop profiles to form lists of plugin offers;
  68 - Provides means of managing profiles;
  69 - Provides means to access the resources provided by a profile.
  70
  71 KDevelop profiles form a tree with a root profile named "KDevelop".
  72 For example, such profiles tree can look as:
  73 @code
  74 KDevelop
  75 - IDE
  76   - CompiledLanguageIDE
  77     - AdaIDE
  78     - CandCppIDE
  79       - CIDE
  80       - CppIDE
  81         - KDECppIDE
  82     - FortranIDE
  83     ...
  84   - DatabaseIDE
  85   - ScriptingLanguageIDE
  86   ..
  87 - KDevAssistant
  88 @endcode
  89 To manage a tree of profiles, use @ref ProfileEngine::walkProfiles methods.
  90 */
  91 class KDEVPLATFORMSHELL_EXPORT ProfileEngine {
  92 public:
  93     ProfileEngine();
  94     ~ProfileEngine();
  95
  96     /** @return The list of plugin offers for given profile and type.*/
  97     KPluginInfo::List offers(const QString &profileName, PluginController::PluginType offerType);
  98
  99     /** @return The list of all plugin offers for given type.*/
 100     KPluginInfo::List allOffers(PluginController::PluginType offerType);
 101
 102     /**@return The list of URLs to the resources (files) with given @p extension.
 103     @param profileName A name of a profile to find resources in.
 104     @param nameFilter Name filter for files. @see QDir::setNameFilter documentation
 105     for name filters syntax.*/
 106     KUrl::List resources(const QString &profileName, const QString &nameFilter);
 107
 108     /**@return The list of URLs to the resources (files) with given @p extension.
 109     This list is obtained by a recursive search that process given profile
 110     and all it's subprofiles.
 111     @param profileName A name of a profile to find resources in.
 112     @param nameFilter Name filter for files. @see QDir::setNameFilter documentation
 113     for name filters syntax.*/
 114     KUrl::List resourcesRecursive(const QString &profileName, const QString &nameFilter);
 115
 116     /**Adds a resource for the profile. Resource will be copied to the user profile directory
 117     (like $HOME/.kde/share/apps/kdevelop/profiles/...).
 118     @param profileName A name of the profile.
 119     @param url The url to a file to copy as a profile resource.*/
 120     void addResource(const QString &profileName, const KUrl &url);
 121
 122     /**Gets the difference between @p profile1 and @p profile2.
 123     Difference is calculated as two lists of plugins to be unloaded and loaded
 124     in order to switch from @p profile1 to @p profile2.
 125     @param offerType A type of plugin offers to list.
 126     @param profile1 A name of the first profile.
 127     @param profile2 A name of the second profile.
 128     @param unload Will be filled with a list of plugins to unload.
 129     @param load Will be filled with a list of plugins to load.
 130     @note Resulting lists are not cleared. Pass only clean lists in the
 131     common case.*/
 132     void diffProfiles(PluginController::PluginType offerType, const QString &profile1, const QString &profile2,
 133         QStringList &unload, KPluginInfo::List &load);
 134
 135     /**@return The root profile. Root profile is always named "KDevelop" and it
 136     defines an empty list of plugins. Applications built on KDevelop platform
 137     will define nested profiles.*/
 138     Profile *rootProfile() const;
 139     /**Finds a profile with given name.
 140     @return The profile found or 0 if it does not exist.*/
 141     Profile *findProfile(const QString &profileName);
 142
 143     /**Walks profiles tree and applies operation @p op to each profile found
 144     in the tree below @p root (@p root profile itself is not processed).
 145
 146     Operation is a class that have operator(Profile *).
 147     Example of operation class which is used to build a plain list of profiles:
 148     @code
 149     class ProfileListing{ //krazy:exclude-dpointer
 150     public:
 151         void operator() (Profile *profile)
 152         {
 153             profiles[profile->name()] = profile;
 154         }
 155
 156         QMap<QString, Profile*> profiles;
 157     };
 158     @endcode
 159     Use case for such operation - building a list of all profiles:
 160     @code
 161     ProfileEngine engine;
 162     ProfileListing listing;
 163     engine.walkProfiles<ProfileListing>(listing, engine.rootProfile());
 164     @endcode
 165
 166     @note @ref ProfileListing and @ref ProfileListingEx operations are already defined in
 167     profileengine.h header file.
 168
 169     @param op An operation to apply.
 170     @param root A profile to start walking from. Complete subtree of the @p root is traversed.
 171     */
 172     template<class Operation>
 173     void walkProfiles(Operation &op, Profile *root)
 174     {
 175         QList<Profile*> children = root->children();
 176         for (QList<Profile*>::iterator it = children.begin(); it != children.end(); ++it)
 177         {
 178             op(*it);
 179             walkProfiles<Operation>(op, *it);
 180         }
 181     }
 182     /**Walks profiles tree and applies operation @p op to each profile
 183     found in the tree below @p root (@p root profile itself is not processed)
 184     but the operation in this case returns a result of type defined by
 185     "Result" template parameter.
 186
 187     When iterating the tree, the result of operation applied to the parent profile
 188     is passed as @p result parameter to the recursive call for child profiles.
 189
 190     For example, this function can be used to build another hierarcy of profiles
 191     or other objects connected to profiles.
 192     Example of operation class which is used to build a listview with items
 193     where each item represents a profile:
 194     @code
 195     class ProfileListBuilding { //krazy:exclude-dpointer
 196     public:
 197         ProfileItem * operator() (ProfileItem *parent, Profile *profile)
 198         {
 199             parent->setOpen(true);
 200             return new ProfileItem(parent, profile);
 201         }
 202     };
 203
 204     class ProfileItem: public K3ListViewItem { //krazy:exclude-dpointer
 205     public:
 206         ProfileItem(K3ListView *parent, Profile *profile)
 207             :K3ListViewItem(parent), m_profile(profile)
 208         {
 209             setText(0, profile->genericName());
 210             setText(1, profile->description());
 211         }
 212
 213         ProfileItem(K3ListViewItem *parent, Profile *profile)
 214             : K3ListViewItem(parent), m_profile(profile)
 215         {
 216             setText(0, profile->genericName());
 217             setText(1, profile->description());
 218         }
 219
 220         Profile *profile() const { return m_profile; }
 221
 222     private:
 223         Profile *m_profile;
 224     };
 225
 226     @endcode
 227     Use case for such operation - building a listview:
 228     @code
 229     ProfileEngine engine;
 230     ProfileItem *item = new ProfileItem(profilesList, engine.rootProfile());
 231     ProfileListBuilding op;
 232     engine.walkProfiles<ProfileListBuilding, ProfileItem>(op, item, engine.rootProfile());
 233     @endcode
 234
 235     @param op An operation to apply.
 236     @param result A result of the operation as it would have been applied to the @p root.
 237     @param root A profile to start walking from. Complete subtree of the @p root is traversed.
 238     */
 239     template<class Operation, class Result>
 240     void walkProfiles(Operation &op, Result *result, Profile *root)
 241     {
 242         QList<Profile*> children = root->children();
 243         for (QList<Profile*>::iterator it = children.begin(); it != children.end(); ++it)
 244         {
 245             Result *newResult = op(result, *it);
 246             walkProfiles<Operation>(op, newResult, *it);
 247         }
 248     }
 249
 250 protected:
 251     void processDir(const QString &dir, const QString &currPath, QMap<QString, Profile*> &passedPaths, Profile *root);
 252
 253     KUrl::List resources(Profile *profile, const QString &nameFilter);
 254
 255     /**Gets a complete listing of available profiles and looks for a profile.
 256     @param listing Profiles listing will be saved here.
 257     @param profile Will be a pointer to a profile with the name @p profileName or 0
 258     if no profile with that name is found.
 259     @param profileName The name of a profile to find.*/
 260     void getProfileWithListing(ProfileListing &listing, Profile **profile,
 261         const QString &profileName);
 262
 263 private:
 264     class ProfileEnginePrivate* const d;
 265 };
 266
 267 }
 268 #endif