/*****
*
* TOra - An Oracle Toolkit for DBA's and developers
* Copyright (C) 2003-2005 Quest Software, Inc
* Portions Copyright (C) 2005 Other Contributors
* 
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation;  only version 2 of
* the License is valid for this program.
* 
* 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 General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
*
*      As a special exception, you have permission to link this program
*      with the Oracle Client libraries and distribute executables, as long
*      as you follow the requirements of the GNU GPL in regard to all of the
*      software in the executable aside from Oracle client libraries.
*
*      Specifically you are not permitted to link this program with the
*      Qt/UNIX, Qt/Windows or Qt Non Commercial products of TrollTech.
*      And you are not permitted to distribute binaries compiled against
*      these libraries without written consent from Quest Software, Inc.
*      Observe that this does not disallow linking to the Qt Free Edition.
*
*      You may link this product with any GPL'd Qt library such as Qt/Free
*
* All trademarks belong to their respective owners.
*
*****/

#ifndef TOTOOL_H
#define TOTOOL_H

#include "config.h"

#include <map>

#include <qobject.h>
#include <qstring.h>
#include <qvbox.h>

class toConnection;
class toTimer;

/**
 * Abstract baseclass for tools.
 *
 * This class is the baseclass of all classes defining tools. It
 * contains functions for defining the priority and name of the tool,
 * as well as virtual functions to define it's place in the user
 * interface. Further it contains methods to access configuration
 * settings.
 *
 * To use this class you create a child which is then instantiated once
 * which inserts that tool in the global tool map (See @ref tools). You
 * should never delete a tool unless on exit. Usually tools are instantiated
 * statically in the global scope.
 */

class toTool : public QObject
{
    Q_OBJECT
private:
    /**
     * Name of the tool.
     */
    QCString Name;
    /**
     * Key of the tool, this is used for sorting.
     */
    QCString Key;
    /**
     * Priority, used to determine in which order the tools should be listed.
     */
    int Priority;
    /**
     * A map of @ref Key to tools. Used to keep track of the different tools
     * available.
     */
    static std::map<QCString, toTool *> *Tools;
    /**
     * A map containing the available configuration settings. By convention the
     * character ':' is used to separate parts of the path.
     *
     * @see globalConfig
     * @see globalSetConfig
     * @see config
     * @see setConfig
     */
    static std::map<QCString, QString> *Configuration;
    /**
     * Contain the pixmap of this tool if any. Used for the toolbar and menu entries.
     */
    QPixmap *ButtonPicture;

    /**
     * Load configuration from file.
     */
    static void loadConfig(void);
protected:
    /**
     * Should return the xpm used to create the @ref ButtonPicture.
     */
    virtual const char **pictureXPM(void);
public:
    /**
     * Get the name.
     *
     * @return Name of tool.
     */
    QCString name() const
    {
        return Name;
    }
    /**
     * Get the name.
     *
     * @return Name of tool.
     */
    QCString key() const
    {
        return Key;
    }
    /**
     * Get the priority.
     *
     * @return Priority of tool.
     */
    int priority() const
    {
        return Priority;
    }
    /**
     * This should never be called, but if it is. Erases the tool from the list of
     * available tools. WARNING: It will not remove any of it's open tools.
     */
    ~toTool();

    /**
     * Create a tool. Remember that usually the main window is not created here.
     *
     * @param priority Priority of the created tool.
     * @param name Name of tool.
     */
    toTool(int priority, const char *name);
    /**
     * Get the image to display in the toolbar.
     *
     * @return Pointer to image in toolbar or NULL if no image should be displayed.
     */
    virtual const QPixmap *toolbarImage();
    /**
     * Get the name of the menuitem to be displayed in the menu.
     *
     * @return A string containing the name of the menuentry or NULL if no menuentry should
     *         be created.
     */
    virtual const char *menuItem()
    {
        return NULL;
    }
    /**
     * Get toolbar tip of the toolbar button. Defaults to same as @ref menuItem.
     *
     * @return Toolbar tip string.
     */
    virtual const char *toolbarTip()
    {
        return menuItem();
    }

    /** Check if the tool can handle a specific connection. Default is to only handle
     * connections from the provider Oracle.
     * @return True if connection can be handled.
     */
    virtual bool canHandle(toConnection &conn);
    /**
     * This function is called as a last step after the main widget is created. It could
     * be used to insert the tool pretty much anywhere in the user interface if the toolmenu,
     * toolbar is not sufficient.
     *
     * @param toolid The tool menu id that should be used if it inserts a custom menu entry.
     */
    virtual void customSetup(int toolid);
    /**
     * Create a new tool window.
     *
     * @param parent Parent window, which is the worksheet of the main window.
     * @param connection The database connection that this tool should operate on.
     */
    virtual QWidget *toolWindow(QWidget *parent, toConnection &connection) = 0;
    /**
     * Create and return configuration tab for this tool. The returned widget should also
     * be a childclass of @ref toSettingTab.
     *
     * @return A pointer to the widget containing the setup tab for this tool or NULL of
     * no settings are available.
     */
    virtual QWidget *configurationTab(QWidget *parent);

    /** Display an about dialog for this tool.
     * @param parent The parent widget of the about dialog.
     */
    virtual void about(QWidget *parent);
    /** Indicate whether or not this tool has an about dialog.
     */
    virtual bool hasAbout(void)
    {
        return false;
    }

    /**
     * Get access to the map of tools. Don't modify it. Observe that the index string is not
     * the name of the tool but an internal key used to get tools sorted in the correct
     * priority order.
     *
     * @see Tools
     * @return A reference to the tool map.
     */
    static std::map<QCString, toTool *> &tools(void)
    {
        if (!Tools)
            Tools = new std::map<QCString, toTool *>;
        return *Tools;
    }
    /**
     * Get a pointer to the tool with a specified key.
     *
     * @see Tools
     * @return A pointer to the tool or NULL if tool doesn't exist.
     */
    static toTool *tool(const QCString &key);
    /**
     * Save configuration to file.
     */
    static void saveConfig(void);
    /**
     * Get value of a setting.
     *
     * Setting names are hierachical separated by ':' instead of '/' usually used
     * in filenames. As an example all settings for the tool 'Example' would be
     * under the 'Example:{settingname}' name.
     *
     * @param tag The name of the configuration setting.
     * @param def Default value of the setting, if it is not available.
     */
    static const QString &globalConfig(const QCString &tag, const QCString &def);
    /**
     * Change a setting. Depending on the implementation this can change the
     * contents on disk or not.
     *
     * Setting names are hierachical separated by ':' instead of '/' usually used
     * in filenames. As an example all settings for the tool 'Example' would be
     * under the 'Example:{settingname}' name.
     *
     * @param tag The name of the configuration setting.
     * @param def Contents of this setting.
     */
    static void globalSetConfig(const QCString &tag, const QString &value);
    /**
     * Remove a setting. Can be usefull for removing sensetive information.
     * @param tag The name of the configuration setting to remove.
     */
    static void globalEraseConfig(const QCString &tag);

    /**
     * Get tool specific settings.
     *
     * Setting names are hierachical separated by ':' instead of '/' usually used
     * in filenames. As an example all settings for the tool 'Example' would be
     * under the 'Example:{settingname}' name.
     *
     * @param tag The name of the configuration setting.
     * @param def Contents of this setting.
     */
    const QString &config(const QCString &tag, const QCString &def);
    /**
     * Change toolspecific setting. Depending on the implementation this can change the
     * contents on disk or not.
     *
     * Setting names are hierachical separated by ':' instead of '/' usually used
     * in filenames. As an example all settings for the tool 'Example' would be
     * under the 'Example:{settingname}' name.
     *
     * @param tag The name of the configuration setting.
     * @param def Default value of the setting, if it is not available.
     */
    void setConfig(const QCString &tag, const QString &value);
    /**
     * Remove a toolspecific setting. Can be usefull for removing sensetive information.
     * @param tag The name of the configuration setting to remove.
     */
    void eraseConfig(const QCString &tag);
    /**
     * Load a string to string map from file saved by the @ref saveMap function.
     * @param filename Filename to load
     * @param map Reference to the map to fill with the new values.
     */
    static void loadMap(const QString &filename, std::map<QCString, QString> &map);
    /**
     * Save a string to string map to file.
     * @see loadMap
     * @param filename Filename to load
     * @param map Reference to the map to fill with the new values.
     */
    static bool saveMap(const QString &filename, std::map<QCString, QString> &map);
public slots:
    /**
     * Create a window of the current tool. This function sets up a toolwindow for
     * this tool. It calls the @ref toolWindow function to get widget and sets it
     * up properly.
     */
    void createWindow(void);
};

#include "tohelp.h"

/**
 * Abstract baseclass for widgets defining tool settings.
 */

class toSettingTab : public toHelpContext
{
public:
    /**
     * Default constructor.
     * @param ctx Help context for this setting tab.
     */
    toSettingTab(const QString &ctx)
            : toHelpContext(ctx)
    { }
    /**
     * This function is called to save the contents of the widget when
     * a user has pressed the ok button of the dialog. It should simply
     * save the values in the dialog to the appropriate configuration
     * entry using the @ref toTool::setConfig function.
     */
    virtual void saveSetting(void) = 0;
};

/** This class is used to hold connections for @ref toResult classes.
 * Must be multiply inherited by a widget otherwise it will go kaboom.
 * It will dynamic cast itself to a QWidget from time to time so if that
 * doesn't resolve correctly it will not work.
 */
class toConnectionWidget
{
    toConnection *Connection;
    QWidget *Widget;
public:
    /** Constructor with the connection it should be set to initially.
     */
    toConnectionWidget(toConnection &conn, QWidget *widget);
    /** Constructor without a connection. Will inherit the connection from a parent connection widget.
     */
    toConnectionWidget(QWidget *widget);
    /** Destructor.
     */
    virtual ~toConnectionWidget();
    /** Change connection of the widget.
     */
    virtual void setConnection(toConnection &conn);
    /** Get the connection it is pointed to.
     */
    virtual toConnection &connection();
};

/** Simple baseclass for widgets defining the main tool widget. It is in
 * no way mandatory and all it does is register the widget in the connetion.
 */
class toToolWidget : public QVBox, public toHelpContext, public toConnectionWidget
{
    Q_OBJECT
    toTimer *Timer;
    toTool &Tool;
private slots:
    void parentConnection(void);
signals:
    /** Emitted when the connection is changed.
     */
    void connectionChange(void);
public:
    /** Create widget.
     * @param ctx Help context for this tool.
     * @param parent Parent widget.
     * @param conn Connection of widget.
     * @param name Name of widget.
     */
    toToolWidget(toTool &tool,
                 const QString &ctx,
                 QWidget *parent,
                 toConnection &conn,
                 const char *name = NULL);
    ~toToolWidget();
    /** Get the current connection.
     * @return Reference to connection.
     */
    toConnection &connection()
    {
        return toConnectionWidget::connection();
    }
    /** Get the tool for this tool widget.
     * @return Reference to a tool object.
     */
    toTool &tool(void)
    {
        return Tool;
    }
    /** Check if this tool can handle a specific connection.
     * @param provider Name of connection.
     * @return True if connection is handled.
     */
    virtual bool canHandle(toConnection &conn)
    {
        return Tool.canHandle(conn);
    }
    /** Change connection of tool.
     */
    void setConnection(toConnection &conn);
    /** Get timer of tool. Used by some results to get update time.
     * @return Pointer to a timer object.
     */
    toTimer *timer(void);

    /** Export data to a map.
     * @param data A map that can be used to recreate the data of a chart.
     * @param prefix Prefix to add to the map.
     */
    virtual void exportData(std::map<QCString, QString> &data, const QCString &prefix);
    /** Import data
     * @param data Data to read from a map.
     * @param prefix Prefix to read data from.
     */
    virtual void importData(std::map<QCString, QString> &data, const QCString &prefix);
};

#endif