/*
 *   Copyright 2011 Kevin Kofler <kevin.kofler@chello.at>
 *
 *   This program 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, or
 *   (at your option) any later version.
 *
 *   This program 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 General Public License for more details
 *
 *   You should have received a copy of the GNU Library General Public
 *   License along with this program; if not, write to the
 *   Free Software Foundation, Inc.,
 *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */

#ifndef PLASMA_COMPONENTINSTALLER_H
#define PLASMA_COMPONENTINSTALLER_H

class QString;
class QWidget;

namespace Plasma
{

class ComponentInstallerPrivate;

/**
 * @class ComponentInstaller plasma/private/componentinstaller_p.h
 *
 * @short This class provides a generic API for installation of components.
 *
 * @internal
 *
 * Plasma::ComponentInstaller allows searching for a missing data or script
 * engine by name, and allowing the user to install the missing service.
 * Currently, PackageKit is supported as the mechanism to install components,
 * but more mechanisms could be supported in the future through the same API.
 *
 * @since 4.8
 */
class ComponentInstaller
{
public:
    /**
     * Singleton pattern accessor.
     */
    static ComponentInstaller *self();

    /**
     * Installs a missing component asynchronously.
     *
     * By default, this method will cache requested components and not
     * prompt again for the same engine in the same session. The force
     * parameter can be used to disable this mechanism, e.g. when the user
     * just installed a new widget written in a scripting language, and so
     * is likely to want the script engine installed after all.
     *
     * In the case of on-demand installation, this will unfortunately not
     * allow the call which triggered the missing component lookup to
     * succeed, but we cannot afford to block all of Plasma until the
     * mechanism is done installing the service.
     *
     * This function does nothing if PackageKit integration was disabled at
     * compile time.
     *
     * @param type the type of the component, should be "scriptengine" or
     *             "dataengine"
     * @param name the name of the component
     * @param parent a parent widget, used to set the wid for PackageKit
     * @param force whether to always prompt, even if recently prompted
     */
    void installMissingComponent(const QString &type, const QString &name,
                                 QWidget *parent = 0, bool force = false);

private:
    /**
     * Default constructor. The singleton method self() is the
     * preferred access mechanism.
     */
    ComponentInstaller();
    ~ComponentInstaller();

    ComponentInstallerPrivate *const d;

    friend class ComponentInstallerSingleton;
};

} // namespace Plasma

#endif // multiple inclusion guard
