workspace/libs/plasma/packagestructure.h

   1 /******************************************************************************
   2 *   Copyright 2007 by 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 PACKAGESTRUCTURE_H
  21 #define PACKAGESTRUCTURE_H
  22
  23 #include <QtCore/QStringList>
  24 #include <QtCore/QSharedData>
  25
  26 #include <KGenericFactory>
  27 #include <KLocale>
  28 #include <KSharedPtr>
  29
  30 #include <plasma/plasma_export.h>
  31
  32 class KConfigBase;
  33
  34 namespace Plasma
  35 {
  36
  37 /**
  38  * @brief A description of the expected file structure of a given package type
  39  *
  40  * PackageStructure defines what is in a package. This information is used
  41  * to create packages and provides a way to programatically refer to contents.
  42  *
  43  * An example usage of this class might be:
  44  *
  45  @code
  46     PackageStructure structure;
  47
  48     structure.addDirectoryDefinition("images", "pics/", i18n("Images"));
  49     QStringList mimetypes;
  50     mimetypes << "image/svg" << "image/png" << "image/jpeg";
  51     structure.setMimetypes("images", mimetypes);
  52
  53     structure.addDirectoryDefinition("scripts", "code/", i18n("Executable Scripts"));
  54     mimetypes.clear();
  55     mimetypes << "text/\*";
  56     structure.setMimetypes("scripts", mimetypes);
  57
  58     structure.addFileDefinition("mainscript", "code/main.js", i18n("Main Script File"));
  59     structure.setRequired("mainscript", true);
  60  @endcode
  61  * One may also choose to create a subclass of PackageStructure and include the setup
  62  * in the constructor.
  63  *
  64  * Either way, PackageStructure creates a sort of "contract" between the packager and
  65  * the application which is also self-documenting.
  66  **/
  67 class PLASMA_EXPORT PackageStructure : public QObject, public QSharedData
  68 {
  69     Q_OBJECT
  70
  71 public:
  72     typedef KSharedPtr<PackageStructure> Ptr;
  73
  74     /**
  75      * Default constructor for a package structure definition
  76      *
  77      * @arg type the type of package. This is often application specific.
  78      **/
  79     explicit PackageStructure(QObject *parent = 0, const QString &type = i18n("Invalid"));
  80
  81     /**
  82      * Destructor
  83      **/
  84     virtual ~PackageStructure();
  85
  86     /**
  87      * Assignment operator
  88      **/
  89     PackageStructure& operator=(const PackageStructure& rhs);
  90
  91     /**
  92      * Loads a package format by name.
  93      *
  94      * @arg format If not empty, attempts to locate the given format, either
  95      *             from built-ins or via plugins.
  96      * @return a package that matches the format, if available. The caller
  97      *         is responsible for deleting the object.
  98      */
  99     static PackageStructure::Ptr load(const QString &packageFormat);
 100
 101     /**
 102      * Type of package this structure describes
 103      **/
 104     QString type() const;
 105
 106     /**
 107      * The directories defined for this package
 108      **/
 109     QList<const char*> directories() const;
 110
 111     /**
 112      * The required directories defined for this package
 113      **/
 114     QList<const char*> requiredDirectories() const;
 115
 116     /**
 117      * The individual files, by key, that are defined for this package
 118      **/
 119     QList<const char*> files() const;
 120
 121     /**
 122      * The individual required files, by key, that are defined for this package
 123      **/
 124     QList<const char*> requiredFiles() const;
 125
 126     /**
 127      * Adds a directory to the structure of the package. It is added as
 128      * a not-required element with no associated mimetypes.
 129      *
 130      * @param key  used as an internal label for this directory
 131      * @param path the path within the the package for this directory
 132      * @param name the user visible (translated) name for the directory
 133      **/
 134     void addDirectoryDefinition(const char* key, const QString& path, const QString& name);
 135
 136     /**
 137      * Adds a file to the structure of the package. It is added as
 138      * a not-required element with no associated mimetypes.
 139      *
 140      * @param key  used as an internal label for this file
 141      * @param path the path within the the package for this file
 142      * @param name the user visible (translated) name for the file
 143      **/
 144     void addFileDefinition(const char* key, const QString& path, const QString& name);
 145
 146     /**
 147      * @return path relative to the package root for the given entry
 148      **/
 149     QString path(const char* key) const;
 150
 151     /**
 152      * @return user visible name for the given entry
 153      **/
 154     QString name(const char* key) const;
 155
 156     /**
 157      * Sets whether or not a given part of the structure is required or not.
 158      * The path must already have been added using addDirectoryDefinition
 159      * or addFileDefinition.
 160      *
 161      * @param path the path of the entry within the package
 162      * @param required true if this entry is required, false if not
 163      */
 164     void setRequired(const char* key, bool required);
 165
 166     /**
 167      * @return true if the item at path exists and is required
 168      **/
 169     bool required(const char* key) const;
 170
 171     /**
 172      * Defines the default mimetypes for any definitions that do not have
 173      * associated mimetypes. Handy for packages with only one or predominantly
 174      * one file type.
 175      *
 176      * @param mimetypes a list of mimetypes
 177      **/
 178     void setDefaultMimetypes(QStringList mimetypes);
 179
 180     /**
 181      * Define mimetypes for a given part of the structure
 182      * The path must already have been added using addDirectoryDefinition
 183      * or addFileDefinition.
 184      *
 185      * @param path the path of the entry within the package
 186      * @param mimetypes a list of mimetypes
 187      **/
 188     void setMimetypes(const char* key, QStringList mimetypes);
 189
 190     /**
 191      * @return the mimetypes associated with the path, if any
 192      **/
 193     QStringList mimetypes(const char* key) const;
 194
 195     /**
 196      * Sets the path to the package. Useful for package formats
 197      * which do not have well defined contents prior to installation.
 198      */
 199     void setPath(const QString &path);
 200
 201     /**
 202      * @return the path to the package, or QString() if none
 203      */
 204     QString path() const;
 205
 206     /**
 207       * Read a package structure from a config file.
 208       */
 209     void read(const KConfigBase *config);
 210
 211     /**
 212       * Write this package structure to a config file.
 213       */
 214     void write(KConfigBase *config) const;
 215
 216     /**
 217      * Installs a package matching this package structure. By default simply calls
 218      * Plasma::Package::install.
 219      *
 220      * @param archivePath path to the package archive file
 221      * @param packageRoot path to the directory where the package should be
 222      *                    installed to
 223      * @return true on successful installation, false otherwise
 224      **/
 225     virtual bool installPackage(const QString &archivePath, const QString &packageRoot);
 226
 227     /**
 228      * @return the prefix inserted between the base path and content entries
 229      */
 230     QString contentsPrefix() const;
 231
 232 protected:
 233     /**
 234      * Sets the prefix that all the contents in this package should
 235      * appear under. This defaults to "contents/" and is added automatically
 236      * between the base path and the entries as defined by the package
 237      * structure
 238      *
 239      * @arg prefix the directory prefix to use
 240      */
 241     void setContentsPrefix(const QString &prefix);
 242
 243     virtual void pathChanged();
 244
 245 private:
 246     class Private;
 247      Private * const d;
 248 };
 249
 250 /**
 251  * Register an applet when it is contained in a loadable module
 252  */
 253 #define K_EXPORT_PLASMA_PACKAGESTRUCTURE(libname, classname) \
 254 K_PLUGIN_FACTORY(factory, registerPlugin<classname>();) \
 255 K_EXPORT_PLUGIN(factory("plasma_packagestructure_" #libname))
 256
 257 } // Plasma namespace
 258 #endif