/****************************************************************************** * Copyright 2007 by Aaron Seigo * * * * This library is free software; you can redistribute it and/or * * modify it under the terms of the GNU Library General Public * * License as published by the Free Software Foundation; either * * version 2 of the License, or (at your option) any later version. * * * * This library is distributed in the hope that it will be useful, * * but WITHOUT ANY WARRANTY; without even the implied warranty of * * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * * Library General Public License for more details. * * * * You should have received a copy of the GNU Library General Public License * * along with this library; see the file COPYING.LIB. If not, write to * * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, * * Boston, MA 02110-1301, USA. * *******************************************************************************/ #ifndef PLASMA_PACKAGESTRUCTURE_H #define PLASMA_PACKAGESTRUCTURE_H #include #include #include #include #include #include #include "packagemetadata.h" class KConfigBase; namespace Plasma { class PackageStructurePrivate; /** * @class PackageStructure plasma/packagestructure.h * * @short A description of the expected file structure of a given package type * * PackageStructure defines what is in a package. This information is used * to create packages and provides a way to programatically refer to contents. * * An example usage of this class might be: * @code PackageStructure structure; structure.addDirectoryDefinition("images", "pics/", i18n("Images")); QStringList mimeTypes; mimeTypes << "image/svg" << "image/png" << "image/jpeg"; structure.setMimetypes("images", mimeTypes); structure.addDirectoryDefinition("scripts", "code/", i18n("Executable Scripts")); mimeTypes.clear(); mimeTypes << "text/\*"; structure.setMimetypes("scripts", mimeTypes); structure.addFileDefinition("mainscript", "code/main.js", i18n("Main Script File")); structure.setRequired("mainscript", true); @endcode * One may also choose to create a subclass of PackageStructure and include the setup * in the constructor. * * Either way, PackageStructure creates a sort of "contract" between the packager and * the application which is also self-documenting. **/ class PLASMA_EXPORT PackageStructure : public QObject, public QSharedData { Q_OBJECT public: typedef KSharedPtr Ptr; /** * Default constructor for a package structure definition * * @arg type the type of package. This is often application specific. **/ explicit PackageStructure(QObject *parent = 0, const QString &type = i18nc("A non-functional package", "Invalid")); /** * Destructor **/ virtual ~PackageStructure(); /** * Assignment operator **/ PackageStructure &operator=(const PackageStructure &rhs); /** * Loads a package format by name. * * @arg format If not empty, attempts to locate the given format, either * from built-ins or via plugins. * @return a package that matches the format, if available. The caller * is responsible for deleting the object. */ static PackageStructure::Ptr load(const QString &packageFormat); /** * Type of package this structure describes **/ QString type() const; /** * The directories defined for this package **/ QList directories() const; /** * The required directories defined for this package **/ QList requiredDirectories() const; /** * The individual files, by key, that are defined for this package **/ QList files() const; /** * The individual required files, by key, that are defined for this package **/ QList requiredFiles() const; /** * Adds a directory to the structure of the package. It is added as * a not-required element with no associated mimeTypes. * * Starting in 4.6, if an entry with the given key * already exists, the path is added to it as a search alternative. * * @param key used as an internal label for this directory * @param path the path within the package for this directory * @param name the user visible (translated) name for the directory **/ void addDirectoryDefinition(const char *key, const QString &path, const QString &name); /** * Adds a file to the structure of the package. It is added as * a not-required element with no associated mimeTypes. * * Starting in 4.6, if an entry with the given key * already exists, the path is added to it as a search alternative. * * @param key used as an internal label for this file * @param path the path within the package for this file * @param name the user visible (translated) name for the file **/ void addFileDefinition(const char *key, const QString &path, const QString &name); /** * Removes a definition from the structure of the package. * @since 4.6 * @param key the internal label of the file or directory to remove */ void removeDefinition(const char *key); /** * @return path relative to the package root for the given entry * @deprecatd use searchPaths instead **/ QString path(const char *key) const; /** * @return a list of paths relative to the package root for the given entry. * They are orted by importance: when searching for a file the paths * will be searched in order * @since 4.6 **/ QStringList searchPath(const char *key) const; /** * Get the list of files of a given type. * * @arg key the type of file to look for * @return list of files by name * @since 4.3 */ QStringList entryList(const char *key); /** * @return user visible name for the given entry **/ QString name(const char *key) const; /** * Sets whether or not a given part of the structure is required or not. * The path must already have been added using addDirectoryDefinition * or addFileDefinition. * * @param key the entry within the package * @param required true if this entry is required, false if not */ void setRequired(const char *key, bool required); /** * @return true if the item at path exists and is required **/ bool isRequired(const char *key) const; /** * Defines the default mimeTypes for any definitions that do not have * associated mimeTypes. Handy for packages with only one or predominantly * one file type. * * @param mimeTypes a list of mimeTypes **/ void setDefaultMimetypes(QStringList mimeTypes); /** * Define mimeTypes for a given part of the structure * The path must already have been added using addDirectoryDefinition * or addFileDefinition. * * @param key the entry within the package * @param mimeTypes a list of mimeTypes **/ void setMimetypes(const char *key, QStringList mimeTypes); /** * @return the mimeTypes associated with the path, if any **/ QStringList mimeTypes(const char *key) const; /** * Sets the path to the package. Useful for package formats * which do not have well defined contents prior to installation. */ void setPath(const QString &path); /** * @return the path to the package, or QString() if none */ QString path() const; /** * Read a package structure from a config file. */ void read(const KConfigBase *config); /** * Write this package structure to a config file. */ void write(KConfigBase *config) const; /** * Installs a package matching this package structure. By default installs a * native Plasma::Package. * * @param archivePath path to the package archive file * @param packageRoot path to the directory where the package should be * installed to * @return true on successful installation, false otherwise **/ virtual bool installPackage(const QString &archivePath, const QString &packageRoot); /** * Uninstalls a package matching this package structure. * * @arg packageName the name of the package to remove * @arg packageRoot path to the directory where the package should be installed to * @return true on successful removal of the package, false otherwise */ virtual bool uninstallPackage(const QString &packageName, const QString &packageRoot); /** * When called, the package plugin should display a window to the user * that they can use to browser, select and then install widgets supported by * this package plugin with. * * The user interface may be an in-process dialog or an out-of-process application. * * When the process is complete, the newWidgetBrowserFinished() signal must be * emitted. * * @param parent the parent widget to use for the widget */ virtual void createNewWidgetBrowser(QWidget *parent = 0); /** * @return the prefix inserted between the base path and content entries * @deprecated use contentsPrefixPaths() instead. */ KDE_DEPRECATED QString contentsPrefix() const; /** * @return the prefix paths inserted between the base path and content entries, in order of priority. * When searching for a file, all paths will be tried in order. * @since 4.6 */ QStringList contentsPrefixPaths() const; /** * @return preferred package root. This defaults to plasma/plasmoids/ */ QString defaultPackageRoot() const; /** * @return service prefix used in desktop files. This defaults to plasma-applet- */ QString servicePrefix() const; /** * Sets service prefix. */ void setServicePrefix(const QString &servicePrefix); /** * @return the package metadata object. */ virtual PackageMetadata metadata() const; /** * @return true if paths/symlinks outside the package itself should be followed. * By default this is set to false for security reasons. */ bool allowExternalPaths() const; Q_SIGNALS: /** * Emitted when the new widget browser process completes. */ void newWidgetBrowserFinished(); protected: /** * Sets whether or not external paths/symlinks can be followed by a package * @arg allow true if paths/symlinks outside of the package should be followed, * false if they should be rejected. */ void setAllowExternalPaths(bool allow); /** * Sets the prefix that all the contents in this package should * appear under. This defaults to "contents/" and is added automatically * between the base path and the entries as defined by the package * structure * * @arg prefix the directory prefix to use * @deprecated use setContentsPrefixPaths() instead. */ KDE_DEPRECATED void setContentsPrefix(const QString &prefix); /** * Sets the prefixes that all the contents in this package should * appear under. This defaults to "contents/" and is added automatically * between the base path and the entries as defined by the package * structure. Multiple entries can be added. * In this case each file request will be searched in all prefixes in order, * and the first found will be returned. * * @arg prefix paths the directory prefix to use * @since 4.6 */ void setContentsPrefixPaths(const QStringList &prefixPaths); /** * Sets preferred package root. */ void setDefaultPackageRoot(const QString &packageRoot); /** * Called whenever the path changes so that subclasses may take * package specific actions. */ virtual void pathChanged(); private: PackageStructurePrivate * const d; }; /** * Register an applet when it is contained in a loadable module */ #define K_EXPORT_PLASMA_PACKAGESTRUCTURE(libname, classname) \ K_PLUGIN_FACTORY(factory, registerPlugin();) \ K_EXPORT_PLUGIN(factory("plasma_packagestructure_" #libname)) \ K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION) } // Plasma namespace #endif