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 PLASMA_PACKAGESTRUCTURE_H
  21 #define PLASMA_PACKAGESTRUCTURE_H
  22
  23 #include <QtCore/QStringList>
  24 #include <QtCore/QSharedData>
  25
  26 #include <kgenericfactory.h>
  27 #include <klocale.h>
  28 #include <ksharedptr.h>
  29
  30 #include <plasma/version.h>
  31 #include "packagemetadata.h"
  32
  33 class KConfigBase;
  34
  35 namespace Plasma
  36 {
  37
  38 class PackageStructurePrivate;
  39
  40 /**
  41  * @class PackageStructure plasma/packagestructure.h <Plasma/PackageStructure>
  42  *
  43  * @short A description of the expected file structure of a given package type
  44  *
  45  * PackageStructure defines what is in a package. This information is used
  46  * to create packages and provides a way to programatically refer to contents.
  47  *
  48  * An example usage of this class might be:
  49  *
  50  @code
  51     PackageStructure structure;
  52
  53     structure.addDirectoryDefinition("images", "pics/", i18n("Images"));
  54     QStringList mimetypes;
  55     mimetypes << "image/svg" << "image/png" << "image/jpeg";
  56     structure.setMimetypes("images", mimetypes);
  57
  58     structure.addDirectoryDefinition("scripts", "code/", i18n("Executable Scripts"));
  59     mimetypes.clear();
  60     mimetypes << "text/\*";
  61     structure.setMimetypes("scripts", mimetypes);
  62
  63     structure.addFileDefinition("mainscript", "code/main.js", i18n("Main Script File"));
  64     structure.setRequired("mainscript", true);
  65  @endcode
  66  * One may also choose to create a subclass of PackageStructure and include the setup
  67  * in the constructor.
  68  *
  69  * Either way, PackageStructure creates a sort of "contract" between the packager and
  70  * the application which is also self-documenting.
  71  **/
  72 class PLASMA_EXPORT PackageStructure : public QObject, public QSharedData
  73 {
  74     Q_OBJECT
  75
  76 public:
  77     typedef KSharedPtr<PackageStructure> Ptr;
  78
  79     /**
  80      * Default constructor for a package structure definition
  81      *
  82      * @arg type the type of package. This is often application specific.
  83      **/
  84     explicit PackageStructure(QObject *parent = 0,
  85                               const QString &type = i18nc("A non-functional package", "Invalid"));
  86
  87     /**
  88      * Destructor
  89      **/
  90     virtual ~PackageStructure();
  91
  92     /**
  93      * Assignment operator
  94      **/
  95     PackageStructure &operator=(const PackageStructure &rhs);
  96
  97     /**
  98      * Loads a package format by name.
  99      *
 100      * @arg format If not empty, attempts to locate the given format, either
 101      *             from built-ins or via plugins.
 102      * @return a package that matches the format, if available. The caller
 103      *         is responsible for deleting the object.
 104      */
 105     static PackageStructure::Ptr load(const QString &packageFormat);
 106
 107     /**
 108      * Type of package this structure describes
 109      **/
 110     QString type() const;
 111
 112     /**
 113      * The directories defined for this package
 114      **/
 115     QList<const char*> directories() const;
 116
 117     /**
 118      * The required directories defined for this package
 119      **/
 120     QList<const char*> requiredDirectories() const;
 121
 122     /**
 123      * The individual files, by key, that are defined for this package
 124      **/
 125     QList<const char*> files() const;
 126
 127     /**
 128      * The individual required files, by key, that are defined for this package
 129      **/
 130     QList<const char*> requiredFiles() const;
 131
 132     /**
 133      * Adds a directory to the structure of the package. It is added as
 134      * a not-required element with no associated mimetypes.
 135      *
 136      * @param key  used as an internal label for this directory
 137      * @param path the path within the package for this directory
 138      * @param name the user visible (translated) name for the directory
 139      **/
 140     void addDirectoryDefinition(const char *key, const QString &path, const QString &name);
 141
 142     /**
 143      * Adds a file to the structure of the package. It is added as
 144      * a not-required element with no associated mimetypes.
 145      *
 146      * @param key  used as an internal label for this file
 147      * @param path the path within the package for this file
 148      * @param name the user visible (translated) name for the file
 149      **/
 150     void addFileDefinition(const char *key, const QString &path, const QString &name);
 151
 152     /**
 153      * @return path relative to the package root for the given entry
 154      **/
 155     QString path(const char *key) const;
 156
 157     /**
 158      * @return user visible name for the given entry
 159      **/
 160     QString name(const char *key) const;
 161
 162     /**
 163      * Sets whether or not a given part of the structure is required or not.
 164      * The path must already have been added using addDirectoryDefinition
 165      * or addFileDefinition.
 166      *
 167      * @param key the entry within the package
 168      * @param required true if this entry is required, false if not
 169      */
 170     void setRequired(const char *key, bool required);
 171
 172     /**
 173      * @return true if the item at path exists and is required
 174      **/
 175     bool isRequired(const char *key) const;
 176
 177     /**
 178      * Defines the default mimetypes for any definitions that do not have
 179      * associated mimetypes. Handy for packages with only one or predominantly
 180      * one file type.
 181      *
 182      * @param mimetypes a list of mimetypes
 183      **/
 184     void setDefaultMimetypes(QStringList mimetypes);
 185
 186     /**
 187      * Define mimetypes for a given part of the structure
 188      * The path must already have been added using addDirectoryDefinition
 189      * or addFileDefinition.
 190      *
 191      * @param key the entry within the package
 192      * @param mimetypes a list of mimetypes
 193      **/
 194     void setMimetypes(const char *key, QStringList mimetypes);
 195
 196     /**
 197      * @return the mimetypes associated with the path, if any
 198      **/
 199     QStringList mimetypes(const char *key) const;
 200
 201     /**
 202      * Sets the path to the package. Useful for package formats
 203      * which do not have well defined contents prior to installation.
 204      */
 205     void setPath(const QString &path);
 206
 207     /**
 208      * @return the path to the package, or QString() if none
 209      */
 210     QString path() const;
 211
 212     /**
 213      * Read a package structure from a config file.
 214      */
 215     void read(const KConfigBase *config);
 216
 217     /**
 218      * Write this package structure to a config file.
 219      */
 220     void write(KConfigBase *config) const;
 221
 222     /**
 223      * Installs a package matching this package structure. By default installs a
 224      * native Plasma::Package.
 225      *
 226      * @param archivePath path to the package archive file
 227      * @param packageRoot path to the directory where the package should be
 228      *                    installed to
 229      * @return true on successful installation, false otherwise
 230      **/
 231     virtual bool installPackage(const QString &archivePath, const QString &packageRoot);
 232
 233     /**
 234      * Uninstalls a package matching this package structure.
 235      *
 236      * @arg packageName the name of the package to remove
 237      * @arg packageRoot path to the directory where the package should be installed to
 238      * @return true on successful removal of the package, false otherwise
 239      */
 240     virtual bool uninstallPackage(const QString &packageName, const QString &packageRoot);
 241
 242     /**
 243      * When called, the package plugin should display a window to the user
 244      * that they can use to browser, select and then install widgets supported by
 245      * this package plugin with.
 246      *
 247      * The user interface may be an in-process dialog or an out-of-process application.
 248      *
 249      * When the process is complete, the newWidgetBrowserFinished() signal must be
 250      * emitted.
 251      *
 252      * @param parent the parent widget to use for the widget
 253      */
 254     virtual void createNewWidgetBrowser(QWidget *parent = 0);
 255
 256     /**
 257      * @return the prefix inserted between the base path and content entries
 258      */
 259     QString contentsPrefix() const;
 260
 261     /**
 262      * @return preferred package root. This defaults to plasma/plasmoids/
 263      */
 264     QString defaultPackageRoot() const;
 265
 266     /**
 267      * @return service prefix used in desktop files. This defaults to plasma-applet-
 268      */
 269     QString servicePrefix() const;
 270
 271     /**
 272      * Sets service prefix.
 273      */
 274     void setServicePrefix(const QString &servicePrefix);
 275
 276     /**
 277       * @return the package metadata object.
 278       */
 279     virtual PackageMetadata metadata();
 280
 281     /**
 282      * @return true if paths/symlinks outside the package itself should be followed.
 283      * By default this is set to false for security reasons.
 284      */
 285     bool allowExternalPaths() const;
 286
 287 Q_SIGNALS:
 288     /**
 289      * Emitted when the new widget browser process completes.
 290      */
 291     void newWidgetBrowserFinished();
 292
 293 protected:
 294     /**
 295      * Sets whether or not external paths/symlinks can be followed by a package
 296      * @arg allow true if paths/symlinks outside of the package should be followed,
 297      *             false if they should be rejected.
 298      */
 299     void setAllowExternalPaths(bool allow);
 300
 301     /**
 302      * Sets the prefix that all the contents in this package should
 303      * appear under. This defaults to "contents/" and is added automatically
 304      * between the base path and the entries as defined by the package
 305      * structure
 306      *
 307      * @arg prefix the directory prefix to use
 308      */
 309     void setContentsPrefix(const QString &prefix);
 310
 311     /**
 312      * Sets preferred package root.
 313      */
 314     void setDefaultPackageRoot(const QString &packageRoot);
 315
 316     /**
 317      * Called whenever the path changes so that subclasses may take
 318      * package specific actions.
 319      */
 320     virtual void pathChanged();
 321
 322 private:
 323     PackageStructurePrivate * const d;
 324 };
 325
 326 /**
 327  * Register an applet when it is contained in a loadable module
 328  */
 329 #define K_EXPORT_PLASMA_PACKAGESTRUCTURE(libname, classname) \
 330 K_PLUGIN_FACTORY(factory, registerPlugin<classname>();) \
 331 K_EXPORT_PLUGIN(factory("plasma_packagestructure_" #libname)) \
 332 K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION)
 333
 334 } // Plasma namespace
 335 #endif